The 66-scandir program

66-scandir handle a scandir for a specific given user. It is designed to be either the root or a branch of a supervision tree.

Interface

     66-scandir [ -h help ] [ -v verbosity ] [ -b boot ] [ -l live ] [ -t rescan ] [ -2 stage2.tini ] [ -3 stage3 ] [ -e environment ] [ -c create ] [ -r remove ] [ -u up ] [ -s signal ] owner

66-scandir will handle or create the scandir at live for a specific owner depending of the options given. The owner can be any valid user on the system. However, the owner must have sufficient permissions to create the necessary directories at live. If the owner is not set, the user of the current process will be took.

Options

-h : print the help.
-v verbosity : increase/decrease verbosity level. 0 or 1: print only error messages. 2: print warning message. Over 3: debugging mode.
-b : create specific files for boot. Only root user can use this option - see below.
-l live : create the scandir at live.Default is /run/66. The default can be changed at compile-time by giving the --livedir=live option to ./configure.
-t rescan : perform a scan every rescan milliseconds. If rescan is 0 (the default), automatic scans are never performed after the first one and s6-svscan will only detect new services when told to via a 66-scandir -d reload command or 66-svscanctl -a command. It is strongly discouraged to set rescan to a positive value under 500.
-2 stage2.tini : set the command to execute with configurable handlers when the scandir receive a signal. An absolute path is expected. This options is mandatory if the -b has been given. If it's not specified /etc/66/stage2.tini scripts is took by default. Without the -b options, this options have no effects - see below.
-3 stage3 : set the command script to execute when the scandir is asked to be shutted down. An absolute path is expected. This options is mandatory if the -b has been given. If it's not specified /etc/66/stage3 scripts is took by default. Without the -b options, this options have no effects - see below.
-e environment : adjust the environment variable of the scandir with variables find on the environment directory. It reads every files in environment directory that does not begin with a dot and does not contain the '=' character. An absolute path is expected.
-c : create the neccessary directories at live. This option is expected to be done before trying to run the scandir by the options -u.
-r : remove the scandir directory at live. The scandir must be stopped previously with the options -d.
-u : start the scandir directory at live.
-s signal : send a signal to the scandir directory. The signal can be any valid s6-svscanctl command more some convenient sentence - see below.

Signals

The options -s to send a signal to the scandir is builded around the s6-svscanctl program and act with exactly the same behaviour. Any signal accepted by s6-svscanctl program can be passed but need to be done without the '-' character at the begin of the signal. If, for example, you want to send a -t signal you need to use: 66-scandir -s t. Series of command is also accepted in the same manner: 66-scandir -s st.
Also some convenient sentence was added to avoid to remember basic and usefull series of command like :

reload : this will send an -an command
interrupt : this will send an -i command
quit : this will send an -q command
halt : this will send an -0 command
reboot : this will send an -6 command
poweroff : this will send an -7 command

Signal usage examples

 66-scandir -s reload

Updates the process supervision tree to exactly match the services listed in scandir.

This command is strictly equal to :

s6-svscanctl -an /service

Scandir creation process

When you ask for a creation of the scandir various files and directories will be created at live directory for the given owner. If you run the 66-scandir with the user root, you will find in /run/66 (default directory is took for the example) :

/run/66/scandir/0 : where 0 is the corresponding uid for the root user. This directory store all longrun proccess (a.k.a. daemon) started by the user root.
/run/66/tree/0 : This directory store all s6-rc service database started by the user root.
/run/66/log/0 : This directory store the catch-all logger when the scandir is created for a boot procedure.

If you ask for the creation of the scandir with normal user you will find /run/66/scandir/1000 where 1000 is the corresponding uid for the user, and /run/66/tree/1000. The log directory is not set due of the missing permissions to create the scandir for the boot process, instead it will be found by default at /var/log/scandir-1000. Default log directory can be changed at compile-time by giving the --with-system-logpath=DIR option for root permissions and --with-user-logpath=DIR options for user permissions to ./configure.

An existing scandir directory will be used as it and the creation will be skipped. If you want to create a fresh scandir directory for the same owner, use the -r options before.

.s6-svscan control directory

s6-svscan program expect to find some control file when it receive a signal. Thoses files are not mandatory and are not created by any s6 program but are usefull to control the e.g shutdown process. The 66-scandir program will care of it and create those files at /run/66/scandir/0/.s6-svscan directory. Depending if the -b options is passed or not to the command line, the files will change.

The path of the scandir in those files is automatically define in conjonction with the -l live options.

crash file

With or without the -b options the file will be:

#!/usr/bin/execlineb -P
redirfd -r 0 /dev/console
redirfd -w 1 /dev/console
fdmove -c 2 1
s6-echo -- "scandir /run/66/scandir/0 crashed ... "
/bin/sh -i

finish file

With the -b options the file will be:

#!/usr/bin/execlineb -S0
/etc/66/stage3 $@

The last command is set by the -3 stage3 options given on the command line. If your e.g stage3 argument is /usr/bin/true your finish file will be:

#!/usr/local/bin/execlineb -S0
/usr/bin/true

without the -b option

#!/usr/bin/execlineb -S0
s6-echo -- "scandir /run/66/scandir/1000 shutted down..."

SIGHUP file

With the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { /etc/66/stage2.tini }
s6-svscanctl -h -- /run/66/scandir/0

The command executed before sending a signal to the scandir is set by the -2 stage2.tini options given on the command line.

Without the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -h -- /run/66/scandir/0

SIGINT file

With the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { /etc/66/stage2.tini }
s6-svscanctl -6 -- /run/66/scandir/0

Without the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -6 -- /run/66/scandir/0

SIGQUIT file

With the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { /etc/66/stage2.tini }
s6-svscanctl -q -- /run/66/scandir/0

Without the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -q -- /run/66/scandir/0

SIGTERM file

With the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { /etc/66/stage2.tini }
s6-svscanctl -t -- /run/66/scandir/0

Without the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -t -- /run/66/scandir/0

SIGUSR1 file

With the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { /etc/66/stage2.tini }
s6-svscanctl -7 -- /run/66/scandir/0

Without the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -7 -- /run/66/scandir/0

SIGUSR2 file

With the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { /etc/66/stage2.tini }
s6-svscanctl -O -- /run/66/scandir/0

Without the -b options the file will be:

#!/usr/bin/execlineb -P
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -O -- /run/66/scandir/0

Environment configuration

You can modify the environment variable at the start of the scandir with the -e options. This option expect to find a valid absolute path for a directory which contain files where the format of the file is :

The name of the files is the name of the key. The name do not begin by a dot and do not contain '=' character.
The contain of the file is the value of the key. Only one value is accepted followed by an empty new line.

Environment file example

name of the file: /etc/66/env/TZ

contain of the file:

Pacific/Noumea

Every daemon launched on the scandir should inherit of the environment variable of the scandir. So if you want to have a specific key=value pair for every daemon, use this option.

Scandir remove process

When you use the -r options some directories of the scandir will be removed but not all the componments of the directory. In our previous example:

/run/66/scandir/0 will be removed
/run/66/tree/0 will be removed
/run/66/log/0 will be removed

The root live (a.k.a /run/66) directory will be not removed because an another user can still use it. In fact the 66-scandir will only remove the componment of the corresponding uid of the owner.

A running scandir can not be removed. You must stop first the scandir to be able to remove it.