Supervision trees

General shape

Below is an exemplar part of a system supervision tree:

s6-svscan /run/system/service
  ├─s6-supervise s6-svscan-log
  │   └─s6-log -bpd3 -- 1 T /run/system/uncaught-logs
  ├─s6-supervise sshd-srv
  │   └─sshd
  └─s6-supervise sshd-log
      └─s6-log -bd3 n3 T /var/log/system/sshd
			

• The supervision tree is initialized by starting s6-svscan on a scandir. In this case, the scan directory is /run/goetia/system/service.
• s6-svscan starts one s6-supervise process per service directory it finds inside the scan directory.
• s6-supervise then reads the content of the service directory and, based on that, starts a daemon. In the example depicted above, there are three services running, with their service directories at:
  • /run/system/service/s6-svscan-log
  • /run/system/service/sshd-srv
  • /run/system/service/sshd-log
• The child of each s6-supervise is the daemon started by it, the corresponding command lines are:
  • s6-log -bpd3 -- 1 T /run/system/uncaught-logs
  • sshd
  • s6-log -bd3 n3 T /var/log/system/sshd
• Thus, the following services are supervised and running:
  • s6-svscan-log: This is the logger of the system supervision tree. It runs s6-log, catches all logs that are not handled by any other logger and writes them to /run/system/uncaught-logs. (see logging directory)
  • sshd-srv: The ssh server is a long lived process and a perfect example of a daemon to be supervised.
  • sshd-log: The logger which is automatically attached to the sshd daemon. In this case, it writes all its logs to /var/log/system/sshd. Did this not exist, all logs produced by sshd would go to s6-svscan-log. (see logging directory)

The exact specification of s6 based supervision trees can be found on the respective page, starting at here.

Management

Once a supervision tree is initiated, i.e. s6-svscan is running on a scandir, tools like s6-svc can be used to control the services.

There are two more problems to solve: dependency management and services that start, do something, and exit without being restarted. They should be considered "up" or "successfull" if the exit 0. Such services are called oneshots. Both problems are solved by s6-rc which is a manager for supervision trees. s6-rc can handle dependencies by starting and stopping services in the right order. It allows for oneshot services, by running the script from a longrun system service and waiting for them to complete before running the next dependant service. Almost all configuration provided by goetia is technically for s6-rc.

s6-rc takes a configuration made up of source directories. These reside in the configuration directory. s6-rc-compile is used to turn the source directories into usable database. s6-rc takes the information of this database to manipulate the supervision tree. goetia provides convenience wrappers around these and more programs as part of goetia-base.

Before s6-rc can be used to manipulate a supervision tree, it has to be initialized by s6-rc-init. For the system supervision tree, this is automatically done by the system-init scripts that come with Kernel specific packages goetia-linux-init, goetia-freebsd-init, etc. For the user supervision tree (see below), this is automated in the user-init script.

In each case, the first bundle to be started is the bundle named default. This can be temporarily changed by setting the environment variable GOETIABUNDLE before invoking system-init/user-init. In the case of system-init, this is done using the Kernel commandline.

The system supervision tree

The system supervision tree is initiated by init and the point of origin from which all programs are directly or indirectly started.

• There is exactly one system supervision tree per machine, initiated by init, stopped on shutdown.
• The system supervision tree is owned by root, all services started have root permissions and should, if possible drop them as early as possible.
• Daemons usually running under the system tree are for example ttys, a system bus (e.g. dbus) or webservers (e.g. tipidee).

User supervision trees

A user supervision tree is a supervision tree that is owned by a user. This means, that the owning user can freely start, stop and manipulate the user supervision tree. The permissions of all processes running under any user supervision tree match those of the owning user.

Each user can have have 0, 1 or more user supervision trees. Each user supervision tree represents a session. Not every session has to be a user supervision tree, but with goetia, most are. User supervision trees of the same user a differentiated using the USERTREE environment variable. It contains the name of the session. Thus, every user supervision tree is characterized by two variables:

• USER=...
• USERTREE=...

A user supervision tree is started by invoking user-init. It is stopped by user-shutdown.

Some examples on how to start user supervision trees can be found on the corresponding tutorial page.