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 Some existing examples:
  13
  14 var_service/dhcp_if -
  15 controls a udhcpc instance which provides dhpc-assigned IP
  16 address on interface named "if". Copy/rename this directory as needed to run
  17 udhcpc on other interfaces (var_service/dhcp_if/run script uses _foo suffix
  18 or the parent directory as interface name). When IP address is obtained or lost,
  19 var_service/dhcp_if/dhcp_handler is run. It saves new config data to
  20 /var/run/service/fw/dhcp_if.ipconf and (re)starts /var/service/fw service.
  21
  22 var_service/ifplugd_if -
  23 watches link status of interface if. Downs and ups /var/service/dhcp_if
  24 service accordingly. In effect, it allows you to unplug/plug-to-different-network
  25 and have your IP properly re-negotiated at once.
  26
  27 var_service/dhcp_if_pinger -
  28 Uses var_service/dhcp_if's data (/var/service/dhcp_if/dhcp_if.out file)
  29 to determine router IP. Pings it. If ping fails, restarts /var/service/dhcp_if
  30 service. Basically, an example of watchdog service for networks
  31 which are not reliable and need babysitting.
  32
  33 var_service/fw -
  34 An *one-shot* service which reconfigures network based on current known state
  35 of ALL interfaces. Uses conf/*.ipconf (static config) and /var/run/service/fw/*.ipconf
  36 (dynamic config from dhcp/ppp/vpn/etc) to determine what to do.
  37 One-shot-ness of this service means that it shuts itself off after single run.
  38
  39 However, any dhcp/ppp/vpn or similar service can restart it anytime
  40 when it senses the change in network configuration.
  41 This even works while fw service runs: if dhcp signals fw to (re)start
  42 while fw runs, fw will not stop after its execution, but will re-execute once,
  43 picking up dhcp's new configuration.
  44 This is achieved very simply by having
  45 # Make ourself one-shot
  46 sv o .
  47 at the very beginning of fw/run script, not at the end.
  48 Therefore, any "sv u /var/run/service/fw" command by any other
  49 script "undoes" o(ne-shot) command if fw still runs, thus
  50 runsv will rerun it; or start it in a normal way if fw is not running.
  51
  52 System administrators are expected to edit fw/run script, since
  53 network configuration needs are likely to be very complex and different
  54 for non-trivial installations.