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.

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. Once the internal services of the scandir are up and ready, or after 3 seconds, it writes a newline to notif. notif cannot be lesser than 3. By default, no notification is sent.
-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, except the one of the scandir-log catch-all logger of a boot scandir, which receives a SIGHUP and exits naturally on EOF. 66-scandir waits for them to exit before exec'ing into .66-scandir/finish or exiting itself.

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 these 66-supervise processes, a SIGHUP to the one of the scandir-log catch-all logger.

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, the one of the scandir-log catch-all logger included. 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

Internal services¶

Every scandir holds the internal services fdholderd, oneshotd and eventd, made by the create subcommand. A boot scandir also holds the scandir-log catch-all logger, unless it was created with -c.

At its first scan, 66-scandir starts the supervisors of its internal services alone. The other services and the readiness notification of start -d wait until each internal service is up and ready, or for 3 seconds at most. An internal service that is not ready by then is reported with a warning and the scandir goes on.

The internal command starts, stops and restarts fdholderd, oneshotd and eventd. A stop lasts until the scandir is started again.

A scandir that dies¶

A scandir that does not run as PID 1, the scandir of a user session, of a container or a nested one, can die without stopping its services: killed with SIGKILL, crashed, or chosen by the out-of-memory killer. Its supervisors, its services and their loggers may then go on running without it. 66 neither adopts nor cleans up these processes: when the scandir is started again on the same directory,

a supervisor left running makes the new supervisor of the same service fail every second with another instance of 66-supervise is already running;
a service left running without its supervisor is started a second time, and its new logger fails every second with unable to lock .../log/<service>/lock: Device or resource busy, the old logger still holding the lock.

Before starting such a scandir again, kill everything left from the previous one. For the scandir of a user, once the user has no session open:

pkill -9 -u <user>

This is a known limitation. It will be solved when 66 places the processes of a scandir in a cgroup, which brings them all down with it; cgroup support is on the roadmap.

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.