emo/busybox
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

examples: update var_service/README

Browse Source 
Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>
This commit is contained in:
Denys Vlasenko 2016-10-14 18:22:50 +02:00
parent 662634b829
commit ee2d19445b
1 changed files with 129 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
examples/var_service/README
View File

@ -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
env - PATH=... <other vars=...> runsvdir /var/service &
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.
from one of system startup scripts. (Google "man runsvdir" and "man runsv"
for more info about these tools).
You can try or debug an individual service by running its SERVICE_DIR/run script.
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
In runit parlance a "service" is simply a directory containing a script
named "run".
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/.
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.
Some existing examples:
var_service/dhcp_if -
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.
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
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).
of the parent directory as interface name).
var_service/ifplugd_if -
watches link status of interface if. Downs and ups /var/service/dhcp_if
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.