ee2d19445
Denys Vlasenko
2016-10-14
Subject
examples: update var_service/README
Binary
No binary (build failed)
Architecture & Compiler Flags
—
Build Log
(log yok)
Commit Diff GitHub →
examples/var_service/README+130 -24
| @@ -1,50 +1,149 @@ | |
| - | In many cases, network configuration makes it necessary to run several daemons: |
| - | dhcp, zeroconf, ppp, openvpn and such. They need to be controlled, |
| - | and in many cases you also want to babysit them. runsvdir is a good tool for this. |
| - | examples/var_service directory provides a few examples. It is meant to be used |
| - | this way: copy it somewhere (say, /var/service) and run something like |
| + | Daemontools and runit |
| + | |
| + | Tired of PID files, needing root access, and writing init scripts just |
| + | to have your UNIX apps start when your server boots? Want a simpler, |
| + | better alternative that will also restart them if they crash? If so, |
| + | this is an introduction to process supervision with runit/daemontools. |
| + | |
| + | |
| + | Background |
| + | |
| + | Classic init scripts, e.g. /etc/init.d/apache, are widely used for |
| + | starting processes at system boot time, when they are executed by init. |
| + | Sadly, init scripts are cumbersome and error-prone to write, they must |
| + | typically be edited and run as root, and the processes they launch do |
| + | not get restarted automatically if they crash. |
| + | |
| + | In an alternative scheme called "process supervision", each important |
| + | process is looked after by a tiny supervising process, which deals with |
| + | starting and stopping the important process on request, and re-starting |
| + | it when it exits unexpectedly. Those supervising processes can in turn |
| + | be supervised by other supervising processes. |
| + | |
| + | Dan Bernstein wrote the process supervision toolkit, "daemontools", |
| + | which is a set of small, reliable programs that cooperate in the |
| + | UNIX tradition to manage process supervision trees. |
| + | |
| + | Runit is a more conveniently licensed and more actively maintained |
| + | reimplementation of daemontools, written by Gerrit Pape. |
| + | |
| + | Here I’ll use runit, however, the ideas are the same for other |
| + | daemontools-like projects (there are several). |
| + | |
| + | |
| + | Service directories and scripts |
| - | env - PATH=... <other vars=...> runsvdir /var/service & |
| + | In runit parlance a "service" is simply a directory containing a script |
| + | named "run". |
| - | from one of system startup scripts. (Google "man runsvdir" and "man runsv" |
| - | for more info about these tools). |
| + | There are just two key programs in runit. Firstly, runsv supervises the |
| + | process for an individual service. Service directories themselves sit |
| + | inside a containing directory, and the runsvdir program supervises that |
| + | directory, running one child runsv process for the service in each |
| + | subdirectory. Out of the box on Debian, for example, an instance of |
| + | runsvdir supervises services in subdirectories of /var/service/. |
| - | You can try or debug an individual service by running its SERVICE_DIR/run script. |
| + | If /var/service/log/ exists, runsv will supervise two services, |
| + | and will connect stdout of main service to the stdin of log service. |
| + | This is primarily used for logging. |
| + | |
| + | You can debug an individual service by running its SERVICE_DIR/run script. |
| In this case, its stdout and stderr go to your terminal. | |
| You can also run "runsv SERVICE_DIR", which runs both the service | |
| and its logger service (SERVICE_DIR/log/run) if logger service exists. | |
| If logger service exists, the output will go to it instead of the terminal. | |
| - | "runsvdir DIR" merely runs "runsv SERVICE_DIR" for every subdirectory in DIR. |
| + | "runsvdir /var/service" merely runs "runsv SERVICE_DIR" for every subdirectory |
| + | in /var/service. |
| + | |
| + | |
| + | Examples |
| + | |
| + | This directory contains some examples of services: |
| + | |
| + | var_service/getty_<tty> |
| + | |
| + | Runs a getty on <tty>. (run script looks at $PWD and extracts suffix |
| + | after "_" as tty name). Create copies (or symlinks) of this directory |
| + | with different names to run many gettys on many ttys. |
| + | |
| + | var_service/gpm |
| + | |
| + | Runs gpm, the cut and paste utility and mouse server for text consoles. |
| + | |
| + | var_service/inetd |
| + | |
| + | Runs inetd. This is an example of a service with log. Log service |
| + | writes timestamped, rotated log data to /var/log/service/inetd/* |
| + | using "svlogd -tt". p_log and w_log scripts demonstrage how you can |
| + | "page log" and "watch log". |
| + | |
| + | Other services which have logs handle them in the same way. |
| - | Some existing examples: |
| + | var_service/nmeter |
| + | |
| + | Runs nmeter '%t %c ....' with output to /dev/tty9. This gives you |
| + | a 1-second sampling of server load and health on a dedicated text console. |
| + | |
| + | |
| + | Networking examples |
| + | |
| + | In many cases, network configuration makes it necessary to run several daemons: |
| + | dhcp, zeroconf, ppp, openvpn and such. They need to be controlled, |
| + | and in many cases you also want to babysit them. |
| + | |
| + | They present a case where different services need to control (start, stop, |
| + | restart) eact other. |
| + | |
| + | var_service/dhcp_if |
| - | var_service/dhcp_if - |
| controls a udhcpc instance which provides dhpc-assigned IP | |
| address on interface named "if". Copy/rename this directory as needed to run | |
| udhcpc on other interfaces (var_service/dhcp_if/run script uses _foo suffix | |
| - | of the parent directory as interface name). When IP address is obtained or lost, |
| - | var_service/dhcp_if/dhcp_handler is run. It saves new config data to |
| - | /var/run/service/fw/dhcp_if.ipconf and (re)starts /var/service/fw service. |
| - | This example can be used as a template for other dynamic network link services |
| - | (ppp/vpn/zcip). |
| - | |
| - | var_service/ifplugd_if - |
| - | watches link status of interface if. Downs and ups /var/service/dhcp_if |
| + | of the parent directory as interface name). |
| + | |
| + | When IP address is obtained or lost, var_service/dhcp_if/dhcp_handler is run. |
| + | It saves new config data to /var/run/service/fw/dhcp_if.ipconf and (re)starts |
| + | /var/service/fw service. This example can be used as a template for other |
| + | dynamic network link services (ppp/vpn/zcip). |
| + | |
| + | This is an example of service with has a "finish" script. If downed ("sv d"), |
| + | "finish" is executed. For this service, it removes DHCP address from |
| + | the interface. |
| + | |
| + | var_service/zcip_if |
| + | |
| + | Zeroconf IP service: assigns a 169.254.x.y/16 address to interface "if". |
| + | This allows to talk to other divices on a network without DHCP server |
| + | (if they also assign 169.254 addresses to themselves). |
| + | |
| + | var_service/ifplugd_if |
| + | |
| + | Watches link status of interface "if". Downs and ups /var/service/dhcp_if |
| service accordingly. In effect, it allows you to unplug/plug-to-different-network | |
| and have your IP properly re-negotiated at once. | |
| - | var_service/dhcp_if_pinger - |
| + | var_service/dhcp_if_pinger |
| + | |
| Uses var_service/dhcp_if's data to determine router IP. Pings it. | |
| If ping fails, restarts /var/service/dhcp_if service. | |
| Basically, an example of watchdog service for networks which are not reliable | |
| and need babysitting. | |
| - | var_service/fw - |
| - | A *one-shot* service which reconfigures network based on current known state |
| - | of ALL interfaces. Uses conf/*.ipconf (static config) and /var/run/service/fw/*.ipconf |
| + | var_service/supplicant_if |
| + | |
| + | Wireless supplicant (wifi association and encryption daemon) service for |
| + | inteface "if". |
| + | |
| + | var_service/fw |
| + | |
| + | This is an example of *one-shot* service. |
| + | |
| + | It reconfigures network based on current known state of ALL interfaces. |
| + | Uses conf/*.ipconf (static config) and /var/run/service/fw/*.ipconf |
| (dynamic config from dhcp/ppp/vpn/etc) to determine what to do. | |
| + | |
| One-shot-ness of this service means that it shuts itself off after single run. | |
| IOW: it is not a constantly running daemon sort of thing. | |
| It starts, it configures the network, it shuts down, all done | |
| @@ -66,3 +165,10 @@ runsv will rerun it; or start it in a normal way if fw is not running. | |
| System administrators are expected to edit fw/run script, since | |
| network configuration needs are likely to be very complex and different | |
| for non-trivial installations. | |
| + | |
| + | var_service/ftpd |
| + | var_service/httpd |
| + | var_service/tftpd |
| + | var_service/ntpd |
| + | |
| + | Examples of typical network daemons. |