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/s6-linux-init-maker.html | 99 +++++++++++++++++++++----------------------- 1 file changed, 48 insertions(+), 51 deletions(-) (limited to 'doc/s6-linux-init-maker.html') 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

    -- cgit v1.2.3