66
www.obarun.org

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 ]  [ -f finish command ] [ -e environment ] [ -c create ] [ -r remove ] [ -u up ] [ -d 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.
• -f finish command : set the command 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. On other case 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.
• -d 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 -rt command
• quit  : this will send an -q command
• halt  : this will send an -st command
• reboot  : this will send an -i command
• poweroff  : this will send an -pt 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.

crash file

With the -b options the file will be:

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

without the -b option

#!/usr/local/bin/execlineb -P
fdmove -c 2 1
s6-envdir .env
foreground { 66-all -v3 -l /run/66/ down }
s6-echo -- "scandir /run/66/scandir/0 crashed..."

finish file

With the -b options the file will be:

#!/usr/local/bin/execlineb -S0
fdmove -c 2 1
s6-envdir .env
cd /
redirfd -w 2 /dev/console
fdmove -c 1 2
foreground { s6-svc -X -- /run/66/scandir/0/scandir-log }
unexport ?
wait r -- { }
/etc/66/stage3 $@

The last command (in our example /etc/66/stage3 @) is set by the -f finish command options given on the command line. If your e.g finish command is /usr/bin/true your finish file will be:

#!/usr/local/bin/execlineb -S0
fdmove -c 2 1
s6-envdir .env
cd /
redirfd -w 2 /dev/console
fdmove -c 1 2
foreground { s6-svc -X -- /run/66/scandir/0/scandir-log }
unexport ?
wait r -- { }
/usr/bin/true

without the -b option

#!/usr/local/bin/execlineb -S0
fdmove -c 2 1
s6-envdir .env
s6-echo -- "scandir /run/66/scandir/0 shutted down..."

SIGHUP file

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

#!/usr/local/bin/execlineb -P
fdmove -c 2 1
s6-envdir .env
foreground { 66-dbctl -v3 -l /run/66/ -d Master }
s6-svscanctl -h .

SIGINT file

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

#!/usr/local/bin/execlineb -P
fdmove -c 2 1
s6-envdir .env
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -6 .

SIGQUIT file

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

#!/usr/local/bin/execlineb -P
fdmove -c 2 1
s6-envdir .env
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -7 .

SIGTERM file

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

#!/usr/local/bin/execlineb -P
fdmove -c 2 1
s6-envdir .env
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -t .

SIGUSR1 file

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

#!/usr/local/bin/execlineb -P
fdmove -c 2 1
s6-envdir .env
s6-svscanctl -an .

SIGUSR2 file

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

#!/usr/local/bin/execlineb -P
fdmove -c 2 1
s6-envdir .env
foreground { 66-all -v3 -l /run/66/ down }
s6-svscanctl -0 .

Environment configuration

• 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.

An running scandir can not be removed. You must stop the scandir before to be able to remove it.