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