From 5a318ce649a7a5f754892518a4452a519b41dac8 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 4 Dec 2020 07:25:12 +0000 Subject: Big signal/command semantics change to svscan/supervise; add s6-svperms. --- doc/index.html | 1 + doc/overview.html | 24 ++++++++ doc/s6-supervise.html | 28 ++++------ doc/s6-svperms.html | 135 +++++++++++++++++++++++++++++++++++++++++++++ doc/s6-svscan.html | 149 +++++++++++++++++++++++--------------------------- doc/s6-svscanctl.html | 75 +++++++++---------------- doc/servicedir.html | 9 --- doc/upgrade.html | 16 +++++- 8 files changed, 280 insertions(+), 157 deletions(-) create mode 100644 doc/s6-svperms.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 9a01f14..ceb854e 100644 --- a/doc/index.html +++ b/doc/index.html @@ -161,6 +161,7 @@ a user interface to control those processes and monitor service states.
  • The s6-svc program
  • The s6-svok program
  • The s6-svstat program
    • +
  • The s6-svperms program
  • The s6-svwait program
  • The s6-svlisten1 program
  • The s6-svlisten program
    • diff --git a/doc/overview.html b/doc/overview.html index 1b4cb5d..9e41824 100644 --- a/doc/overview.html +++ b/doc/overview.html @@ -379,6 +379,30 @@ implemented for instance in the s6-rc package.

    +

    Fine-grained control over services

    + +

    + s6 provides you with a few more tools to control and monitor your +services. services. For instance: +

    + + + +

    + These tools make s6 the most powerful and flexible of the existing +process supervision suites. +

    +

    Additional utilities

    diff --git a/doc/s6-supervise.html b/doc/s6-supervise.html index 2926f83..94504e3 100644 --- a/doc/s6-supervise.html +++ b/doc/s6-supervise.html @@ -108,11 +108,15 @@ daemon as fdmove -c 2 1 fdmove 1 3 prog... (in execline), or

    @@ -183,17 +187,9 @@ better to have a collection of service directories single scan directory, and just run s6-svscan on that scan directory. s6-svscan will spawn the necessary s6-supervise processes, and will also take care of logged services. -
  • s6-supervise is not supposed to have a controlling terminal: it's generally -launched by a s6-svscan process that itself does not -have a controlling terminal. If you run s6-supervise from an interactive shell, be -warned that typing ^C in the controlling terminal (which sends a SIGINT to -all processes in the foreground process group in the terminal) will terminate -s6-supervise, but not the supervised processes - so, the daemon will keep running -as an orphan. This is by design: supervised processes should be as resilient as -possible, even when their supervisors die. However, if you want to launch -s6-supervise from an interactive shell and need your service to die when you ^C it, -you can obtain this behaviour by creating a ./nosetsid file in the -service directory.
    • +
  • s6-supervise always spawns its child in a new session, as a session leader. +The goal is to protect the supervision tree from misbehaved services that would +send signals to their whole process group.
  • You can use s6-svc to send commands to the s6-supervise process; mostly to change the service state and send signals to the monitored process.
    • diff --git a/doc/s6-svperms.html b/doc/s6-svperms.html new file mode 100644 index 0000000..5b5d485 --- /dev/null +++ b/doc/s6-svperms.html @@ -0,0 +1,135 @@ + + + + + + s6: the s6-svperms program + + + + + + +

    +s6
    +Software
    +skarnet.org +

    + +

    The s6-svperms program

    + +

    +s6-svperms allows the user to see, or modify, for a given +list of services: who can read their states, who can send them +control commands, and who can subscribe to up/down events for those +services. +

    + +

    Interface

    + +
    +     s6-svperms [ -v ] [ -u | -g group | -G group | -o | -O group ] [ -e | -E group ] servicedirs...
+
    + +

    + Without options, or with only the -v option, +s6-svperms prints 3 lines to stdout for every service directory +listed in servicedirs. Every line contains the name +of the service directory, then the following information: +

    + + + +

    + If something goes wrong while reading a part of the configuration of +a service directory, s6-svperms does not print the corresponding +line to stdout; instead, it prints a warning message to stderr. +

    + +

    + When invoked with other options, s6-svperms modifies the +permissions of the service directories listed in servicedirs... as +specified by the options. The same permissions will be applied to all +the services listed in servicedirs.... +

    + +

    Options

    + + + +

    + group is normally a group name that will be searched in the group +database. But if it starts with a colon (:), the rest of group +will be interpreted as a numerical gid, and the group database will not be read. +

    + +

    Exit codes

    + + + +

    Notes

    + + + + + diff --git a/doc/s6-svscan.html b/doc/s6-svscan.html index 3a93e00..5d92174 100644 --- a/doc/s6-svscan.html +++ b/doc/s6-svscan.html @@ -27,7 +27,7 @@ the root or a branch of a supervision tree.

    Interface 

    -     s6-svscan [ -S | -s ] [ -d notif ] [ -X consoleholder ] [ -c max ] [ -t rescan ] [ scandir ]
+     s6-svscan [ -d notif ] [ -X consoleholder ] [ -c max ] [ -t rescan ] [ scandir ]

    Options

    Signals

    - s6-svscan always reacts to the following signals: + s6-svscan has special handling for the following signals:

    - By default, it also reacts to the following signals: + Signals that are not in the above list are not caught by s6-svscan and will +have the system's default effect.

    - -

    - But if the -s option was given, then instead of those default actions, -s6-svscan uses configurable handlers: it forks and executes a program every time -it receives one of the following signals. + The behaviour for the first three signals in the list is always fixed:

    - If an action cannot be taken (the relevant file doesn't exist, or isn't -executable, or any kind of error happens), s6-svscan prints a warning -message to its standard error but does nothing else with the signal. -

    - -

    - The -s mechanism is useful, for instance, when s6-svscan is running as -process 1 and needs to trap signals such as SIGINT (sent on some systems by -a Ctrl-Alt-Del press) in order to perform some specific work instead of -executing into .s6-svscan/finish on the spot. + The behaviour for the rest of the list is configurable: on receipt of a +SIGFOO, +s6-svscan will try to run an executable .s6-svscan/SIGFOO file. For +instance, a .s6-svscan/SIGTERM executable script will be run on receipt of +a SIGTERM. If the file cannot be found, or cannot be executed for any reason, the +default behaviour for the signal will be applied. Default behaviours are:

    -

    - s6-svscan will not exit its loop on its own when it receives a signal such as -SIGINT and the -s option has been given. To make it exit its loop, -invoke a s6-svscanctl command from the signal -handling script. For instance, a .s6-svscan/SIGINT script could look -like this: -

    - -
      #!/command/execlineb -P
-  foreground { shutdown-the-services }
-  s6-svscanctl -i .
-
    +

    The reaper

    @@ -189,9 +189,10 @@ one second later.

    The scanner

    - Every rescan milliseconds, or upon receipt of a SIGALRM or a + Upon receipt of a SIGALRM or a s6-svscanctl -a command, s6-svscan runs a -scanner routine. +scanner routine. (It also runs it every rescan milliseconds +if the -t option has been given.)

    @@ -217,8 +218,8 @@ Every service the scanner finds is flagged as "active". started in an earlier scan, but the current scan can't find the corresponding directory, the service is then flagged as inactive. No command is sent to stop inactive s6-supervise processes (unless the administrator -uses s6-svscanctl -n), but inactive -s6-supervise processes will not be restarted if they die. +uses s6-svscanctl -n or a SIGHUP), but +inactive s6-supervise processes will not be restarted if they die.

    Notes

    @@ -238,22 +239,10 @@ process commands at any time, even when the computer is in trouble. memory. However, s6-svscan uses opendir(), and most opendir() implementations internally use heap memory - so unfortunately, it's impossible to guarantee that s6-svscan does not use heap memory at all. -
  • When run with the -t0 option, s6-svscan never polls, -it only wakes up on notifications, just like s6-supervise. The s6 supervision -tree can be used in energy-critical environments.
    • -
  • The supervision tree (i.e. the tree of processes made of s6-svscan and -all its scions) is not supposed to have a controlling terminal; s6-svscan -generally is either process 1 or a child of process 1, not something that is -launched from a terminal. If you run s6-svscan from an interactive shell, be -warned that typing ^C in the controlling terminal (which sends a SIGINT to -all processes in the foreground process group in the terminal) will terminate -the supervision tree, but not the supervised processes - so, the supervised -processes will keep running as orphans. This is by design: supervised -processes should be as resilient as possible, even when their supervisors -die. However, if you want to launch s6-svscan from an interactive shell and -need your services to die with the supervision tree when you ^C it, you can -obtain this behaviour by creating ./nosetsid files in every -service directory.
    • +
  • Unless run with a nonzero -t option, which is only a legacy +feature used to emulate other supervision suites such as daemontools or runit, +s6-svscan never polls; it only wakes up on notifications. +The s6 supervision tree can be used in energy-critical environments.
    • diff --git a/doc/s6-svscanctl.html b/doc/s6-svscanctl.html index ae0f8ee..6340c14 100644 --- a/doc/s6-svscanctl.html +++ b/doc/s6-svscanctl.html @@ -26,82 +26,57 @@ process.

    Interface 

    -     s6-svscanctl [ -phratszbnNiq0678 ] svscandir
+     s6-svscanctl [ -zabhitqnN ] scandir

    s6-svscanctl sends the given series of commands to the s6-svscan process monitoring the -svscandir directory, then exits 0. It exits 111 if it cannot send -a command, or 100 if no s6-svscan process is running on svscandir. +scandir directory, then exits 0. It exits 111 if it cannot send +a command, or 100 if no s6-svscan process is running on scandir.

    Options

    -

    Usage examples

    - -
     s6-svscanctl -an /service
    -

    - Updates the process supervision tree -to exactly match the services listed in /service. -

    - -
     s6-svscanctl -6 /service
    -

    - Orders the s6-svscan process monitoring /service to exit in -reboot mode: all the supervision tree at /service will be terminated, -and s6-svscan will execute into the /service/.s6-svscan/finish -script with the reboot argument. -

    -

    Internals

    -s6-svscanctl writes control commands into the svscandir/.s6-svscan/control -FIFO. An s6-svscan process running on svscandir will be listening to this FIFO, +s6-svscanctl writes control commands into the scandir/.s6-svscan/control +FIFO. An s6-svscan process running on scandir will be listening to this FIFO, and will read and interpret those commands.

    diff --git a/doc/servicedir.html b/doc/servicedir.html index fa7f974..d8d7c8d 100644 --- a/doc/servicedir.html +++ b/doc/servicedir.html @@ -122,15 +122,6 @@ must be writable. the default state of the service is considered down, not up: s6-supervise will not automatically start it until it receives a s6-svc -u command. If no down file exists, the default state of the service is up. -
  • An optional, empty, regular file named nosetsid. -If this file exists and starts with the word setpgrp, s6-supervise will run the service -in a new process group (the run script will be a process group leader), but not in a new session. -If this file exists and does not start with setpgrp, -s6-supervise will start the service in the same session and process group as itself. -If no nosetsid file exists, the service has its own process group and is started -as a session leader - which is the default and should normally not be changed. Using the -nosetsid file is a hack; it should only be used in testing environments for -job control convenience, and probably never outside that use case.
  • An optional regular file named notification-fd. If such a file exists, it means that the service supports readiness notification. The file must only diff --git a/doc/upgrade.html b/doc/upgrade.html index 5837345..f49cc0f 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -25,8 +25,20 @@ dependency bumped to 2.10.0.0.
  • execline dependency bumped to 2.7.0.0.
    • -
  • s6-svscan and -s6-svscanctl have changed.
    • +
  • Commands received by s6-svscan and +sent by s6-svscanctl have changed significantly. +Different semantics of SIGHUP for s6-svscan.
    • +
  • Commands received by s6-supervise and +sent by s6-svc have changed slightly +(no s6-svc -X anymore). Different semantics of SIGHUP and SIGQUIT +for s6-supervise.
    • +
  • s6-supervise now handles SIGINT +appropriately, by forwarding it to its child's process group.
    • +
  • The nosetsid file is not recognized anymore in service +directories. s6-supervise now always starts +it child as a session leader.
    • +
  • Split permissions on service control are now officially supported. +New binary: s6-svperms.

    • in 2.9.2.0

    -- cgit v1.2.3