This program sends a *signal* to an already running [scandir](scandir.html) at *live* where by default *live* is at `%%livedir%%` or the resulting path provided by the **‑l** option. If owner is not explicitely set with **‑o** then the user of the current process will be used instead.
## 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—see [66-scandir](66-scandir.html).
-**-d***notif* : notify readiness on file descriptor notif. When *scandir* is ready to accept commands from [66‑scanctl](66-scanctl.html), 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 have no effects.
-**-t***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 [s6‑svscan](https://skarnet.org/software/s6/s6-svscan.html) will only detect new services by issuing either [66‑scanctl](66-scanctl.html) reload or [s6‑svscanctl -a](https://skarnet.org/software/s6/s6-svscanctl.html). It is **strongly** discouraged to set rescan to a positive value under `500`.
-**-e***environment* : an absolute path. Merge the current environment variables with variables found in this directory before starting the *scandir*. Any file in environment not beginning with a dot and not containing the `=` character will be read and parsed.
-**-o***owner* : send the *signal* to a [scandir](66-scandir.html) owned by *owner* instead of the current owner of the process. *owner* needs adecuate permissions to deal with the scandir.
## Signal
Any signal accepted by [s6‑svscanctl](https://skarnet.org/software/s6/s6-svscanctl.html) can be passed but without the dash `‑` character. As a result if you wanted to send a **‑t** signal, you need to use: `66‑scanctl t`. Further a series of commands is also accepted in the same way: `66‑scanctl st`. A few convenient keywords were added to avoid having to remember basic and useful commands:
-*reload* = ‑an
-*interrupt* = ‑i
-*quit* = ‑q
-*halt* = ‑0
-*reboot* = ‑6
-*poweroff* = ‑7
## Usage examples
```
66-scanctl reload
```
Updates the process supervision tree to exactly match the services listed in [scandir](66-scandir.html).
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](66‑boot.html) 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)](http://man7.org/linux/man-pages/man2/reboot.2.html) 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](66-boot.html) and exit the container when the command dies while reporting the exit code to its parent, [66-boot](66-boot.html) 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](66-boot.html) 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](https://skarnet.org/software/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.
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](boot.html) 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](66-scanctl.html) 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](66-boot.html). **‑b** and **-B** will create .s6‑svscan control files (see [s6‑svscan](https://skarnet.org/software/s6/s6-svscan.html) 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](66‑shutdownd.html) 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](https://skarnet.org/software/s6/s6-svscan.html) 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.
This program creates, removes or sends a signal to a *scandir* (directory containing a collection of s6‑supervise processes) for the current owner of the proccess depending on the provided options.
When the `start` subcommand is invoked, this command launches the [s6-svscan](https://skarnet.org/software/s6/s6-svscan.html), responsible for supervising the [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) program, where [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) monitors a single service.
## Options
-**-h**: prints this help.
-**-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 `66 ‑l` option.
## Subcommands
-**create**: create a *scandir*.
-**start**: start a *scandir*.
-**stop**: stop a running *scandir*.
-**remove**: remove a *scandir*.
-**reload**: reload 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 environment directory
This command create the necessary directory at `%%livedir%%`. 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 is created at `%%livedir%%`. Refers to [deeper understanding](deeper.html) documentation for futhers information.
#### Options
-**-h**: print this help.
-**-b**: 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](boot.html) calls it during the boot process.
-**-B**: 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 [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) 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](poweroff.html) will make it report being killed by a `SIGINT`. This is according to the reboot(2) specification.
Stopping the container with [66 halt](halt.html), however, is different. It will make the container's pid 1 read a number in the `/run/66/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](boot.html) and exit the container when the command dies while reporting the exit code to its parent, [66 boot](boot.html) use the `/etc/66/rc.init.container` file instead of the `/etc/66/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 [66 halt](halt.html).
All the running services will be killed, all the zombies will be reaped, and the container will exit with the required exit code.
-**-c**: 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*: run catch-all logger as *log_user* 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`.
-**-s***skel*: use *skel* as skeleton directory. Directory containing *skeleton* files. This option is not meant to be used directly even with root. [66 boot](boot.html) calls it during the boot process. Default is `%%skel%%`.
#### 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 .
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**: prints this help.
-**-d***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 have no effects.
-**-t***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 [s6‑svscan](https://skarnet.org/software/s6/s6-svscan.html) will only detect new services by issuing either [scandir reload](scandir.html#reload) or [scandir check](scandir.html#rescan). It is **strongly** discouraged to set *rescan* to a positive value under `500`.
-**-e***environment*: an absolute path. Merge the current environment variables with variables found in this directory before starting the *scandir*. Any file in environment not beginning with a dot and not containing the `=` character will be read and parsed. Each services will inherit of the `key=value` pair define within *environment*. 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.
#### 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 [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) processes supervising a service and a `SIGHUP` to all the [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) 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 [s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) will wait for them to exit before exec'ing into `.s6-svscan/finish` or exiting itself: it's a clean shutdown with no loss of logs.
#### Options
-**-h**: 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](#stop) subcommand or similar subcommand to be able to remove it.
This subcommand remove some directories and files from the `%%livedir%%` directory. Refers to [deeper understanding](deeper.html) documentation for futhers documentation.
#### Options
-**-h**: prints this help.
#### Usage examples
Removes a *scandir*
```
66 scandir remove
```
Removes a *scandir* for the owner `owner`
```
66 scandir -o owner scandir
```
### reload
This command reload configuration of a running *scandir*.
#### Interface
```
scandir reload [ -h ]
```
[s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) will perform a scan, and destroy inactive services.
#### Options
-**-h**: prints this help.
#### Usage examples
Reloads a running *scandir*.
```
66 scandir reload
```
Reloads a *scandir* for the owner `owner`
```
66 scandir -o owner reload
```
### check
This command check the *scandir* for services.
#### Interface
```
scandir check [ -h ]
```
[s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) will immediately perform a scan of *scandir* to check for services.
#### Options
-**-h**: 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 ]
```
[s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) will send all its [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) 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**: prints this help.
#### Usage examples
Quits a *scandir* 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 ]
```
[s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) will exec into its finishing procedure. It will not kill any of the maintained [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) processes.
#### Options
-**-h**: 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 [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) processes.
#### Interface
```
scandir nuke [ -h ]
```
[s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) kill all the [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) 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 [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) processes supervising services and a `SIGHUP` is sent to the [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) processes supervising loggers.
#### Options
-**-h**: prints this help.
#### Usage examples
Kill s6-supervise processes from a *scandir*
```
66 scandir nuke
```
Kill s6-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](#nuke), except that `SIGTERM` is sent to all the relevant [s6-supervise](https://skarnet.org/software/s6/s6-supervise.html) 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.
Removes zombies from a *scandir* for the owner `owner`
```
66 scandir -o owner zombies
```
## Boot specification
The **-b**, **-B**, **-c** and **-s** option are called by [66 boot](boot.html). **‑b** and **-B** will create `.s6‑svscan` control files (see [s6‑svscan](https://skarnet.org/software/s6/s6-svscan.html) interface documentation) specifically for stage1 (PID1 process). This special *scandir* is controlled by [66 halt](halt.html), [66 poweroff](poweroff.html) and [66 reboot](reboot.html) command. The [66-shutdownd](66‑shutdownd.html) 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](https://skarnet.org/software/s6/s6-svscan.html) can be run.
