From ab82e6f69652d3a561783820c0509d890a5c75ed Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Thu, 10 Jul 2025 13:29:38 +0200 Subject: [PATCH] doc: update service modifiers with all new options Signed-off-by: Joachim Wiberg --- doc/config/service-opts.md | 71 +++++++++++++++++++++++++------------- doc/config/services.md | 9 ++--- 2 files changed, 52 insertions(+), 28 deletions(-) diff --git a/doc/config/service-opts.md b/doc/config/service-opts.md index 33e313a1..103ed1cf 100644 --- a/doc/config/service-opts.md +++ b/doc/config/service-opts.md @@ -1,23 +1,29 @@ -If a service should not be automatically started, it can be configured -as manual with the optional `manual` argument. The service can then be -started at any time by running `initctl start `. +Service Options +=============== - manual:yes +The run/task/tty/service/sysv directives take modifiers, or options, to +control their behavior. This section lists them with their limitations. +All modifiers must be placed between the directive and its command. The name of a service, shown by the `initctl` tool, defaults to the -basename of the service executable. It can be changed with the -optional `name` argument: +basename of the service executable. It can be changed with the `name:` +option: name: -If multiple instances of a service, with the same `name`, exist. Set -the identifier `:ID` to prevent Finit from replacing previous instances: +For multiple instances of a service, with the same `name`, set the +identifier `:ID` to prevent Finit from replacing previous instances: - service :eth1 ssdpd eth1 -- Windows discovery on eth1 - service :eth2 ssdpd eth2 -- Windows discovery on eth2 + service name:ssdp :eth1 ssdpd eth1 -- Windows discovery on eth1 + service name:ssdp :eth2 ssdpd eth2 -- Windows discovery on eth2 -If you have conflicting services and want to prevent them from starting, -use the `conflict:` argument: +The [`initctl`](../initctl.md) tool will list these two services as: + + - ssdp:eth1 + - ssdp:eth2 + +Conflicting services that must be prevented from starting, use the +`conflict:` option: service [S12345789] udevd -- Device event management daemon run [S] conflict:udevd mdev -s -- Populating device tree @@ -28,8 +34,25 @@ Multiple conflicting services can be separated using `,`: service :2 abc service conflict:abc:1,abc:2 cde -As mentioned previously, services are automatically restarted, this is -configurable with the following options: +If a service should not be automatically started, it can be configured +as manual with the optional `manual` argument. The service can then be +started at any time by running `initctl start `. + + manual:yes + +Other run/task/service options are: + + * `cgroups:...` -- see the [Cgroups](cgroups.md) section + * `env:[-]/path/to/env` -- see the [Service Environment](service-env.md) section + * `log:...` -- see [Redirecting Output](logging.md#redirecting-output) + * `nowarn` -- see [Conditional Loading](services.md#conditional-loading) + * `notify:...` -- see [Service Synchronization](service-sync.md) + * `if:...` -- see [Conditional Execution](services.md#conditional-execution) + * `type:forking` -- see description of the [service](services.md) directive + +As mentioned previously, services are automatically started, restarted, +and stopped, depending on the configuration and conditions. Within the +confines of that the following options are available: * `restart:NUM` -- number of times Finit tries to restart a crashing service, default: 10, max: 255. When this limit is reached the @@ -49,14 +72,14 @@ configurable with the following options: has *crashed*, if this option is set the system is rebooted * `oncrash:script` -- similarly, but instead of rebooting, call the `post:script` action with exit code `crashed`, see below - * `reload:script [args]` -- some services do not support `SIGHUP` but + * `reload:'script [args]'` -- some services do not support `SIGHUP` but may have other ways to update the configuration of a running daemon. When `reload:script` is defined it is preferred over `SIGHUP`. Like systemd, Finit sets `$MAINPID` as a convenience to scripts, which in effect also allow `reload:'kill -HUP $MAINPID'` - * `stop:script [args]` -- some services may require alternate methods - to be stopped. When `stop:script` is defined it is preferred over - `SIGTERM` and `stop` for `service` and `sysv` stanzas, respectively. + * `stop:'script [args]'` -- some services may require alternate methods + to be stopped. If a `stop:script` is defined it is preferred over + `SIGTERM` and `stop`, for `service` and `sysv`, respectively. Similar to `reload:script`, Finit sets `$MAINPID` > [!CAUTION] @@ -66,12 +89,12 @@ configurable with the following options: When stopping a service (run/task/sysv/service), either manually or when moving to another runlevel, Finit starts by sending `SIGTERM`, to allow -the process to shut down gracefully. However, if the process has not -been collected within 3 seconds, Finit will send `SIGKILL`. To stop the -process using a different signal than `SIGTERM`, use `halt:SIGNAL`, -e.g., `halt:SIGPWR`. To change the delay between the stop signal and -KILL, use the option `kill:<1-60>`, e.g., `kill:10` to wait 10 seconds -before sending `SIGKILL`. +the process to shut down gracefully (unless a `stop:'script'` is used). +However, if the process has not been collected within 3 seconds, Finit +will send `SIGKILL`. To stop the process using a different signal than +`SIGTERM`, use `halt:SIGNAL`, e.g., `halt:SIGPWR`. To change the delay +between the stop signal and KILL, use the option `kill:<1-60>`, e.g., +`kill:10` to wait 10 seconds before sending `SIGKILL`. Services, including the `sysv` variant, support pre/post/ready and cleanup scripts: diff --git a/doc/config/services.md b/doc/config/services.md index 9ce46ed5..20f2d704 100644 --- a/doc/config/services.md +++ b/doc/config/services.md @@ -10,7 +10,7 @@ they have to be manually restarted with `initctl restart NAME`. The limits controlling this are configurable, see the options below. > [!TIP] -> To allow endless restarts, see below option `respawn` +> To allow endless restarts, see the [`respawn` option](service-opts.md) For daemons that support it, we recommend appending `--foreground`, `--no-background`, `-n`, `-F`, or similar command line argument to @@ -151,7 +151,7 @@ which also provides a service named `udevd`. run nowarn if:udevd :1 udevadm settle -t 0 This line is only loaded if we know of a service named `udevd`. Again, -we do not warn if `udevadm` is not found, Execution will also stop here +we do not warn if `udevadm` is not found, execution will also stop here until the PID condition is asserted, i.e., Finit detecting udevd has started. @@ -165,9 +165,10 @@ can also be written as: run nowarn if:!udevd [S] mdev -s -- Populating device tree -The reason for using `confict` in this example is that a conflict can be +The reason for using `conflict` in this example is that a conflict can be resolved. Stanzas marked with `conflict:foo` are rechecked at runtime. + Conditional Execution --------------------- @@ -188,7 +189,7 @@ in true sequence. If loading the file `startup-config` fails confd sets the condition `usr/fail-startup`, thus allowing the next run statement to load `failure-config`. -Notice critical the difference between `` condition and +Notice the critical difference between the `` condition and `if:`. The former is a condition for starting and the latter is a condition to check if a run/task/service is qualified to even be considered.