Skip to content
Snippets Groups Projects
Commit d40c0e02 authored by Eric Vidal's avatar Eric Vidal :speech_balloon:
Browse files

update documentation

parent beccea5c
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/66-boot.md
+ 28
− 24
View file @ d40c0e02
...@@ -13,7 +13,7 @@ Meant to be run as pid 1 as a *stage1* init. Performs the necessary early system ...@@ -13,7 +13,7 @@ Meant to be run as pid 1 as a *stage1* init. Performs the necessary early system
``` ```
66-boot [ -h ] [ -s skel ] [ -m ] [ -l log_user ] [ -e environment ] [ -d dev ] [ -b banner ] 66-boot [ -h ] [ -z ] [ -m ] [ -s skel ] [ -l log_user ] [ -e environment ] [ -d dev ] [ -b banner ]
``` ```
...@@ -25,12 +25,12 @@ This program performs some early preparations, spawns a process that will run th ...@@ -25,12 +25,12 @@ This program performs some early preparations, spawns a process that will run th
## Options ## Options
- **-h** : prints this help. - **-h** : prints this help.
- **-s** *skel* : an absolute path. Directory that holds skeleton files. By default this will be `%%skel%%`. The default can also be changed at compile time by passing the `--with-skeleton=DIR` option to `./configure`. This directory ***must*** contain the necessary skeleton files to properly boot the machine, without it the system **will not boot**.
- **-m** : umount the basename of the *LIVE* directory set into the *init.conf* skeleton file, if it is already mounted, and mounts a tmpfs on it. By default, the *LIVE* basename is mounted if it is not already a valid mountpoint. Otherwise without the **-m** option, it does nothing. - **-m** : umount the basename of the *LIVE* directory set into the *init.conf* skeleton file, if it is already mounted, and mounts a tmpfs on it. By default, the *LIVE* basename is mounted if it is not already a valid mountpoint. Otherwise without the **-m** option, it does nothing.
- **-s** *skel* : an absolute path. Directory that holds skeleton files. By default this will be `%%skel%%`. The default can also be changed at compile time by passing the `--with-skeleton=DIR` option to `./configure`. This directory ***must*** contain the necessary skeleton files to properly boot the machine, without it the system **will not boot**.
- **-l** *log_user* : the `catch-all` logger will run 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`. - **-l** *log_user* : the `catch-all` logger will run 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`.
- **-e** *environment* : an absolute path. *stage 1 init* empties its environment before spawning the `rc.init` skeleton file and executing into [66-scandir](66-scandir.html) in order to prevent kernel environment variables from leaking into the process tree. The *PATH* variable is the only variable set for the environment. If you want to define additional environment variables then use this option. Behaves the same as [66-scandir -e](66-scandir.html). - **-e** *environment* : an absolute path. *stage 1 init* empties its environment before spawning the `rc.init` skeleton file and executing into [66-scandir](66-scandir.html) in order to prevent kernel environment variables from leaking into the process tree. The *PATH* variable is the only variable set for the environment. If you want to define additional environment variables then use this option. Behaves the same as [66-scandir -e](66-scandir.html).
...@@ -69,19 +69,19 @@ When booting a system, *66-boot* performs the following operations: ...@@ -69,19 +69,19 @@ When booting a system, *66-boot* performs the following operations:
- It performs "the fifo trick" where it redirects its stdout to the `catch-all` logger's fifo without blocking before the `catch-all` logger is even up (because it's a service that will be spawned a bit later, when [66-scandir](66-scandir.html) is executed). - It performs "the fifo trick" where it redirects its stdout to the `catch-all` logger's fifo without blocking before the `catch-all` logger is even up (because it's a service that will be spawned a bit later, when [66-scandir](66-scandir.html) is executed).
- It forks a child, also called *stage2*. - It forks a child, also called *stage2*.
* The child is blocked until the `catch-all` logger runs. * The child is blocked until the `catch-all` logger runs.
* The child starts any service of tree *TREE*. * The child starts any service of tree *TREE*.
* The child becomes a session leader. * The child becomes a session leader.
- It also makes the catch-all logger's fifo its stderr. - It also makes the catch-all logger's fifo its stderr.
- It execs into [66-scandir -v VERBOSITY -l LIVE -u](66-scandir.html) with `LIVE/scandir/0` (default `%%livedir%%/scandir/0`) as its scandir. - It execs into [66-scandir -v VERBOSITY -l LIVE -u](66-scandir.html) with `LIVE/scandir/0` (default `%%livedir%%/scandir/0`) as its scandir.
* [66-scandir](66-scandir.html) transitions into [s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) which spawns the early services that are defined in *TREE* where one of those services is `scandir-log`, which is the `catch-all` logger. Once this service is up *66-boot*'s child *stage2* unblocks. * [66-scandir](66-scandir.html) transitions into [s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) which spawns the early services that are defined in *TREE* where one of those services is `scandir-log`, which is the `catch-all` logger. Once this service is up *66-boot*'s child *stage2* unblocks.
* The child then execs into `rc.init` * The child then execs into `rc.init`
In the unusual event that any of the above processes fail, *66-boot* will try to launch a single-user login namely *sulogin* to provide the means to repair the system. In the unusual event that any of the above processes fail, *66-boot* will try to launch a single-user login namely *sulogin* to provide the means to repair the system.
...@@ -93,15 +93,15 @@ Skeleton files are mandatory and must exist on your system to be able to boot an ...@@ -93,15 +93,15 @@ Skeleton files are mandatory and must exist on your system to be able to boot an
- `init` : the *66-boot* binary is not meant to be called directly or be linked to the binary directory because it takes command line options. Therefore the `init` skeleton file is used to pass any options to *66-boot. By default *66-boot* is launched without options. This file ***should be copied*** by the administrator into the binary directory of your system. - `init` : the *66-boot* binary is not meant to be called directly or be linked to the binary directory because it takes command line options. Therefore the `init` skeleton file is used to pass any options to *66-boot. By default *66-boot* is launched without options. This file ***should be copied*** by the administrator into the binary directory of your system.
- `init.conf` : this file contains a set of `key=value` pairs. ***All*** keys are mandatory where the name of the key ***must not*** be changed. This is the file available to a user to configure the boot process. By default: - `init.conf` : this file contains a set of `key=value` pairs. ***All*** keys are mandatory where the name of the key ***must not*** be changed. This is the file available to a user to configure the boot process. By default:
* `VERBOSITY=0` : increases/decreases the verbosity of the *stage1* process. * `VERBOSITY=0` : increases/decreases the verbosity of the *stage1* process.
* `LIVE=%%livedir%%` : an absolute path; creates the scandir at *LIVE*. The value will depend by default on the `--livedir=live` option set at compile time. * `LIVE=%%livedir%%` : an absolute path; creates the scandir at *LIVE*. The value will depend by default on the `--livedir=live` option set at compile time.
* `PATH=/usr/bin:/usr/sbin:/bin:/sbin:/usr/local/bin` : the initial value for the *PATH* environment variable that will be passed on to all starting processes unless it's overridden by *PATH* declaration with the **-e** option. It is absolutely necessary for [execline](https://skarnet.org/software/execline/),[s6](https://skarnet.org/software/s6/),[s6-rc](https://skarnet.org/software/s6-rc/) and all *66 tools* binaries to be accessible via *PATH*, else the machine will not boot. * `PATH=/usr/bin:/usr/sbin:/bin:/sbin:/usr/local/bin` : the initial value for the *PATH* environment variable that will be passed on to all starting processes unless it's overridden by *PATH* declaration with the **-e** option. It is absolutely necessary for [execline](https://skarnet.org/software/execline/),[s6](https://skarnet.org/software/s6/),[s6-rc](https://skarnet.org/software/s6-rc/) and all *66 tools* binaries to be accessible via *PATH*, else the machine will not boot.
* `TREE=boot` : name of the *tree* to start. This *tree* should contain a sane set of services to bring up the machine into an operating system. 'classic' services will start early at the invocation of [66-init](66-init.html). *stage2* will then start any other service type. It is the responsibility of the system administrator to build this tree without errors. * `TREE=boot` : name of the *tree* to start. This *tree* should contain a sane set of services to bring up the machine into an operating system. 'classic' services will start early at the invocation of [66-init](66-init.html). *stage2* will then start any other service type. It is the responsibility of the system administrator to build this tree without errors.
* `RCINIT=%%skel%%/rc.init` : an absolute path. This file is launched at the end of *stage1* and run as *stage2*. It calls [66-init](66-init.html) to initiate any services inside of *TREE* except 'classic' ones which were already initiated by *stage1*. After that it invokes [66-dbctl](66-dbctl.html) to bring up all services. * `RCINIT=%%skel%%/rc.init` : an absolute path. This file is launched at the end of *stage1* and run as *stage2*. It calls [66-init](66-init.html) to initiate any services inside of *TREE* except 'classic' ones which were already initiated by *stage1*. After that it invokes [66-dbctl](66-dbctl.html) to bring up all services.
* `RCSHUTDOWN=%%skel%%/rc.shutdown` : an absolute path. This is launched when a shutdown is requested also called *stage3*. It invokes [66-all](66-all.html) to bring down all services of *TREE*. * `RCSHUTDOWN=%%skel%%/rc.shutdown` : an absolute path. This is launched when a shutdown is requested also called *stage3*. It invokes [66-all](66-all.html) to bring down all services of *TREE*.
...@@ -111,21 +111,27 @@ Skeleton files are mandatory and must exist on your system to be able to boot an ...@@ -111,21 +111,27 @@ Skeleton files are mandatory and must exist on your system to be able to boot an
* `UMASK=0022` : sets the value of the initial file umask for all starting processes in octal. * `UMASK=0022` : sets the value of the initial file umask for all starting processes in octal.
* `RESCAN=0` : forces [s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) to perform a scan every *RESCAN* milliseconds. This is an overload function mostly for debugging. It should be 0 during *stage1*. It is strongly discouraged to set *RESCAN* to a positive value smaller than 500. * `RESCAN=0` : forces [s6-svscan](https://skarnet.org/software/s6/s6-svscan.html) to perform a scan every *RESCAN* milliseconds. This is an overload function mostly for debugging. It should be 0 during *stage1*. It is strongly discouraged to set *RESCAN* to a positive value smaller than 500.
* `ISHELL=%%skel%%/ishell` : an absolute path. Gets called in case *stage2* crashes if define by the administrator at the `rc.init` file. * `CONTAINER=0` : accepted value are `0` or `1` where `0` ask to boot on a hardware system and `1` ask to boot inside a container. Default `0`. If set to `1`, the `rc.init.container` file is used instead of the `rc.init` file.
* `RCINIT_CONTAINER=%%skel%%/rc.init.container` : an absolute path. This is launched when a boot inside a container is asked. It as the same behavior of the `rc.init` file but allows to implement a command to run inside this container and retrieves the exit code of that command. The exit code of the command is automatically written at the `%%skel%%/container/<owner>/halt` file modifying the `EXITCODE=` variable.
* `CATCHLOG=1` : accepted value are `0` or `1` where `0` ask to not redirects its stdout to the `catch-all` logger's fifo and `1` ask to redirects its stdout to the `catch-all` logger's fifo. Default `1`.
- `rc.init` : this file is called by the child of *66-boot* to process *stage2*. It invokes two commands: - `rc.init` : this file is called by the child of *66-boot* to process *stage2*. It invokes two commands:
* `66-init -v${VERBOSITY} -l ${LIVE} -t ${TREE} database` will initiate `bundle` and `atomic` services inside of *TREE*. * `66-init -v${VERBOSITY} -l ${LIVE} -t ${TREE} database` will initiate `bundle` and `atomic` services inside of *TREE*.
* `66-dbctl -v${VERBOSITY} -l ${LIVE} -t ${TREE} -u` will bring up all `bundle` and `atomic` services inside of *TREE*. * `66-dbctl -v${VERBOSITY} -l ${LIVE} -t ${TREE} -u` will bring up all `bundle` and `atomic` services inside of *TREE*.
* If any of these two commands fail a warning message is sent to sdtout. It is the responsibility of the administrator to call or not the `ishell` file. * If any of these two commands fail a warning message is sent to sdtout.
- `rc.init.container` : this file replace the `rc.init` when a boot inside a container is asked. It has the same behavior than the `rc.init` file. However, this file is especially designed to be used for a boot inside a container. It allow to easily define a command(see comment on that file) to launch inside the container and to retrieve the exit code of that command.
- `rc.shutdown` : this file is called at shudown when the administrator requests the `shutdown`, `halt`, `poweroff` or `reboot` command. It invokes a single command: - `rc.shutdown` : this file is called at shudown when the administrator requests the `shutdown`, `halt`, `poweroff` or `reboot` command. It invokes a single command:
* `66-all -v${VERBOSITY} -l ${LIVE} -t ${TREE} -f down` to bring down all *services* for all *trees* marked as enabled. * `66-all -v${VERBOSITY} -l ${LIVE} -t ${TREE} -f down` to bring down all *services* for all *trees* marked as enabled.
The following skeleton files are called to execute their corresponding power related functions and are safe wrappers that accept their corresponding command options. They **should be copied or symlinked** to the binary directory of the system. The following skeleton files are called to execute their corresponding power related functions and are safe wrappers that accept their corresponding command options. They **should be copied or symlinked** to the binary directory of the system.
- `halt` : wraps [66-hpr -h](66-hpr.html). Terminates all processes and shuts down the CPU. - `halt` : wraps [66-hpr -h](66-hpr.html). Terminates all processes and shuts down the CPU.
...@@ -136,8 +142,6 @@ The following skeleton files are called to execute their corresponding power rel ...@@ -136,8 +142,6 @@ The following skeleton files are called to execute their corresponding power rel
- `shutdown` : wraps [66-shutdown](66-shutdown.html). Like `poweroff` but also runs scripts to bring the system down in a sane way including user notification. - `shutdown` : wraps [66-shutdown](66-shutdown.html). Like `poweroff` but also runs scripts to bring the system down in a sane way including user notification.
- `ishell` : this file will try to run *sulogin* to provide a means of repair.
## Kernel command line ## Kernel command line
Any valid `key=value` pair set at the `init.conf` skeleton file can be passed on the kernel command line as parameter: Any valid `key=value` pair set at the `init.conf` skeleton file can be passed on the kernel command line as parameter:
......
doc/66-enable.md
+ 3
− 9
View file @ d40c0e02
...@@ -12,7 +12,7 @@ This command enables one or more services inside a given *tree*. ...@@ -12,7 +12,7 @@ This command enables one or more services inside a given *tree*.
## Interface ## Interface
``` ```
66-enable [ -h ] [ -z ] [ -v verbosity ] [ -l live ] [ -t tree ] [ -f|F ] [ -c|m|C ] [ -i ] [ -S ] service(s) 66-enable [ -h ] [ -z ] [ -v verbosity ] [ -l live ] [ -t tree ] [ -f|F ] [ -I ] [ -S ] service(s)
``` ```
This tool expects to find a corresponding [frontend service file](frontend.html), a directory name (see [directory](#Directory name as service)) or a *service* instance (see [instance](#Instantiated service)), by default at `%%service_adm%%` or `%%service_system%%` in this order of precedence for root user and `$HOME/%%service_user%%`, `%%service_adm%%` or `%%service_system%%` in this order of precedence for a normal user. The default path can be changed at compile time by passing the `--with-system-service=DIR`, `--with-sysadmin-service=DIR` and `--with-user-service=DIR` to `./configure`. It will run a parser on the frontend service file and write the result to the directory of the given *tree*—see [66-tree](66-tree.html). The *service* will then be available in the given *tree* for the next boot depending on the state of the *tree*. The targeted service(s) can also be started on the fly when enabling it with the **-S** option. This tool expects to find a corresponding [frontend service file](frontend.html), a directory name (see [directory](#Directory name as service)) or a *service* instance (see [instance](#Instantiated service)), by default at `%%service_adm%%` or `%%service_system%%` in this order of precedence for root user and `$HOME/%%service_user%%`, `%%service_adm%%` or `%%service_system%%` in this order of precedence for a normal user. The default path can be changed at compile time by passing the `--with-system-service=DIR`, `--with-sysadmin-service=DIR` and `--with-user-service=DIR` to `./configure`. It will run a parser on the frontend service file and write the result to the directory of the given *tree*—see [66-tree](66-tree.html). The *service* will then be available in the given *tree* for the next boot depending on the state of the *tree*. The targeted service(s) can also be started on the fly when enabling it with the **-S** option.
...@@ -45,15 +45,9 @@ Multiple *services* can be enabled by seperating their names with a space. ...@@ -45,15 +45,9 @@ Multiple *services* can be enabled by seperating their names with a space.
- **-f** : reenables an already enabled *service* with the given options. This option will run again the process from the start and overwrite all existing files. - **-f** : reenables an already enabled *service* with the given options. This option will run again the process from the start and overwrite all existing files.
- **-F** : same as **-f** but also reenables its dependencies. - **-F** : same as **-f** but also reenables its dependencies.
- **-c** : only appends new `key=value` pairs to the environment configuration file of the *frontend* file. - **-I** : do not imports modified configuration files from the previous version used. Refer to [Service configuration file](service-configuration-file.html) for further information.
- **-m** : appends new `key=value` and merges existing one to the environment configuration file from *frontend* file.
- **-C** : overwrites its environment configuration file from *frontend* file.
- **-i** : imports extra configuration files from the previous version used. This is a convenient option which call `66-env -t <tree> -i previous,current <service>` command. Refer to [66-env](66-env.html) for further information.
- **-S** : starts the *service* on the fly directly after enabling it. If the state of the *service* is already up, this option will have no effect unless the **-f** option is used to reload it. - **-S** : starts the *service* on the fly directly after enabling it. If the state of the *service* is already up, this option will have no effect unless the **-f** option is used to reload it.
......
doc/66-hpr.md
+ 5
− 3
View file @ d40c0e02
...@@ -8,11 +8,11 @@ author: Eric Vidal <eric@obarun.org> ...@@ -8,11 +8,11 @@ author: Eric Vidal <eric@obarun.org>
# 66-hpr # 66-hpr
Triggers the software shutdown procedure. Performs an immediate hardware shutdown with the **‑f** option. It is normally invoked by `halt`, `poweroff` or `reboot` wrappers installed by default at `%%skel%%`. This program is a modified copy of [s6-linux-init-hpr](https://skarnet.org/software/s6-linux-init/s6-linux-init-hpr.html). Triggers the software shutdown procedure. Performs an immediate hardware shutdown with the **‑f** option. It is normally invoked by `halt`, `poweroff` or `reboot` wrappers installed by default at `%%skel%%`. This program is a modified copy of [s6-linux-init-hpr](https://skarnet.org/software/s6-linux-init/s6-linux-init-hpr.html).
## Interface ## Interface
``` ```
66-hpr [ -H ] [ -l live ] [ -b banner ] [ -f ] [ -h | -p | -r ] [ -d | -w ] [ -W ] 66-hpr [ -H ] [ -l live ] [ -b banner ] [ -f ] [ -h | -p | -r ] [ -n ] [ -d | -w ] [ -W ]
``` ```
- If the **-f** option is passed the system is stopped or rebooted immediately without properly cleaning up. - If the **-f** option is passed the system is stopped or rebooted immediately without properly cleaning up.
...@@ -42,7 +42,7 @@ This is the traditional sysvinit interface for the `halt`, `poweroff` and `reboo ...@@ -42,7 +42,7 @@ This is the traditional sysvinit interface for the `halt`, `poweroff` and `reboo
The system is going down NOW! The system is going down NOW!
``` ```
- **-f** : force. The command will not trigger a clean shutdown procedure; it will only sync the filesystems then tell the kernel to immediately `halt`, `poweroff` and `reboot`. This should be the last step in the lifetime cycle of the machine. - **-f** : force. The command will not trigger a clean shutdown procedure; it will only sync the filesystems then tell the kernel to immediately `halt`, `poweroff` and `reboot`. This should be the last step in the lifetime cycle of the machine.
- **-h** : halt. The system will be shut down but the power will remain connected. - **-h** : halt. The system will be shut down but the power will remain connected.
...@@ -50,6 +50,8 @@ The system is going down NOW! ...@@ -50,6 +50,8 @@ The system is going down NOW!
- **-r** : reboot. The system will initialize a warm boot without disconnecting power. - **-r** : reboot. The system will initialize a warm boot without disconnecting power.
- **-n** : Do not call [sync()](https://pubs.opengroup.org/onlinepubs/9699919799/functions/sync.html) before the hardware shutdown. The default is to sync, just in case. This option is only relevant when combined with **-f**; without it, it has no effect.
- **-d** : Do not write a wtmp shutdown entry—see [utmp,wtmp and btmp](https://en.wikipedia.org/wiki/Utmp). - **-d** : Do not write a wtmp shutdown entry—see [utmp,wtmp and btmp](https://en.wikipedia.org/wiki/Utmp).
- **-w** : Only write a wtmp shutdown entry; does not actually shut down the system. - **-w** : Only write a wtmp shutdown entry; does not actually shut down the system.
......
doc/66-nuke.md 0 → 100644
+ 11
− 0
View file @ d40c0e02
title: The 66 Suite: 66-nuke
author: Eric Vidal <eric@obarun.org>
[66](index.html)
[obarun.org](https://web.obarun.org)
# 66-nuke
Exact copy of [s6-linux-init-nuke](https://skarnet.org/software/s6-linux-init/s6-linux-init-nuke.html). It was adapted to avoid the dependency on [s6‑linux‑init](https://skarnet.org/software/s6‑linux‑init) at *66* tools compile time. Refer to the [s6‑linux‑init](https://skarnet.org/software/s6‑linux‑init) documentation page for further details.
doc/66-parser.md
+ 4
− 8
View file @ d40c0e02
...@@ -12,7 +12,7 @@ Parses a [frontend](frontend.html) service file and writes the result to a direc ...@@ -12,7 +12,7 @@ Parses a [frontend](frontend.html) service file and writes the result to a direc
## Interface ## Interface
``` ```
66-parser [ -h ] [ -z ] [ -v verbosity ] [ -f ] [ -c|m|C ] service destination 66-parser [ -h ] [ -z ] [ -v verbosity ] [ -f ] [ -I ] service destination
``` ```
...@@ -20,7 +20,7 @@ Parses a [frontend](frontend.html) service file and writes the result to a direc ...@@ -20,7 +20,7 @@ Parses a [frontend](frontend.html) service file and writes the result to a direc
- Runs a parser on the file. - Runs a parser on the file.
- Writes the parsing result to the *destination* directory. - Writes the parsing result to the *destination* directory.
An absolute path is expected for either *service* and *destination*. An absolute path is expected for either *service* and *destination*.
## Exit codes ## Exit codes
...@@ -44,12 +44,8 @@ An absolute path is expected for either *service* and *destination*. ...@@ -44,12 +44,8 @@ An absolute path is expected for either *service* and *destination*.
- **-f** : force. Owerwrite an existing parsing result at *destination*. - **-f** : force. Owerwrite an existing parsing result at *destination*.
- **-c** : only appends new `key=value` pairs to the environment configuration file from [frontend](frontend.html) file. - **-I** : do not imports modified configuration files from the previous version used. Refer to [Service configuration file](service-configuration-file.html) for further information.
- **-m** : appends new `key=value` and merges existing one to the environment configuration file from [frontend](frontend.html) file.
- **-C** : overwrite it environment configuration file from [frontend](frontend.html) file.
## Notes ## Notes
*66-parser* will not try to read and parse any services declared under the `@contents`, `@depends`, `@optsdepends` or `@extdepends` key of the given [frontend](frontend.html) file even for a service `module` type. This tool is mainly intended for debugging purposes and to see the result of a parsing process before actually enabling the service on the system. The tool uses the exact same parser as [66‑enable](66-enable.html) which by default writes the configuration file to `%%service_admconf%%/service_name`. As a consequence any corresponding existing file will be overwritten. To avoid this, it writes the configuration file to the *destination/env/* directory and adjust the resulting *run/finish* file to match the configuration file path. *66-parser* will not try to read and parse any services declared under the `@contents`, `@depends`, `@optsdepends` or `@extdepends` key of the given [frontend](frontend.html) file even for a service `module` type. This tool is mainly intended for debugging purposes and to see the result of a parsing process before actually enabling the service on the system. The tool uses the exact same parser as [66‑enable](66-enable.html) which by default writes the configuration file to `%%service_admconf%%/service_name`. As a consequence any corresponding existing file will be overwritten. To avoid this, it writes the configuration file to the *destination/env/* directory and adjust the resulting *run/finish* file to match the configuration file path.
doc/66-scanctl.md
+ 10
− 2
View file @ d40c0e02
...@@ -7,12 +7,12 @@ author: Eric Vidal <eric@obarun.org> ...@@ -7,12 +7,12 @@ author: Eric Vidal <eric@obarun.org>
# 66-scanctl # 66-scanctl
Sends a *signal* to a scandir. Safe wrapper around [s6‑svscanctl](https://skarnet.org/software/s6/s6-svscanctl.html). Sends a *signal* to a scandir. Safe wrapper around [s6‑svscanctl](https://skarnet.org/software/s6/s6-svscanctl.html).
## Interface ## Interface
``` ```
66-scanctl [ -h ] [ -z ] [ -v verbosity ] [ -l live ] [ -o owner ] signal 66-scanctl [ -h ] [ -z ] [ -v verbosity ] [ -l live ] [ -d notif ] [ -t rescan ] [ -o owner ] signal
``` ```
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. 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.
...@@ -37,6 +37,10 @@ This program sends a *signal* to an already running [scandir](scandir.html) at * ...@@ -37,6 +37,10 @@ This program sends a *signal* to an already running [scandir](scandir.html) at *
- **-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). - **-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`.
- **-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. - **-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 ## Signal
...@@ -62,3 +66,7 @@ This command is strictly equal to: ...@@ -62,3 +66,7 @@ This command is strictly equal to:
``` ```
s6-svscanctl -an /path_to_scandir s6-svscanctl -an /path_to_scandir
``` ```
- **-u** : start the *scandir* directory at *live* calling [s6‑svscan](https://skarnet.org/software/s6/s6-svscan.html).
doc/66-scandir.md
+ 29
− 27
View file @ d40c0e02
...@@ -12,10 +12,10 @@ Handles the *scandir* for a given user. Designed to be either root or a branch o ...@@ -12,10 +12,10 @@ Handles the *scandir* for a given user. Designed to be either root or a branch o
## Interface ## Interface
``` ```
66-scandir [ -h ] [ -z ] [ -v verbosity ] [ -b ] [ -l live ] [ -d notif ][ -t rescan ] [ -L log_user ] [ -s skel ] [ -e environment ] [ -c | r | u ] owner 66-scandir [ -h ] [ -z ] [ -v verbosity ] [ -l live ] [ -b|B ] [ -c ] [ -L log_user ] [ -s skel ] [ -e environment ] [ -o owner ] create|remove
``` ```
This program creates or starts the *scandir* (directory containing a collection of s6‑supervise processes) for the given *owner* depending on the provided options. 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. If *owner* is not explicitely set then the user of the current process will be used instead. 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 ## Exit codes
...@@ -35,13 +35,17 @@ This program creates or starts the *scandir* (directory containing a collection ...@@ -35,13 +35,17 @@ This program creates or starts the *scandir* (directory containing a collection
* *3* : also print tracing messages. * *3* : also print tracing messages.
* *4* : also print debugging messages. * *4* : also print debugging messages.
- **-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.
- **-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. - **-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.
- **-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. - **-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.
- **-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`. - **-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%%`. - **-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%%`.
...@@ -49,15 +53,11 @@ This program creates or starts the *scandir* (directory containing a collection ...@@ -49,15 +53,11 @@ This program creates or starts the *scandir* (directory containing a collection
- **-e** *environment* : an absolute path. Merge the current environment variables of *scandir* with variables found in this directory. Any file in environment not beginning with a dot and not containing the `=` character will be read and parsed. - **-e** *environment* : an absolute path. Merge the current environment variables of *scandir* with variables found in this directory. Any file in environment not beginning with a dot and not containing the `=` character will be read and parsed.
- **-c** : create the neccessary directories at *live*. ***Must be*** executed once with this option before being able to use **‑u**. - **-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.
- **-r** : remove the *scandir* directory at *live*. If it was already started with **‑u** it ***must*** first be stopped sending a signal with [66‑scanctl quit](66-scanctl.html) or similar.
- **-u** : start the *scandir* directory at *live* calling [s6‑svscan](https://skarnet.org/software/s6/s6-svscan.html).
## Scandir creation process ## Scandir creation process
When creating the *scandir* with the **‑c** option various files and directories will be created at the *live* directory for the given *owner*. 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): 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):
...@@ -78,21 +78,15 @@ If the *scandir* was created with a regular user you will find the following in ...@@ -78,21 +78,15 @@ If the *scandir* was created with a regular user you will find the following in
- *%%livedir%%/state/1000* - *%%livedir%%/state/1000*
If a *scandir* already existed at the default location for the given user it will prevent its creation when calling `66‑scandir ‑c`. If you wanted to create a different scandir for the same owner at the same live location you must delete it first with **‑r**. 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.
## Environment configuration 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`.
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 `4095` bytes or more than `50` `key=value` pairs.
## Scandir removal process ## Scandir removal process
When using the **‑r** option to delete the *scandir* of a given user 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: 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%%/scandir/0* # will be deleted
...@@ -104,10 +98,18 @@ When using the **‑r** option to delete the *scandir* of a given user some dire ...@@ -104,10 +98,18 @@ When using the **‑r** option to delete the *scandir* of a given user some dire
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. 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.
**Note**: A running *scandir* can not be removed. It needs to be stopped first with [66-scanctl](66‑scanctl.html) quit or similar to be able to remove it.
## Boot specification ## Boot specification
The **-b** and **-s** option are called by [66-boot](66-boot.html). **‑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 **-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 *live* directory for the boot process requires writable directories. 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. 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.
doc/66-shutdownd.md
+ 6
− 2
View file @ d40c0e02
...@@ -7,12 +7,12 @@ author: Eric Vidal <eric@obarun.org> ...@@ -7,12 +7,12 @@ author: Eric Vidal <eric@obarun.org>
# 66-shutdownd # 66-shutdownd
The daemon that manages the shutdown procedure for a [66-boot](66-boot.html) installation. It is not meant to be called directly. This program is a modified copy of [s6-linux-init-shudownd](https://skarnet.org/software/s6-linux-init/s6-linux-init-shutdownd.html). The daemon that manages the shutdown procedure for a [66-boot](66-boot.html) installation. It is not meant to be called directly. This program is a modified copy of [s6-linux-init-shudownd](https://skarnet.org/software/s6-linux-init/s6-linux-init-shutdownd.html).
## Interface ## Interface
``` ```
66-shutdownd [ -h ] [ -l live ] [ -s skel ] [ -g gracetime ] 66-shutdownd [ -h ] [ -l live ] [ -s skel ] [ -g gracetime ] [ -B ] [ -c ]
``` ```
- 66-shutdownd opens the `%%livedir%%/scandir/0/shutdownd/fifo` pipe and listens to it. Programs such as [66-shutdown](66-shutdown.html) send their commands to this pipe when they are told to trigger the shutdown procedure. - 66-shutdownd opens the `%%livedir%%/scandir/0/shutdownd/fifo` pipe and listens to it. Programs such as [66-shutdown](66-shutdown.html) send their commands to this pipe when they are told to trigger the shutdown procedure.
...@@ -39,6 +39,10 @@ The daemon that manages the shutdown procedure for a [66-boot](66-boot.html) ins ...@@ -39,6 +39,10 @@ The daemon that manages the shutdown procedure for a [66-boot](66-boot.html) ins
- **-g** *gracetime* : specify a grace time between the `SIGTERM` and the `SIGKILL` in milliseconds if the shutdown command does not provide one. Defaults to `3000`. - **-g** *gracetime* : specify a grace time between the `SIGTERM` and the `SIGKILL` in milliseconds if the shutdown command does not provide one. Defaults to `3000`.
- **-B** : inform the shutdown daemon that it is running in a container. This changes the nature of *stage 4*, since exiting a container is slightly different from rebooting a real machine (in particular, pid 1 has to exit, and great care must be given not to leave any zombie hanging around).
- **-c** : inform the shutdown daemon that no catch-all logger is running. This also changes the shutdown procedure slightly, since some operations are specific to the existence of a catch-all logger.
## Note ## Note
The *66-shutdownd* binary is not meant to be called directly. It is automatically generated by a [66-scandir](66‑scandir.html) program invocation. The *66-shutdownd* binary is not meant to be called directly. It is automatically generated by a [66-scandir](66‑scandir.html) program invocation.
doc/frontend.md
+ 0
− 6
View file @ d40c0e02
...@@ -520,12 +520,6 @@ This section is *mandatory*. (!) ...@@ -520,12 +520,6 @@ This section is *mandatory*. (!)
valid values : valid values :
* nosetsid : Corresponds to the file *nosetsid* of [s6](https://skarnet.org/software/s6) and [s6-rc](https://skarnet.org/software/s6-rc) programs
This will create the file nosetsid
Once this file was created the service will be run in the same process group as the supervisor of the service ([s6-supervise](https://skarnet.org/software/s6/s6-supervise.html)). Without this file the service will have its own process group and is started as a session leader.
* down : Corresponds to the file *down* of [s6](https://skarnet.org/software/s6) and [s6-rc](https://skarnet.org/software/s6-rc) programs. * down : Corresponds to the file *down* of [s6](https://skarnet.org/software/s6) and [s6-rc](https://skarnet.org/software/s6-rc) programs.
This will create the file down This will create the file down
......
doc/make-html.sh
+ 1
− 1
View file @ d40c0e02
#!/bin/sh #!/bin/sh
html='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update 66-boot 66-hpr 66-shutdown 66-shutdownd 66-umountall 66-update frontend instantiated-service module-service index execl-envfile upgrade' html='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update 66-boot 66-hpr 66-shutdown 66-shutdownd 66-umountall 66-update 66-nuke frontend instantiated-service module-service index execl-envfile upgrade'
version=${1} version=${1}
......
doc/make-man.sh
+ 1
− 1
View file @ d40c0e02
#!/bin/sh #!/bin/sh
man1='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update execl-envfile' man1='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update 66-nuke execl-envfile'
man8='66-boot 66-hpr 66-shutdown 66-shutdownd 66-umountall' man8='66-boot 66-hpr 66-shutdown 66-shutdownd 66-umountall'
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment