From dfa16e4a89158f3d3198db71e2eba3bda9330078 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 10 Sep 2016 13:29:56 +0000 Subject: Make s6-linux-init a real init package. This means: - removing leaky options to s6-linux-init-maker. Default initial_path is now always /usr/bin:/bin; the uid and gid of the catch-all logger (used at boot time) can now be given numerically instead of relying on the (run-time) user db mapping. - moving s6-halt, s6-poweroff and s6-reboot over here, from s6-linux-utils - clarifying on the documentation a bit. --- doc/index.html | 6 ++- doc/quickstart.html | 11 ++++- doc/s6-halt.html | 55 ++++++++++++++++++++++ doc/s6-linux-init-maker.html | 110 ++++++++++++++++++++++++++----------------- doc/s6-poweroff.html | 55 ++++++++++++++++++++++ doc/s6-reboot.html | 55 ++++++++++++++++++++++ doc/upgrade.html | 7 +++ 7 files changed, 255 insertions(+), 44 deletions(-) create mode 100644 doc/s6-halt.html create mode 100644 doc/s6-poweroff.html create mode 100644 doc/s6-reboot.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 47226b4..5c39b78 100644 --- a/doc/index.html +++ b/doc/index.html @@ -64,7 +64,8 @@ a small FAQ.

When you build s6-linux-init, the s6-linux-init-maker tool -is created; then you run that tool to create an init script, +is created (as well as the shutdown commands); + then you run that tool to create an init script, and then you can boot your system on that init script.

@@ -122,6 +123,9 @@ the previous versions of s6-linux-init and the current one.

Related resources

diff --git a/doc/quickstart.html b/doc/quickstart.html index bd758b1..dac9779 100644 --- a/doc/quickstart.html +++ b/doc/quickstart.html @@ -20,7 +20,7 @@

Quickstart

Install all the s6-linux-init dependencies:
- skalibs
- Make sure you have a /run directory
- Write a machine initialization script in /etc/rc.init and a machine shutdown script in /etc/rc.shutdown. Make them executable.
- If, at shutdown time, you need to run a script before the +supervision tree is torn down (for instance if you're using +s6-rc and want to +cleanly stop all your services), write that script in +/etc/rc.tini.
- Check that your devtmpfs is automounted by your kernel at boot time. If it is not, add the -d 1 option to the s6-linux-init-maker command line below.
- As root, run:
```
@@ -44,6 +49,10 @@ add the -d 1 option to the s6-linux-init-maker command line be
      ln -sf /etc/s6-linux-init/init /sbin/init 
```
- Reboot.
- Congratulations! your machine is now running a s6-based init system.
- To shut the machine down, use the +s6-halt, +s6-poweroff or +s6-reboot command as appropriate.
FAQ
diff --git a/doc/s6-halt.html b/doc/s6-halt.html new file mode 100644 index 0000000..b6a326c --- /dev/null +++ b/doc/s6-halt.html @@ -0,0 +1,55 @@ + + + + + + s6-linux-init: the s6-halt program + + + + + + +
+s6-linux-init
+Software
+skarnet.org +
+ +
The s6-halt program
+ +
+s6-halt sends a signal to process 1 in order to halt the machine; +or, with the -f option, it performs an immediate hard shutdown. +
+ +
Interface
+ +
```
+     s6-halt [ -h | -p | -r ] [ -f ]
+
```
+ +
- s6-halt sends a signal to process 1.
- It then exits 0.
+ +
Options
+ +
- -h : halt. The command will order a halt (i.e. the system will +be shut down, but the power will remain up), which means +sending a SIGUSR2 to process 1. This is the default.
- -p : poweroff. The command will order a power off, which means +sending a SIGUSR1 to process 1.
- -r : reboot. The command will order a reboot, which means +sending a SIGINT to process 1.
- -f : force. The command will not send any signal to process 1; +it will just sync the filesystems then tell the kernel to halt, poweroff or reboot. +s6-reboot -f or s6-poweroff -f should be the last program +executed in the lifetime of a machine, at the end of the shutdown script called +by process 1 when it receives a signal telling it to shut down.
+ + + diff --git a/doc/s6-linux-init-maker.html b/doc/s6-linux-init-maker.html index e82ce40..4eee9db 100644 --- a/doc/s6-linux-init-maker.html +++ b/doc/s6-linux-init-maker.html @@ -51,8 +51,8 @@ machine - else the scripts will crash. [ -c basedir ] \ [ -l tmpfsdir ] \ [ -b execline_bindir ] \ - [ -u log_user ] \ - [ -g early_getty ] \ + [ -u log_uid -g log_gid | -U ] \ + [ -G early_getty ] \ [ -2 stage2 ] \ [ -r ] \ [ -Z ] stage2_finish \ @@ -173,48 +173,63 @@ real machine and service initialization should happen in stage2.
Shutdown sequence
-
- When s6-svscan is told to exit via an appropriate -s6-svscanctl -command, it executes into the stage3 script, which, like -stage2, is the responsibility of the administrator. stage3 -is run in the following state: -
+
- A shutdown is performed when the administrator runs one of the +s6-halt, +s6-poweroff or +s6-reboot commands.
- Those commands send a signal to the +s6-svscan +process running as pid 1; this signal is caught and s6-svscan runs the +corresponding "signal handler" script that has been placed by +s6-linux-init-maker into the +basedir/run-image/service/.s6-svscan directory (and that +has been copied at boot time to tmpfsdir/service/.s6-svscan).
- That script first spawns the stage2_finish script, who +must have been written by the administrator. The purpose of +stage2_finish is to perform the high-level shutdown sequence +while the supervision tree is still alive. Typically, when using a +service manager, stage2_finish would tell the service manager +to bring all services down. When using +s6-rc, a typical +stage2_finish script just contains s6-rc -da change. + More generally speaking, stage2_finish should undo what +stage2 has done at boot time.
- The "signal handler" script then tells s6-svscan to exit via an +appropriate s6-svscanctl +command: s6-svscan then executes into the stage3 script, which, like +stage2 and stage2_finish, is the responsibility of the +administrator. When stage3 runs, the machine is in the following +state:
  - It runs as process 1. (Doing so makes it easier to recover after -killing all processes by kill -9 -1 or -s6-nuke).
  - The supervision tree has been torn down: it is not operational +anymore. (So, commands such as +s6-rc, which +require a live supervision tree, will not work.) +
  - stage3 runs as process 1. Doing so makes it easier to recover +after killing all processes by kill -9 -1 or +s6-nuke.
  - Its working directory is / and its stdin is /dev/null
  - Its stdout and stderr are both /dev/console
  - Depending on the exact s6-svscanctl command that terminated s6-svscan, -and what has happened before that command was sent, there may or may not be +
  - Depending on the exact configuration and what the administrator has +written in stage2_finish, there may or may not be long-running services that remain alive. The catch-all logger and its -supervisor will always be alive, which is not a problem because they +supervisor will always be alive; this is not a problem because they do not hold any file descriptor to a filesystem that would need to be unmounted.
  +

- When s6-svscan receives a signal such as SIGINT, typically sent by the -Ctrl-Alt-Del key combination or a reboot or poweroff -command, it will run the corresponding script in -tmpfsdir/service/.s6-svscan, which will first run -stage2_finish, then send an exit command to s6-svscan as -described above. This is useful if some commands need to be run before -s6-svscan executes into stage3: for instance, if the machine -state is maintained by a service manager such as -s6-rc, all the -services can be turned off in stage2_finish while s6-svscan -is still alive, and then the last steps of the shutdown procedure can -be performed in stage3. -

The last command that stage3 executes should be +s6-$1 -f, $1 being the first argument that has been +given to it. This command will instantly execute the hard system halt, +poweroff or reboot that has initially been asked by the admin.

- Generally speaking, stage2_finish should undo what -stage2 has done at boot time, so stage3 has very -little work to do. -

The examples/ subdirectory of the s6-linux-init package @@ -251,11 +266,24 @@ launcher and the first few early commands before PATH can be set. found. It must be absolute. Default is /bin.

-u log_user : the catch-all -logger will not run as root, but as log_user. Default is -nobody.

-u log_uid : the catch-all +logger will run with the uid log_uid. Default is 0.

+ +

-g log_gid : the catch-all +logger will run with the gid log_gid. Default is 0.

+ +

-U : the correct log_uid and +log_gid values for the catch-all logger will be read from the +UID and GID environment variables that have been passed to +s6-linux-init-maker. This allows for invocations such as +s6-envuidgid nobody s6-linux-init-maker -U ... so that +the catch-all logger runs as the nobody user. Be aware that +this option is only safe when the user database on the +boot-time machine is the same as on the run-time +machine, else the catch-all logger may run with an unexpected uid +and gid.

-g early_getty : if this option +

-G early_getty : if this option is set, s6-linux-init-maker will define a service that will run very early, before stage2 is executed. This early service should be a getty, to allow logins even if stage2 fails. @@ -297,9 +325,7 @@ absolutely necessary for s6-portable-utils and s6-linux-utils binaries to be accessible via initial_path, else the machine -will not boot. Default is the value that has been compiled in -skalibs via the ---with-default-path configure option, i.e. by default +will not boot. Default is /usr/bin:/bin.

-m initial_umask : the value of diff --git a/doc/s6-poweroff.html b/doc/s6-poweroff.html new file mode 100644 index 0000000..9a268af --- /dev/null +++ b/doc/s6-poweroff.html @@ -0,0 +1,55 @@ + + + + + + s6-linux-init: the s6-poweroff program + + + + + + +

+s6-linux-init
+Software
+skarnet.org +

+ +

The `s6-poweroff` program

+ +

+s6-poweroff sends a signal to process 1 in order to power off the machine; +or, with the -f option, it performs an immediate hard shutdown. +

+ +

Interface

+ +

+     s6-poweroff [ -h | -p | -r ] [ -f ]
+

+ +

s6-poweroff sends a signal to process 1.
It then exits 0.

+ +

Options

+ +

-h : halt. The command will order a halt (i.e. the system will +be shut down, but the power will remain up), which means +sending a SIGUSR2 to process 1.
-p : poweroff. The command will order a power off, which means +sending a SIGUSR1 to process 1. This is the default.
-r : reboot. The command will order a reboot, which means +sending a SIGINT to process 1.
-f : force. The command will not send any signal to process 1; +it will just sync the filesystems then tell the kernel to halt, poweroff or reboot. +s6-reboot -f or s6-poweroff -f should be the last program +executed in the lifetime of a machine, at the end of the shutdown script called +by process 1 when it receives a signal telling it to shut down.

+ + + diff --git a/doc/s6-reboot.html b/doc/s6-reboot.html new file mode 100644 index 0000000..e116235 --- /dev/null +++ b/doc/s6-reboot.html @@ -0,0 +1,55 @@ + + + + + + s6-linux-init: the s6-reboot program + + + + + + +

+s6-linux-init
+Software
+skarnet.org +

+ +

The `s6-reboot` program

+ +

+s6-reboot sends a signal to process 1 in order to reboot the machine; +or, with the -f option, it performs an immediate reboot. +

+ +

Interface

+ +

+     s6-reboot [ -h | -p | -r ] [ -f ]
+

+ +

s6-reboot sends a signal to process 1.
It then exits 0.

+ +

Options

+ +

-h : halt. The command will order a halt (i.e. the system will +be shut down, but the power will remain up), which means +sending a SIGUSR2 to process 1.
-p : poweroff. The command will order a power off, which means +sending a SIGUSR1 to process 1.
-r : reboot. The command will order a reboot, which means +sending a SIGINT to process 1. This is the default.
-f : force. The command will not send any signal to process 1; +it will just sync the filesystems then tell the kernel to halt, poweroff or reboot. +s6-reboot -f or s6-poweroff -f should be the last program +executed in the lifetime of a machine, at the end of the shutdown script called +by process 1 when it receives a signal telling it to shut down.

+ + + diff --git a/doc/upgrade.html b/doc/upgrade.html index 49dbb2e..bc2c722 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -31,6 +31,13 @@ dependency bumped to 2.1.0.0.

dependency bumped to 2.2.0.0.

s6 dependency bumped to 2.4.0.0.

s6-halt, + s6-poweroff and + s6-reboot moved from +s6-linux-utils +to s6-linux-init.

s6-linux-init-maker +options modified. (Read the documentation!)

in 0.1.0.0

-- cgit v1.2.3

Related resources

Quickstart

FAQ

The s6-halt program

Interface

Options

Shutdown sequence

The s6-poweroff program

Interface

Options

The s6-reboot program

Interface

Options

in 0.1.0.0

The `s6-halt` program

The `s6-poweroff` program

The `s6-reboot` program