blob: 9ad1b2581bac06418867084242f6c23fcd0d4a62 [file] [log] [blame]
Denys Vlasenko75bb3322010-12-06 15:13:58 +01001In many cases, network configuration makes it necessary to run several daemons:
2dhcp, zeroconf, ppp, openvpn and such. They need to be controlled,
3and in many cases you also want to babysit them. runsvdir is a good tool for this.
4examples/var_service directory provides a few examples. It is meant to be used
5this way: copy it somewhere (say, /var/service) and run something like
6
7env - PATH=... <other vars=...> runsvdir /var/service &
8
9from one of system startup scripts. (Google "man runsvdir" and "man runsv"
10for more info about these tools).
11
Denys Vlasenko192c14b2014-02-21 12:55:43 +010012You can try or debug an individual service by running its SERVICE_DIR/run script.
13In this case, its stdout and stderr go to your terminal.
14
15You can also run "runsv SERVICE_DIR", which runs both the service
16and its logger service (SERVICE_DIR/log/run) if logger service exists.
17If logger service exists, the output will go to it instead of the terminal.
18
19"runsvdir DIR" merely runs "runsv SERVICE_DIR" for every subdirectory in DIR.
20
Denys Vlasenko75bb3322010-12-06 15:13:58 +010021Some existing examples:
22
23var_service/dhcp_if -
24controls a udhcpc instance which provides dhpc-assigned IP
25address on interface named "if". Copy/rename this directory as needed to run
26udhcpc on other interfaces (var_service/dhcp_if/run script uses _foo suffix
Denys Vlasenko30997442010-12-06 15:44:13 +010027of the parent directory as interface name). When IP address is obtained or lost,
Denys Vlasenko75bb3322010-12-06 15:13:58 +010028var_service/dhcp_if/dhcp_handler is run. It saves new config data to
29/var/run/service/fw/dhcp_if.ipconf and (re)starts /var/service/fw service.
Denys Vlasenkobc3cdf82010-12-06 15:42:44 +010030This example can be used as a template for other dynamic network link services
31(ppp/vpn/zcip).
Denys Vlasenko75bb3322010-12-06 15:13:58 +010032
33var_service/ifplugd_if -
34watches link status of interface if. Downs and ups /var/service/dhcp_if
35service accordingly. In effect, it allows you to unplug/plug-to-different-network
36and have your IP properly re-negotiated at once.
37
38var_service/dhcp_if_pinger -
39Uses var_service/dhcp_if's data (/var/service/dhcp_if/dhcp_if.out file)
40to determine router IP. Pings it. If ping fails, restarts /var/service/dhcp_if
41service. Basically, an example of watchdog service for networks
42which are not reliable and need babysitting.
43
44var_service/fw -
Denys Vlasenko1f3709e2010-12-08 06:08:47 +010045A *one-shot* service which reconfigures network based on current known state
Denys Vlasenko75bb3322010-12-06 15:13:58 +010046of ALL interfaces. Uses conf/*.ipconf (static config) and /var/run/service/fw/*.ipconf
47(dynamic config from dhcp/ppp/vpn/etc) to determine what to do.
48One-shot-ness of this service means that it shuts itself off after single run.
Denys Vlasenkobc3cdf82010-12-06 15:42:44 +010049IOW: it is not a constantly running daemon sort of thing.
50It starts, it configures the network, it shuts down, all done
51(unlike infamous NetworkManagers which sit in RAM forever, doing hell knows what).
Denys Vlasenko75bb3322010-12-06 15:13:58 +010052
53However, any dhcp/ppp/vpn or similar service can restart it anytime
54when it senses the change in network configuration.
55This even works while fw service runs: if dhcp signals fw to (re)start
56while fw runs, fw will not stop after its execution, but will re-execute once,
57picking up dhcp's new configuration.
58This is achieved very simply by having
Denys Vlasenko192c14b2014-02-21 12:55:43 +010059 # Make ourself one-shot
60 sv o .
Denys Vlasenko75bb3322010-12-06 15:13:58 +010061at the very beginning of fw/run script, not at the end.
62Therefore, any "sv u /var/run/service/fw" command by any other
63script "undoes" o(ne-shot) command if fw still runs, thus
64runsv will rerun it; or start it in a normal way if fw is not running.
65
66System administrators are expected to edit fw/run script, since
67network configuration needs are likely to be very complex and different
68for non-trivial installations.