66-scandir.md

title: The 66 Suite: 66-scandir author: Eric Vidal eric@obarun.org

66

Software

obarun.org

66-scandir

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

Interface

    66-scandir [ -h ] [ -z ] [ -v verbosity ] [ -l live ] [ -b|B ] [ -c ] [ -L log_user ] [ -s skel ] [ -o owner ] create|remove

This program creates or remove the scandir (directory containing a collection of s6‑supervise processes) for the current owner of the proccess depending on the provided options.

Exit codes

• 0 success
• 100 wrong usage
• 111 system call failed

Options

• -h : prints this help.

• -z : use color.

• -v verbosity : increases/decreases the verbosity of the command.

  • 1 : only print error messages. This is the default.
  • 2 : also print warning messages.
  • 3 : also print tracing messages.
  • 4 : also print debugging messages.

• -l live : changes the supervision directory of service to live. By default this will be %%livedir%%. The default can also be changed at compile time by passing the --livedir=live option to ./configure. An existing absolute path is expected and should be within a writable and executable filesystem - likely a RAM filesystem.

• -b : create specific files for boot. 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 : create specific files for boot 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 s6-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 poweroff will make it report being killed by a SIGINT. This is according to the reboot(2) specification.
  • Stopping the container with halt, however, is different. It will make the container's pid 1 read a number in the %%livedir%%/container/\<owner\>/halt file which contents the variable EXITCODE, and exit with the code it has read. (Default is 0.) This means that in order to run a command in a container managed by 66-boot and exit the container when the command dies while reporting the exit code to its parent, 66-boot use the %%skel%%/rc.init.container file instead of the %%skel%%/rc.init file. This file should be modified to launch the command that you want to start inside this container. Then you need to stop that container calling 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 : run the system without a catch-all logger. On a non-containerized system, that means that all the logs from the s6 supervision tree 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.

• -s skel : an absolute path. Directory containing skeleton files. This option is not meant to be used directly even with root. 66‑boot calls it during the boot process. Default is %%skel%%.

• -L log_user : will run the catch-all logger as log_user. Default is %%s6log_user%%. The default can also be changed at compile-time by passing the ‑‑with‑s6‑log‑user=user option to ./configure.

• -o 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 %%livedir%% by default or the resulting path provided by the ‑l option.

Scandir creation process

When creating the scandir various files and directories will be created at the live directory.

If created with the user root, you will find the following in %%livedir%% (the directory created by default if ‑l is not passed and 0 being the corresponding UID for the root user):

• %%livedir%%/scandir/0 : stores all longrun proccesses (commonly known as daemons) started by root.

• %%livedir%%/tree/0 : stores any s6‑rc service database started by root.

• %%livedir%%/log/0 : stores the catch-all logger when the scandir is created for a boot procedure with the ‑b option.

• %%livedir%%/state/0 : stores internal 66 ecosystem files.

If the scandir was created with a regular user you will find the following in %%livedir%% (Default directories if ‑l is not passed and 1000 being the UID for the user):

• %%livedir%%/scandir/1000

• %%livedir%%/tree/1000

• %%livedir%%/state/1000

The -B option create an extra directory at %%livedir%%/scandir/<owner>/container containing a file named halt. See 66-boot for further information.

If a scandir already existed at the default location for the given user it will prevent its creation when calling 66‑scandir create. If you wanted to create a different scandir for the same owner at the same live location you must delete it first with 66-scandir remove.

Scandir removal process

The scandir must first be stopped sending a signal with 66‑scanctl stop or similar to be able to remove it.

Some directories of the scandir may not be removed if another user accesses them. In our previous example where we created a scandir for root with UID 0 and a regular user with the UID 1000 this would imply the following:

• %%livedir%%/scandir/0 # will be deleted

• %%livedir%%/tree/0 # will be deleted

• %%livedir%%/log/0 # will be deleted

• %%livedir%%/state/0 # will be deleted

The live directory of the root user (in this example and by default %%livedir%%) will not be removed because another user (the one from our example) can still use it. In fact 66‑scandir will only remove the subdirectories of the corresponding UID of the owner while the live root directory is not touched. If live was created on a RAM filesystem as suggested the deletion happens on the next reboot.

Boot specification

The -b, -B, -c and -s option are called by 66-boot. ‑b and -B will create .s6‑svscan control files (see s6‑svscan interface documentation) specifically for stage1 (PID1 process). This special scandir is controlled by the safe wrappers halt, poweroff, reboot, shutdown provided with 66 tools. The 66-shutdownd daemon which controls the shutdown request will be created automatically at the correct location. Further this specific task needs to read the skeleton file init.conf containing the live directory location which is the purpose of the ‑s option.

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 s6‑svscan can be run.

Environment configuration

You can modify environment variables when starting the scandir with the ‑e option. This option expects to find a valid absolute path to a directory containing one or more files where the format is the classic key=value pair. Each file found will be read and parsed.

Any service launched on the scandir will inherit the environment variables of the scandir. A specific global key=value pair inherited by all service can be set using this option.

Limits

The mentioned environment directory can not exceed more than 100 files. Each file can not contain more than 8095 bytes or more than 50 key=value pairs.