scandir¶

Handles the scandir for a given user. Designed to be either root or a branch of the supervision tree (nested scandir).

Interface¶

scandir [ -h ] [ -o owner ] create|start|stop|remove|reconfigure|check|quit|abort|nuke|annihilate|zombies [<subcommand options>]

This program creates, removes or sends a signal to a scandir (directory containing a collection of 66-supervise processes) for the current owner of the proccess depending on the provided options.

When the start subcommand is invoked, this command launches 66-scandir, which supervises the 66-supervise processes, where each 66-supervise monitors a single service.

Options¶

-h, --help: prints this help.
-o, --owner owner: handles the scandir for the given owner. Only the root user can use this option. Note that owner can be any valid user on the system. However, the given user must have sufficient permissions to create the necessary directories at its location. That is /run/66 by default or the resulting path provided by the 66 -l option.

Subcommands¶

create: create a scandir.
start: start a scandir.
stop: stop a running scandir.
remove: remove a scandir.
reconfigure: reconfigure a running scandir.
check: check a running scandir.
quit: quit a running scandir.
abort: abort a running scandir.
nuke: nuke a running scandir.
annihilate: annihilate a running scandir.
zombies: destroy zombies from a running scandir.

Usage examples¶

Creates a scandir for the owner of the process

66 scandir create

Creates a scandir for the owner owner

66 scandir -o owner create

Creates a scandir for a boot process

66 scandir create -b

Creates a scandir for the boot process using the specific account logaccount for the logger

66 scandir create -b -L logaccount

Creates (if doesn't exist yet) and starts a scandir for the boot process within a container adding an extra environment directory called /myenvdir.

66 scandir start -B -e /myenvdir

Stops an already running scandir

66 scandir stop

create¶

This subcommand create a scandir.

Interface¶

scandir create [ -h ] [ -b|B ] [ -c ] [ -L log_user ]

This command create the necessary directory at /run/66. If the scandir already exist for the given user it will prevent its creation. You must remove it first if you don't want to keep it.

Various files and directories are created at /run/66. Refer to the deeper understanding documentation for further information.

Options¶

-h, --help: print this help.
-b, --boot: create scandir for a boot process. Only the root user can use this option. It is not meant to be used directly even with root. 66 boot calls it during the boot process.
-B, --container: create scandir for a boot process inside a container. This option modifies some behaviors:

The ultimate output fallback (i.e. the place where error messages go when nothing catches them, e.g. the error messages from the catch-all logger and the 66-supervise process managing the catch-all logger) is not /dev/console, but the descriptor that was init's standard error. Stopping the container with reboot will make the container's init program report being killed by a SIGHUP. Stopping it with 66 poweroff will make it report being killed by a SIGINT. This is according to the reboot(2) specification. Stopping the container with 66 halt, however, is different. It will make the container's pid 1 read a number in the /run/66/container/<UID>/halt file which contents the variable EXITCODE, and exit with the code it has read. (Default is 0.) A container is booted with 66 boot -c: it brings up the enabled trees as a full supervised system rather than launching a single command. Define whatever the container should run as ordinary services in those trees, then stop it with 66 halt. All the running services will be killed, all the zombies will be reaped, and the container will exit with the required exit code.
-c, --no-logger: do not catch logs. On a non-containerized system, that means that all the logs from the scandir will go to /dev/console, and that /dev/console will also be the default stdout and stderr for services running under the supervision tree: use of this option is discouraged. On a containerized system (when paired with the -B option), it simply means that these outputs go to the default stdout and stderr given to the container's init - this should generally not be the default, but might be useful in some cases.
-L, --log-user log_user: run catch-all logger as log_user user. Default is 66log. The default can also be changed at compile-time by passing the -D 66-log-user=user option to meson setup.

Usage examples¶

Creates a scandir for the owner of the process

66 scandir create

Creates a scandir for the boot process using the specific account logaccount for the logger

66 scandir create -b -L logaccount

start¶

This subcommand starts a scandir and, if it doesn't exist yet, it possibly creates it .

Interface¶

scandir start [ -h ] [ -d notif ] [ -s rescan ] [ -e environment ] [ -b|B ]

The scandir is created if it wasn't made previously, but you don't a fine-grained control over its creation as you do with the create subcommand.

Options¶

-h, --help: prints this help.
-d, --notify notif: notify readiness on file descriptor notif. When scandir is ready to accept signal, it will write a newline to notif. notif cannot be lesser than 3. By default, no notification is sent. If -b is set, this option has no effect.
-s, --rescan rescan: perform a scan every rescan milliseconds. If rescan is set to 0 (the default), automatic scans are never performed after the first one and 66-scandir will only detect new services by issuing either scandir reconfigure or scandir check. It is strongly discouraged to set rescan to a positive value under 500.
-e, --environment environment: an absolute path. Merge the current environment variables with variables found in this directory before starting the scandir. Every regular file found in environment is read and parsed. Sub-directories are not descended into. Each services started within the scandir will inherit of the key=value pair define within environment. By default, 66 import the /etc/66/environment environment directory by default for the root user and the .66/environment directory for the regular user. Although this can be changed at compile time by passing the -D sysadmin-environment-dir=DIR, -D user-environment-dir=DIR for root and regular user respectively. In case of same key=value pair, the environment directory define with the -e take precedence. Also, see Environment for further information about the syntax and the limitations.

Usage examples¶

Starts a scandir with notify readiness mechanism on file descriptor 3

66 scandir start -d 3

Starts a scandir for the owner owner

66 scandir -o owner start

stop¶

This command stops a running scandir.

Interface¶

scandir stop [ -h ]

This command stops the scandir sending a SIGTERM to all the 66-supervise processes supervising a service and a SIGHUP to all the 66-supervise processes supervising a logger, then exec into its finish procedure. This means that services will be brought down but loggers will exit naturally on EOF, and 66-scandir will wait for them to exit before exec'ing into .66-scandir/finish or exiting itself: it's a clean shutdown with no loss of logs.

Options¶

-h, --help: prints this help.

Usage examples¶

Stop an already running scandir

66 scandir stop

Stop an already running scandir for the owner owner

66 scandir -o owner stop

remove¶

This command remove a scandir from the live directory.

Interface¶

scandir remove [ -h ]

The scandir must first be stopped with scandir stop subcommand or similar subcommand to be able to remove it.

Certain directories within the scandir will not be removed. Specifically, /run/66/log, /run/66/scandir, /run/66/state and /run/66/environment remain intact, whereas all UID subdirectories are deleted. Refer to the deeper understanding for further information.

Options¶

-h, --help: prints this help.

Usage examples¶

Removes a scandir

66 scandir remove

Removes a scandir for the owner owner

66 scandir -o owner remove

reconfigure¶

This command reconfigure a running scandir.

Interface¶

scandir reconfigure [ -h ]

66-scandir will perform a scan, and destroy inactive services.

Options¶

-h, --help: prints this help.

Usage examples¶

Reconfigures a running scandir.

66 scandir reconfigure

Reconfigures a scandir for the owner owner

66 scandir -o owner reconfigure

check¶

This command check the scandir for services.

Interface¶

scandir check [ -h ]

66-scandir will immediately perform a scan of scandir to check for services.

Options¶

-h, --help: prints this help.

Usage examples¶

Checks a scandir

66 scandir check

Checks a scandir for the owner owner

66 scandir -o owner check

quit¶

Quits a running scandir.

Interface¶

scandir quit [ -h ]

66-scandir will send all its 66-supervise processes a SIGTERM, then exec into its finish procedure. This is different from stop subcommand in that services and loggers will be forcibly killed, so the quit procedure may be faster but in-flight logs may be lost.

Options¶

-h, --help: prints this help.

Usage examples¶

Quits a running scandir.

66 scandir quit

Quits a scandir for the owner owner

66 scandir -o owner quit

abort¶

This command abort a running scandir.

Interface¶

scandir abort [ -h ]

66-scandir will exec into its finishing procedure. It will not kill any of the maintained 66-supervise processes.

Options¶

-h, --help: prints this help.

Usage examples¶

Aborts a scandir

66 scandir abort

Aborts a scandir for the owner owner

66 scandir -o owner abort

nuke¶

Kill all the 66-supervise processes.

Interface¶

scandir nuke [ -h ]

66-scandir kill all the 66-supervise processes it has launched but that did not match a service directory last time scandir was scanned, i.e. it prunes the supervision tree so that it matches exactly what was in scandir at the time of the last scan. A SIGTERM is sent to the 66-supervise processes supervising services and a SIGHUP is sent to the 66-supervise processes supervising loggers.

Options¶

-h, --help: prints this help.

Usage examples¶

Kill 66-supervise processes from a scandir

66 scandir nuke

Kill 66-supervise processes from a scandir for the owner owner

66 scandir -o owner nuke

annihilate¶

Annihilates a running scandir.

Interface¶

scandir annihilate [ -h ]

Does the same thing as nuke, except that SIGTERM is sent to all the relevant 66-supervise processes, even if they are supervising loggers. This is not recommended in a situation where you do not need to tear down the supervision tree.

Options¶

-h, --help: prints this help.

Usage examples¶

Annihilates a scandir

66 scandir annihilate

Annihilates a scandir for the owner owner

66 scandir -o owner annihilate

zombies¶

Destroy zombies from a running scandir.

Interface¶

scandir zombies [ -h ]

Immediately triggers 66-scandir's reaper mechanism.

Options¶

-h, --help: prints this help.

Usage examples¶

Removes zombies from a scandir

66 scandir zombies

Removes zombies from a scandir for the owner owner

66 scandir -o owner zombies

Boot specification¶

The -b, -B and -c option are called by 66 boot. -b and -B will create .66-scandir control files (see the Interface section) specifically for stage1 (PID1 process). This special scandir is controlled by 66 halt, 66 poweroff and 66 reboot command. The 66-shutdownd daemon which controls the shutdown request will be created automatically at the correct location.

The live directory for the boot process requires writable directories and an executable filesystem. In order to accommodate for read-only root filesystems there needs to be a tmpfs mounted before 66-scandir can be run.

Environment¶

An Environment directory is a directory containing files with lines of pairs with the syntax being: key = value. The directory is parsed by ascending alphabetical order. If there are duplicate key=value pairs, the pair found in the last file takes precedence.

Whitespace is permitted before and after key, and before or after value.

Empty lines, or lines containing only whitespace, are ignored. Lines beginning with # (possibly after some whitespace) are ignored (and typically used for comments). Leading and trailing whitespace is stripped from values; but a value can be double-quoted, which allows for inclusion of leading and trailing whitespace.

Escaping double-quoted can be done with backslash \. For instance,

cmd_args=-g \"daemon off;\"

C escapes, including hexadecimal and octal sequences, are supported in quoted values. Unicode codepoint sequences are not supported.

If value is empty, key is still added to the environment, with an empty value.

Reusing the same variable or variable from the actual environment is allowed. In such case, variable name must be between ${} to get its value. For instance, an environment file can be declared

    PATH=/usr/local/bin:${PATH}
    socket_name=sname
    socket_dir=dname
    socket=${socket_dir}/${socket_name}

The order of key=value pair declaration does not matter

    PATH=/usr/local/bin:${PATH}
    socket=${socket_dir}/${socket_name}
    socket_name=sname
    socket_dir=dname

A variable calling itself is only allowed if the key name can be found at the environment of the current process. If the key of the key=value cannot be found it leaves the pair as is. For instance,

    PATH=/usr/local/bin:${PATH}

will only work if PATH is already defined in the current environment. If not the result will literally be PATH=/usr/local/bin:${PATH}.

Limits¶

An environment directory can not exceed more than 20 files. Each file can not contain more than 8191 bytes or more than 50 key=value pairs.