From 90b12bd71bb9fc79a4640b9112c13ef529d0196a Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 5 Dec 2014 22:26:11 +0000 Subject: Initial commit --- doc/s6-svscan.html | 176 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 doc/s6-svscan.html (limited to 'doc/s6-svscan.html') diff --git a/doc/s6-svscan.html b/doc/s6-svscan.html new file mode 100644 index 0000000..4a7e800 --- /dev/null +++ b/doc/s6-svscan.html @@ -0,0 +1,176 @@ + + + + + s6: the s6-svscan program + + + + + + +

+s6
+Software
+www.skarnet.org +

+ +

The s6-svscan program

+ +

+s6-svscan starts and monitors a collection of s6-supervise +processes, each of these processes monitoring a single service. It is designed to be either +the root or a branch of a supervision tree. +

+ +

Interface

+ +

+     s6-svscan [ -c max ] [ -t rescan ] [ scandir ]
+

+ +

If given a scandir argument, s6-svscan switches to it. Else it uses +its current directory as scan directory.
It exits 100 if another s6-svscan process is already monitoring this +scan directory.
If the ./.s6-svscan control directory does not exist, +s6-svscan creates it. However, it is recommended to already have a .s6-svscan +subdirectory in your scan directory, because s6-svscan may try and execute into the +.s6-svscan/crash or .s6-svscan/finish files at some point - so those +files should exist and be executable.
From this point on, s6-svscan never dies. It tries its best to keep +control of what's happening. In case of a major system call failure, which means +that the kernel or hardware is broken in some fashion, it executes into the +.s6-svscan/crash program. (But if that execution fails, s6-svscan exits +111.)
s6-svscan performs an initial scan of its scan directory.
s6-svscan then occasionally runs scans or reaps, +see below.
s6-svscan runs until it is told to stop via +s6-svscanctl, or a signal. +Then it executes into the .s6-svscan/finish program. The program is +given an argument that depends on the s6-svscanctl options that were used.
If that execution fails, s6-svscan falls back on a .s6-svscan/crash +execution.

+ +

Options

+ +

-c max : maintain services for up to max +service directories. Default is 500. Lower limit is 2. There is no upper limit, but: +
- The higher max is, the more stack memory s6-svscan will use, +approximately 50 bytes per service.
- s6-svscan uses 2 file descriptors per logged service.
+ It is the admin's responsibility to make sure that s6-svscan has enough available +descriptors to function properly and does not exceed its stack limit. The default +of 500 is safe and provides enough room for every reasonable system.
-t rescan : perform a scan every rescan +milliseconds. If rescan is 0, automatic scans are never performed after +the first one and s6-svscan will only detect new services when told to via a +s6-svscanctl -a command. The default rescan +value is 5000, for compatibility with daemontools' +svscan, which performs a +scan (and a reap) every 5 seconds. It is strongly discouraged to set +rescan to a positive value under 500.

+ +

Signals

+ +

+ s6-svscan reacts to the following signals: +

+ +

SIGCHLD : triggers the reaper.
SIGALRM : triggers the scanner.
SIGTERM : acts as if a s6-svscanctl -t command had been received.
SIGHUP : acts as if a s6-svscanctl -h command had been received.
SIGQUIT : acts as if a s6-svscanctl -q command had been received.
SIGABRT : acts as if a s6-svscanctl -b command had been received.
SIGINT : acts as if a s6-svscanctl -i command had been received.

+ +

The reaper

+ +

+ Upon receipt of a SIGCHLD, or a s6-svscanctl -z +command, s6-svscan runs a reaper routine. +

+ +

+The reaper acknowledges (via some +wait() +function), without blocking, every terminated child of s6-svscan, even ones it does not +know it has. This is especially important when s6-svscan is +run as process 1. +

+ +

+ If the dead child is a s6-supervise process watched +by s6-svscan, and the last scan flagged that process as active, then it is restarted +one second later. +

+ +

The scanner

+ +

+ Every rescan milliseconds, or upon receipt of a SIGALRM or a +s6-svscanctl -a command, s6-svscan runs a +scanner routine. +

+ +

+ The scanner scans the current directory for subdirectories (or symbolic links +to directories), which must be service directories. +It skips names starting with dots. It will not create services for more than +max subdirectories. +

+ +

+ For every new subdirectory dir it finds, the scanner spawns a +s6-supervise process on it. If +dir/log exists, it spawns a s6-supervise process on +both dir and dir/log, and maintains a +never-closing pipe from the service's stdout to the logger's stdin. +This is starting the service, with or without a corresponding +logger. +Every service the scanner finds is flagged as "active". +

+ +

+ The scanner remembers the services it found. If a service has been +started in an earlier scan, but the current scan can't find the corresponding +directory, the service is then flagged as inactive. No command is sent +to stop inactive s6-supervise processes (unless the administrator +uses s6-svscanctl -n), but inactive +s6-supervise processes will not be restarted if they die. +

+ +

Implementation notes

+ +

s6-svscan is designed to run until the machine is shut down. It is +also designed as a suitable candidate for +process 1. So, it goes out of its way to +stay alive, even in dire situations. When it encounters a fatal situation, +something it really cannot handle, it executes into .s6-svscan/crash +instead of dying; when it is told to exit, it executes into +.s6-svscan/finish. Administrators should make sure to design +appropriate crash and finish routines.
s6-svscan is a fully asynchronous state machine. It will read and +process commands at any time, even when the computer is in trouble.
s6-svscan does not use malloc(). That means it will never leak +memory. However, s6-svscan uses opendir(), and most opendir() +implementations internally use heap memory - so unfortunately, it's impossible +to guarantee that s6-svscan does not use heap memory at all.
When run with the -t0 option, s6-svscan never polls, +it only wakes up on notifications, just like s6-supervise. The s6 supervision +tree can be used in energy-critical environments.

+ + + -- cgit 1.4.1