diff --git a/doc/66-svctl.md b/doc/66-svctl.md deleted file mode 100644 index d5ebd021c4b455d748770fac94820810fc05b173..0000000000000000000000000000000000000000 --- a/doc/66-svctl.md +++ /dev/null @@ -1,78 +0,0 @@ -title: The 66 Suite: 66-svctl -author: Eric Vidal <eric@obarun.org> - -[66](index.html) - -[Software](https://web.obarun.org/software) - -[obarun.org](https://web.obarun.org) - -# 66-svctl - -Controls an already supervised *service* at live defined in a *tree*. - -## Interface - -``` - 66-svctl [ -h ] [ -z ] [ -v verbosity ] [ -l live ] [ -t tree ] [ -T timeout ] [ -n death ] [ -u | d | r | K | X ] service(s) -``` - -This tool expects to find an already supervised *service* at *live* defined in the given *tree* and an already running [scandir](66-scandir.html). - -***(!)*** This tool only deals with `classic` services—see [66‑dbctl](66-dbctl.html) for other types of services. - -Multiple *services* can be handled by separating their names with a space. *66‑svctl* gathers each of these services in a list called *selection*. The command is sent to the *selection* asynchronously. - -## Exit codes - -- *0* success -- *100* wrong usage -- *111* system call failed - -## Options - -- **-h** : prints this help. - -- **-z** : use color. - -- **-v** *verbosity* : increases/decreases the verbosity of the command. - * *1* : only print error messages. This is the default. - * *2* : also print warning messages. - * *3* : also print tracing messages. - * *4* : also print debugging messages. - -- **-l** *live* : changes the supervision directory of *service* to *live*. By default this will be `%%livedir%%`. The default can also be changed at compile time by passing the `--livedir=live` option to `./configure`. An existing absolute path is expected and should be within a writable and executable filesystem - likely a RAM filesystem—see [66-scandir](66-scandir.html). - -- **-t** : handles the *selection* of the given *tree*. This option is mandatory except if a tree was marked as 'current'—see [66-tree](66-tree.html). - -- **-T** *timeout* : specify a timeout in milliseconds after which *66-svctl* will stop trying to reach the desired state of the *service*; defaults to `3000`. timeout is applied to each *service* of the *selection*. Separate timeouts for different services can be set in their respective [frontend](frontend.html) files using the `@timeout‑up` or `@timeout‑down` key. The [frontend](frontend.html) key is prioritized over this option. - -- **-n** *death* : specifiy the maximum number of *service* death events that the supervisor will keep track of. If the *service* dies more than this number of times *66‑svctl* will stop trying to reach the desired state of the *service*. The [frontend](frontend.html) key `@maxdeath` is prioritized over this option—see [frontend](frontend.html). If this option is not specified and no max-death-tally file exists then the maximum allowed deaths will be `5` by default. - -- **-u** : send an up signal to *service*. It searches for a notification-fd file—see [service startup notifications](https://skarnet.org/software/s6/notifywhenup.html) and [frontend](frontend.html). If this file exists *66‑svctl* will automatically change to uppercase `U`. - -- **-d** : send a down signal to *service*. It searches for a notification‑fd file—see [service startup notifications](https://skarnet.org/software/s6/notifywhenup.html) and [frontend](frontend.html). If this file exists *66‑svctl* will automatically change to uppercase `D`. - -- **-r** : send a reload signal to *service*. By default the signal is a `SIGTERM`; this can be configured with the `@down-signal` field in the [frontend](frontend.html) service file. It searches for a notification-fd file—see [service startup notifications](https://skarnet.org/software/s6/notifywhenup.html) and [frontend](frontend.html). If this file exists *66‑svctl* will automatically change to uppercase `R`. - -- **-X** : exit; the supervisor of the *service* will exit too. This command should normally never be used on a working system. - -- **-K** : send a SIGKILL to *service* and keep it down. - -## s6-svc corresponding signal - -The *66‑svctl* signals correspond to [s6‑svc](https://skarnet.org/software/s6/s6-svc.html) in the following manner: - -- *-u* = -u -- *-U* = -uwU -- *-d* = -d -- *-D* = -uwD -- *-r* = -r -- *-X* = -xd -- *-K* = -kd - -## Notes - -You can also send a signal in a similar fashion to a `classic` or `longrun` service with the [s6‑svc](https://skarnet.org/software/s6/s6-svc.html) tool which has the philosophy "launch and forget" which unlike *66‑svctl* does not care for the exit status of the service when a signal is sent. - -As an extra convenience the **-n** option allows to deal directly with *max-death-tally* from the command line even if it was not specified explicitely in the services [frontend](frontend.html) file and no corresponding file exists. diff --git a/doc/signal.md b/doc/signal.md new file mode 100644 index 0000000000000000000000000000000000000000..d919974a6b5c05e93b93baf10a3035e9852866a9 --- /dev/null +++ b/doc/signal.md @@ -0,0 +1,82 @@ +title: The 66 Suite: signal +author: Eric Vidal <eric@obarun.org> + +[66](index.html) + +[Software](https://web.obarun.org/software) + +[obarun.org](https://web.obarun.org) + +# signal + +Controls an already supervised *service*. + +## Interface + +``` +signal [ -h ] [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -abqHkti12pcysodDuUxOrP ] service... +``` + +This command expects to find an already supervised *service* and an already running [scandir](scandir.html). + +This command is the heart of `66` concerning service state change. Every other `66` command that need to send a signal to a service pass through this command. + +Multiple *services* can be handled by separating their names with a space. + +## Options + +- **-h**: print this help. +- **-P**: Do not handle service dependencies. In such cases, the *signal* command will not attempt to send signal to the services that are dependent on the service, regardless of their current state. +- **-wu**: do not exit until the service is up. +- **-wU**: do not exit until the service is up and ready and has notified readiness. +- **-wd**: do not exit until the service is down. +- **-wD**: do not exit until the service is down and ready to be brought up and has notified readiness. +- **-wr**: do not exit until the service has been started or restarted. +- **-wR**: do not exit until the service has been started or restarted and has notified readiness. +- **-a**: send a SIGALRM signal. +- **-b**: send a SIGABRT signal. +- **-q**: send a SIGQUIT signal. +- **-H**: send a SIGHUP signal. +- **-k**: send a SIGKILL signal. +- **-t**: send a SIGTERM signal. +- **-i**: send a SIGINT signal. +- **-1**: send a SIGUSR1 signal. +- **-2**: send a SIGUSR2 signal. +- **-p**: send a SIGSTOP signal. +- **-c**: send a SIGCONT signal. +- **-y**: send a SIGWINCH signal. +- **-o**: once. Equivalent to '-uO'. +- **-d**: send a SIGTERM signal then a SIGCONT signal. +- **-D**: bring down service and avoid to be bring it up automatically. +- **-u**: bring up service. +- **-U**: bring up service and ensure that service can be restarted automatically. +- **-x**: bring down the service and propagate to its supervisor. +- **-O**: mark the service to run once at most. +- **-r**: restart service by sending it a signal(default SIGTERM). + +## Usage examples + +Send a SIGHUP signal to `foo` +``` +66 signal -H foo +``` + +Send a SIGHUP signal to `foo` by signal name +``` +66 signal -s SIGHUP foo +``` + +Triggers a log rotation of `foo-log` +``` +66 signal -a -P foo-log +``` + +Take down `foo` and block until the process is down and the finish script has completed +``` +66 signal -wD -d foo +``` + +Bring up `foo` and block until it has sent notification that it is ready. Exit if it is still not ready after 5 seconds. +``` +66 -T 5000 -wU -u foo +``` \ No newline at end of file diff --git a/src/lib66/exec/ssexec_help.c b/src/lib66/exec/ssexec_help.c index de38f660704860466bc1312a8f6a0879a4c22dc7..09cb701a5e3b0454e1813219ee25a472b7faa590 100644 --- a/src/lib66/exec/ssexec_help.c +++ b/src/lib66/exec/ssexec_help.c @@ -249,13 +249,14 @@ char const *help_remove = " -P: do not propagate signal to its dependencies at stop process\n" ; -char const *usage_signal = "66 signal [ -h ] [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -abqHkti12pcysodDuUxOr ] service..." ; +char const *usage_signal = "66 signal [ -h ] [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -abqHkti12pcysodDuUxOrP ] service..." ; char const *help_signal = "\nsend a signal to services\n" "\n" "options:\n" " -h: print this help\n" +" -P: do not propagate signal to its dependencies\n" " -a: send a SIGALRM signal\n" " -b: send a SIGABRT signal\n" " -q: send a SIGQUIT signal\n"