examples/var_service/README

   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
  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
  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
  27 of the parent directory as interface name). When IP address is obtained or lost,
  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.
  30 This example can be used as a template for other dynamic network link services
  31 (ppp/vpn/zcip).
  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 to determine router IP. Pings it.
  40 If ping fails, restarts /var/service/dhcp_if service.
  41 Basically, an example of watchdog service for networks which are not reliable
  42 and need babysitting.
  43
  44 var_service/fw -
  45 A *one-shot* service which reconfigures network based on current known state
  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.
  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).
  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
  59         # Make ourself one-shot
  60         sv o .
  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.