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 --- .gitignore | 9 ++-- COPYING | 2 +- INSTALL | 8 ++-- NEWS | 10 +++++ doc/index.html | 10 ++--- doc/quickstart.html | 69 ++++++++++++++++++++++++----- doc/s6-linux-init-maker.html | 99 ++++++++++++++++++++---------------------- doc/upgrade.html | 17 ++++++++ examples/rc.init | 12 +---- examples/rc.shutdown | 30 ++++++------- examples/rc.tini | 16 ------- package/info | 2 +- src/init/s6-linux-init-maker.c | 36 +++++++++------ 13 files changed, 189 insertions(+), 131 deletions(-) delete mode 100755 examples/rc.tini diff --git a/.gitignore b/.gitignore index 5c6415e..6b2e3dd 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,8 @@ *.o -*.a *.lo -*.so -*.so.* +/config.mak +/src/include/s6-linux-init/config.h +/s6-linux-init-maker +/s6-halt +/s6-poweroff +/s6-reboot diff --git a/COPYING b/COPYING index a34920e..ca90f6c 100644 --- a/COPYING +++ b/COPYING @@ -1,4 +1,4 @@ -Copyright (c) 2015-2017 Laurent Bercot +Copyright (c) 2015-2018 Laurent Bercot Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above diff --git a/INSTALL b/INSTALL index 5562636..8b11fa8 100644 --- a/INSTALL +++ b/INSTALL @@ -6,15 +6,15 @@ Build Instructions - 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: http://skarnet.org/software/skalibs/ + - skalibs version 2.6.3.0 or later: http://skarnet.org/software/skalibs/ The scripts generated by the s6-linux-init-maker program have some additional dependencies: - - execline version 2.3.0.2 or later: http://skarnet.org/software/execline/ + - execline version 2.3.0.4 or later: http://skarnet.org/software/execline/ - s6-portable-utils version 2.2.1.1 or later: http://skarnet.org/software/s6-portable-utils/ - - s6-linux-utils version 2.4.0.0 or later: http://skarnet.org/software/s6-linux-utils/ - - s6 version 2.6.1.0 or later: http://skarnet.org/software/s6/ + - s6-linux-utils version 2.4.0.2 or later: http://skarnet.org/software/s6-linux-utils/ + - s6 version 2.7.0.0 or later: http://skarnet.org/software/s6/ This software is Linux-specific. It will run on a Linux kernel, version 2.6.32 or later. However, it should not be too hard to port to diff --git a/NEWS b/NEWS index e84a356..df33cd5 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,15 @@ Changelog for s6-linux-init. +In 0.4.0.0 +---------- + + - The old /etc/rc.shutdown is now created by s6-linux-init-maker +and is not the user's responsibility anymore. + - /etc/rc.tini is now named /etc/rc.shutdown. In summary: +now, /etc/rc.shutdown marks the end of stage 2, not stage 3, +and stage 3 is all automatically generated. + + In 0.3.1.1 ---------- 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

    • The current released version of s6-linux-init is -0.3.1.1.
      • +0.4.0.0.
    • Alternatively, you can checkout a copy of the s6-linux-init git repository: diff --git a/doc/quickstart.html b/doc/quickstart.html index 619fbbd..6a0069b 100644 --- a/doc/quickstart.html +++ b/doc/quickstart.html @@ -29,17 +29,13 @@
    • s6-linux-utils
    • s6
    -
  • 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: +

    + +
      +
    • There is a tmpfs partition, only writable by root, mounted on /run
      • +
    • There is a s6 supervision tree +running on /run/service
      • +
    • /dev is mounted, but /proc and /sys are not
    +

    /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:

      -
    • stage2's working directory is / and its stdin +
    • initscript's working directory is / and its stdin is /dev/null. Its stdout and stderr both point either to /dev/console or to the pipe to the catch-all logger, depending on the -r option.
      • @@ -159,7 +159,7 @@ into tmpfsdir/service, then running the command s6-svscanctl -a tmpfsdir/service. Services without a dedicated logger will send their output to the catch-all logger.
    • A getty service may already be available. The point of this early -getty is essentially to make it easier to debug if stage2 fails.
      • +getty is essentially to make it easier to debug if initscript fails.

    @@ -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 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 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; this is not a problem because they -do not hold any file descriptor to a filesystem that would need to be -unmounted.
      • +
    • The supervision tree gets torn down.
      • +
    • All data is flushed to disk.
      • +
    • All processes get a SIGTERM, a SIGHUP, and a SIGCONT. This should +allow all processes to die gracefully. Note that most processes should +already have been killed during the /etc/rc.shutdown execution; +this phase only catches stragglers, background processs, etc.
      • +
    • The sequence sleeps for finalsleeptime milliseconds, to +allow all processes to finish their clean exit routine.
      • +
    • All processes get a SIGKILL.
      • +
    • All zombies are reaped.
      • +
    • All filesystems get unmounted, and the root filesystem is remounted +read-only.
      • +
    • The machine performs a hardware reboot, halt or poweroff, depending +on the command that has been used.
    • -
  • 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

    + +
      +
    • skalibs +dependency bumped to 2.6.3.0.
      • +
    • execline +dependency bumped to 2.3.0.4.
      • +
    • s6 +dependency bumped to 2.7.0.0.
      • +
    • s6-linux-init-maker now +autogenerates stage 3, which is not the responsibility of the user +anymore (stage 3 was previously the user-written /etc/rc.shutdown +script).
      • +
    • The default user-provided "end of stage 2, bring down services" script +was named /etc/rc.tini before; now it's named /etc/rc.shutdown.
      • +
    +

    in 0.3.1.1

      diff --git a/examples/rc.init b/examples/rc.init index d71fd1a..afc7735 100755 --- a/examples/rc.init +++ b/examples/rc.init @@ -1,17 +1,9 @@ #!/bin/execlineb -P - -# Make sure the /dev/urandom entropy pool will be set in -# a not-too-distant future. Ideally we'd block on this, -# but it's not critical, so we don't. - -background -d { s6-fillurandompool } - - # Set the system clock to something sensible, -# to get coherent logs until the initial NTP message +# to get coherent logs until the initial NTP exchange -if { s6-clock @40000000596c000000000000 } +if { s6-clock @400000005a58000000000000 } # Initialize the service manager diff --git a/examples/rc.shutdown b/examples/rc.shutdown index 04d7357..14b4692 100755 --- a/examples/rc.shutdown +++ b/examples/rc.shutdown @@ -1,20 +1,16 @@ -#!/bin/execlineb -S0 +#!/bin/execlineb -P -foreground { s6-echo "Giving dying processes some grace time." } -foreground { s6-sleep 2 } -foreground { s6-echo "Syncing disks." } -foreground { s6-sync } -foreground { s6-echo "Sending all processes the TERM signal." } -foreground { s6-nuke -th } -foreground { s6-sleep 2 } -foreground { s6-echo "Sending all processes the KILL signal." } -foreground { s6-nuke -k } -wait { } -foreground { s6-echo "Syncing and unmounting disks." } -foreground { s6-sync } -foreground { s6-umount -a } -foreground { s6-mount -ro remount /dev/root / } +# Write a message to /var/log/syslogd -foreground { s6-echo "\nPerforming "${1}"." } -s6-${1} -f +foreground +{ + s6-ipcclient -l0 /dev/log + fdmove 1 7 + s6-echo "/etc/rc.shutdown: shutdown requested" +} + + +# Shut down all services + +s6-rc -da change diff --git a/examples/rc.tini b/examples/rc.tini deleted file mode 100755 index 02e7ec7..0000000 --- a/examples/rc.tini +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/execlineb -P - - -# Write a message to /var/log/syslogd - -foreground -{ - s6-ipcclient -l0 /dev/log - fdmove 1 7 - s6-echo "/etc/rc.tini: shutdown requested" -} - - -# Shut down all services - -s6-rc -da change diff --git a/package/info b/package/info index bf53f22..f7c3758 100644 --- a/package/info +++ b/package/info @@ -1,4 +1,4 @@ package=s6-linux-init -version=0.3.1.1 +version=0.4.0.0 category=admin package_macro_name=S6_LINUX_INIT diff --git a/src/init/s6-linux-init-maker.c b/src/init/s6-linux-init-maker.c index 71d82cb..30866fe 100644 --- a/src/init/s6-linux-init-maker.c +++ b/src/init/s6-linux-init-maker.c @@ -16,7 +16,7 @@ #include #include -#define USAGE "s6-linux-init-maker [ -c basedir ] [ -l tmpfsdir ] [ -b execline_bindir ] [ -u log_uid -g log_gid | -U ] [ -G early_getty_cmd ] [ -2 stage2_script ] [ -r ] [ -Z finish_script ] [ -3 stage3_script ] [ -p initial_path ] [ -m initial_umask ] [ -t timestamp_style ] [ -d dev_style ] [ -s env_store ] [ -e initial_envvar ... ] [ -n ] dir" +#define USAGE "s6-linux-init-maker [ -c basedir ] [ -l tmpfsdir ] [ -b execline_bindir ] [ -u log_uid -g log_gid | -U ] [ -G early_getty_cmd ] [ -2 stage2_script ] [ -r ] [ -Z shutdownscript ] [ -p initial_path ] [ -m initial_umask ] [ -t timestamp_style ] [ -d dev_style ] [ -s env_store ] [ -e initial_envvar ... ] [ -n ] [ -q final_sleep_time ] dir" #define dieusage() strerr_dieusage(100, USAGE) #define dienomem() strerr_diefu1sys(111, "stralloc_catb") ; @@ -34,8 +34,7 @@ static char const *slashrun = "/run" ; static char const *robase = "/etc/s6-linux-init" ; static char const *init_script = "/etc/rc.init" ; -static char const *tini_script = "/etc/rc.tini" ; -static char const *shutdown_script = "/etc/rc.shutdown" ; +static char const *tini_script = "/etc/rc.shutdown" ; static char const *bindir = "/bin" ; static char const *initial_path = "/usr/bin:/usr/sbin:/bin:/sbin" ; static char const *env_store = 0 ; @@ -45,6 +44,7 @@ static gid_t uncaught_logs_gid = 0 ; static unsigned int initial_umask = 022 ; static unsigned int timestamp_style = 1 ; static unsigned int slashdev_style = 2 ; +static unsigned int finalsleep = 2000 ; static int redirect_stage2 = 0 ; static int in_namespace = 0 ; @@ -101,6 +101,8 @@ static int s6_svscan_log_script (buffer *b) static int finish_script (buffer *b) { size_t sabase = satmp.len ; + char fmt[UINT_FMT] ; + fmt[uint_fmt(fmt, finalsleep)] = 0 ; if (buffer_puts(b, "#!") < 0 || buffer_puts(b, bindir) < 0 || buffer_puts(b, "/execlineb -S0\n\n") < 0 @@ -120,11 +122,21 @@ static int finish_script (buffer *b) if (buffer_puts(b, "cd /\nredirfd -w 2 /dev/console\nfdmove -c 1 2\nforeground { s6-svc -X -- ") < 0 || buffer_put(b, satmp.s + sabase, satmp.len - sabase) < 0) goto err ; satmp.len = sabase ; - if (buffer_puts(b, "/service/s6-svscan-log }\nunexport ?\nwait -r -- { }\n") < 0 - || !string_quote(&satmp, shutdown_script, strlen(shutdown_script))) return 0 ; - if (buffer_put(b, satmp.s + sabase, satmp.len - sabase) < 0) goto err ; - satmp.len = sabase ; - if (buffer_puts(b, " ${@}\n") < 0) return 0 ; + if (buffer_puts(b, "/service/s6-svscan-log }\n" + "unexport ?\nwait -r -- { }\n" + "foreground { s6-echo \"Syncing disks.\" }\n" + "foreground { s6-sync }\n" + "foreground { s6-echo \"Sending all processes the TERM signal.\" }\n" + "foreground { s6-nuke -th }\n" + "s6-sleep -m -- ") < 0 + || buffer_puts(b, fmt) < 0 + || buffer_puts(b, "\nforeground { s6-echo \"Sending all processes the KILL signal.\" }\n" + "foreground { s6-nuke -k }\n" + "wait { }\n" + "foreground { s6-echo \"Unmounting disks.\" }\n" + "foreground { s6-umount -a }\n" + "foreground { s6-mount -ro remount /dev/root / }\n" + "s6-${1} -f\n") < 0) return 0 ; return 1 ; err: satmp.len = sabase ; @@ -394,7 +406,7 @@ int main (int argc, char const *const *argv, char const *const *envp) subgetopt_t l = SUBGETOPT_ZERO ; for (;;) { - int opt = subgetopt_r(argc, argv, "c:l:b:u:g:UG:2:rZ:3:p:m:t:d:s:e:n", &l) ; + int opt = subgetopt_r(argc, argv, "c:l:b:u:g:UG:2:rZ:p:m:t:d:s:e:nq:", &l) ; if (opt == -1) break ; switch (opt) { @@ -416,7 +428,6 @@ int main (int argc, char const *const *argv, char const *const *envp) case '2' : init_script = l.arg ; break ; case 'r' : redirect_stage2 = 1 ; break ; case 'Z' : tini_script = l.arg ; break ; - case '3' : shutdown_script = l.arg ; break ; case 'p' : initial_path = l.arg ; break ; case 'm' : if (!uint0_oscan(l.arg, &initial_umask)) dieusage() ; break ; case 't' : if (!uint0_scan(l.arg, ×tamp_style)) dieusage() ; break ; @@ -424,6 +435,7 @@ int main (int argc, char const *const *argv, char const *const *envp) case 's' : env_store = l.arg ; break ; case 'e' : if (!stralloc_catb(&satmp, l.arg, strlen(l.arg) + 1)) dienomem() ; break ; case 'n' : in_namespace = 1 ; break ; + case 'q' : if (!uint0_scan(l.arg, &finalsleep)) dieusage() ; break ; default : dieusage() ; } } @@ -440,9 +452,7 @@ int main (int argc, char const *const *argv, char const *const *envp) if (init_script[0] != '/') strerr_dief3x(100, "stage 2 script location ", init_script, " is not absolute") ; if (tini_script[0] != '/') - strerr_dief3x(100, "stage 2 finish script location ", tini_script, " is not absolute") ; - if (shutdown_script[0] != '/') - strerr_dief3x(100, "stage 3 script location ", shutdown_script, " is not absolute") ; + strerr_dief3x(100, "shutdown script location ", tini_script, " is not absolute") ; if (timestamp_style > 3) strerr_dief1x(100, "-t timestamp_style must be 0, 1, 2 or 3") ; if (slashdev_style > 2) -- cgit v1.2.3