From c2c14b525080203561d9e47d8a10442828342251 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 13 Jan 2018 14:33:25 +0000 Subject: Autogenerate final shutdown; rename rc.tini to rc.shutdown --- doc/index.html | 10 ++--- doc/quickstart.html | 69 +++++++++++++++++++++++++----- doc/s6-linux-init-maker.html | 99 +++++++++++++++++++++----------------------- doc/upgrade.html | 17 ++++++++ 4 files changed, 129 insertions(+), 66 deletions(-) (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 598b50b..49aed5f 100644 --- a/doc/index.html +++ b/doc/index.html @@ -50,15 +50,15 @@ a small FAQ.
  • A Linux-based system with a standard C development environment
  • GNU make, version 3.81 or later
  • skalibs version -2.6.0.0 or later
    • +2.6.3.0 or later
  • execline version -2.3.0.2 or later
    • +2.3.0.4 or later
  • s6-portable-utils version 2.2.1.1 or later
  • s6-linux-utils version -2.4.0.0 or later
    • +2.4.0.2 or later
  • s6 version -2.6.1.0 or later
    • +2.7.0.0 or later

    @@ -87,7 +87,7 @@ against the shared version of the skalibs library, it also becomes a

    -
  • Install s6-linux-init itself
    • -
  • Save your old /sbin/init binary
    • -
  • Save and remove your old /etc/s6-linux-init directory, if you have one
    • -
  • Make sure you have a /run directory
    • +
  • Install s6-linux-init itself.
    • +
  • Save your old /sbin/init binary.
    • +
  • Save and remove your old /etc/s6-linux-init directory, if you have one.
    • +
  • 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.
    • +a machine shutdown script in /etc/rc.shutdown. Make sure they are +executable. See below for more information on how to write these scripts.
  • 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: 
    @@ -53,8 +49,61 @@ add the -d 1 option to the s6-linux-init-maker command line be
 s6-halt,
 s6-poweroff or
 s6-reboot command as appropriate.
    • + + +

    What should go into /etc/rc.init and /etc/rc.shutdown ?

    + +

    /etc/rc.init

    + +

    + This script will be run after s6-linux-init has done is job, i.e. +s6-svscan is running as process 1, and it +is now up to /etc/rc.init to get the machine to its usable state. +It normally contains a call to the service manager to bring up all the services; +for instance, if you're using +s6-rc as your service manager, and +your top bundle (containing all the services you want to bring up) is named +ok-all, a proper /etc/rc.init could look like this: +

    + +
    #!/bin/sh
+s6-rc-init /run/service && exec s6-rc -u change ok-all
+
    + +

    + The script can assume that: +

    + + +

    /etc/rc.shutdown

    + +

    + This script is spawned by s6-svscan +when the administrator calls s6-halt, +s6-poweroff or +s6-reboot. When this script exits, the final +shutdown sequence is run, which means that the supervision tree is dismantled, +all processes are killed, the file systems are umounted and the system +undergoes a hardware shutdown or reboot. So the goal of this script is to +bring services down in an orderly fashion and perform all the necessary +cleanups before all remaining processes are summarily killed. +

    + +

    + If you're using s6-rc as your +service manager, a proper /etc/rc.shutdown could look like this: +

    + +
    #!/bin/sh
+exec s6-rc -da change
+
    +

    FAQ

    Why is it so complicated to use s6 as an init process? It's much diff --git a/doc/s6-linux-init-maker.html b/doc/s6-linux-init-maker.html index 5ba7326..4c0b51d 100644 --- a/doc/s6-linux-init-maker.html +++ b/doc/s6-linux-init-maker.html @@ -53,10 +53,9 @@ machine - else the scripts will crash. [ -b execline_bindir ] \ [ -u log_uid -g log_gid | -U ] \ [ -G early_getty ] \ - [ -2 stage2 ] \ + [ -2 initscript ] \ [ -r ] \ - [ -Z ] stage2_finish \ - [ -3 stage3 ] \ + [ -Z ] shutdownscript \ [ -p initial_path ] \ [ -m initial_umask ] \ [ -t timestamp_style ] \ @@ -64,6 +63,7 @@ machine - else the scripts will crash. [ -s env_store ] \ [ -e initial_envvar ] ... \ [ -n ] \ + [ -q ] finalsleeptime dir @@ -131,19 +131,19 @@ instead of clogging the system console. scan directory will also contain a service for an early getty.
  • s6-svscan starts all the services defined in the scan directory, and unblocks the child forked by stage 1.
    • -
  • This child executes into stage2.
    • +
  • This child executes into initscript.

    • - stage2 is the responsibility of the administrator - it will + initscript is the responsibility of the administrator - it will not be written automatically! It should contain all the necessary initialization sequence to bring up a proper -system. When stage2 is executed, the machine state is as follows: +system. When initscript is executed, the machine state is as follows:

    @@ -167,9 +167,10 @@ getty is essentially to make it easier to debug if stage2 fails. mounted yet, including /proc and /sys; and no one-time initialization has been performed. The point of stage 1 is only to make it -possible to run stage2 with a logging infrastructure and a +possible to run initscript with a logging infrastructure and a supervision infrastructure already available, and all the -real machine and service initialization should happen in stage2. +real machine and service initialization should happen in initscript, +also known as stage 2.

    Shutdown sequence

    @@ -189,54 +190,46 @@ 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 +
  • That script first spawns the shutdownscript script, who must have been written by the administrator. The purpose of -stage2_finish is to perform the high-level shutdown sequence +shutdownscript 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 +service manager, shutdownscript 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 + More generally speaking, shutdownscript 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: +command: s6-svscan then executes into the final shutdown sequence. This +sequence is made of the following actions:
    • -
  • 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.
    • -

    The examples/ subdirectory of the s6-linux-init package -contains an example of /etc/rc.init, /etc/rc.tini +contains an example of /etc/rc.init and /etc/rc.shutdown scripts, suitable for -stage2, stage2_finish and stage3 +initscript and shutdownscript respectively. Those scripts can practically be used as is if the machine is managed by the s6-rc service manager. @@ -292,7 +285,7 @@ should be a getty, to allow logins even if stage2 fails. "/sbin/getty 38400 tty1". By default, no early service is defined.

    -

  • -2 stage2 : stage2 is +
  • -2 initscript : initscript is the location of the stage 2 script that will be run when the system has an operational supervision tree. It must be absolute. Default is /etc/rc.init.

    • @@ -305,21 +298,15 @@ with an early getty, or be undesirable for other reasons. The to the catch-all logger, so the output will be made available in the tmpfsdir/uncaught-logs directory.

    -

  • -Z stage2_finish : -stage2_finish is the location of the script that will be +
  • -Z shutdownscript : +shutdownscript is the location of the script that will be run when s6-svscan receives a signal that tells it to stop the -machine, before it executes into stage3. It must be -absolute. Default is /etc/rc.tini. +machine, before it executes into the final shutdown sequence. It must be +absolute. Default is /etc/rc.shutdown. Note that this script is run with its stdout and stderr redirected to the tmpfsdir/uncaught-logs logging directory, so its output will not appear on the system's console.

    • -

  • -3 stage3 : stage3 is -the location of the stage 3 script that will be run at the end of -the machine lifetime, when s6-svscan is told to terminate. -It must be absolute. Default is -/etc/rc.shutdown.

    • -

  • -p initial_path : the value to set the PATH environment variable to, for all the starting processes. This will be done as early as possible in stage 1. It is @@ -383,6 +370,16 @@ and .s6-svscan/SIGINT scripts slightly, in order to provide adequate functionality when the containerized system is asked to shutdown. Do not add this option if the init script is going to run in the root pid namespace.

    • + +

  • -q finalsleeptime : when the machine +shuts down, all processes that have not already been killed during +shutdownscript will receive a SIGTERM or a SIGHUP to allow +them to exit gracefully; then, after finalsleeptime +milliseconds, they will receive a SIGKILL and the shutdown sequence +will go on. This option configures the amount of time that will +elapse between the SIGTERM/SIGHUP and the SIGKILL. +Default is 2000, meaning a grace period of 2 seconds.

    • +

    Notes

    diff --git a/doc/upgrade.html b/doc/upgrade.html index aa04135..7acdf64 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -18,6 +18,23 @@

    What has changed in s6-linux-init

    +

    in 0.4.0.0

    + + +

    in 0.3.1.1