2023-12-13 00:16:26 +08:00
|
|
|
# Using supervise-daemon
|
2016-02-02 02:42:58 +08:00
|
|
|
|
|
|
|
Beginning with OpenRC-0.21 we have our own daemon supervisor,
|
2023-12-13 00:16:26 +08:00
|
|
|
`supervise-daemon`, which can start a daemon and restart it if it
|
2016-02-02 02:42:58 +08:00
|
|
|
terminates unexpectedly.
|
|
|
|
|
2016-05-25 01:55:50 +08:00
|
|
|
The following is a brief guide on using this capability.
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
* **Use Default start, stop and status functions**.
|
2018-10-23 06:49:25 +08:00
|
|
|
If you write your own start, stop and status functions in your service
|
|
|
|
script, none of this will work. You must allow OpenRC to use the default
|
|
|
|
functions.
|
2016-02-02 02:42:58 +08:00
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
* **Daemons must not fork**.
|
|
|
|
Any daemon that you would like to have monitored by `supervise-daemon`
|
2018-10-23 06:49:25 +08:00
|
|
|
must not fork. Instead, it must stay in the foreground. If the daemon
|
|
|
|
forks, the supervisor will be unable to monitor it.
|
2016-02-02 02:42:58 +08:00
|
|
|
|
2018-10-23 06:49:25 +08:00
|
|
|
If the daemon can be configured to not fork, this should be done in the
|
|
|
|
daemon's configuration file, or by adding a command line option that
|
2023-12-13 00:16:26 +08:00
|
|
|
instructs it not to fork to the `command_args_foreground` variable shown
|
2018-10-23 06:49:25 +08:00
|
|
|
below.
|
2016-02-02 02:42:58 +08:00
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
## Health checks
|
2018-10-10 06:49:02 +08:00
|
|
|
|
|
|
|
Health checks are a way to make sure a service monitored by
|
2023-12-13 00:16:26 +08:00
|
|
|
`supervise-daemon` stays healthy. To configure a health check for a
|
|
|
|
service, you need to write a `healthcheck()` function, and optionally an
|
|
|
|
`unhealthy()` function in the service script. Also, you will need to set
|
|
|
|
the `healthcheck_timer` and optionally `healthcheck_delay` variables.
|
2018-10-10 06:49:02 +08:00
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
### healthcheck() function
|
2018-10-10 06:49:02 +08:00
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
The `healthcheck()` function is run repeatedly based on the settings of
|
|
|
|
the `healthcheck_*` variables. This function should return zero if the
|
2018-10-10 06:49:02 +08:00
|
|
|
service is currently healthy or non-zero otherwise.
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
### unhealthy() function
|
2018-10-10 06:49:02 +08:00
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
If the `healthcheck()` function returns non-zero, the `unhealthy()` function
|
2018-10-10 06:49:02 +08:00
|
|
|
is run, then the service is restarted. Since the service will be
|
|
|
|
restarted by the supervisor, the unhealthy function should not try to
|
|
|
|
restart it; the purpose of the function is to allow any cleanup tasks
|
|
|
|
other than restarting the service to be run.
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
## Variable settings
|
2016-02-02 02:42:58 +08:00
|
|
|
|
|
|
|
The most important setting is the supervisor variable. At the top of
|
|
|
|
your service script, you should set this variable as follows:
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
```sh
|
2016-02-02 02:42:58 +08:00
|
|
|
supervisor=supervise-daemon
|
2018-10-23 06:49:25 +08:00
|
|
|
```
|
2016-02-02 02:42:58 +08:00
|
|
|
|
|
|
|
Several other variables affect the way services behave under
|
|
|
|
supervise-daemon. They are documented on the openrc-run man page, but I
|
|
|
|
will list them here for convenience:
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
```sh
|
2018-10-23 06:49:25 +08:00
|
|
|
command_args_foreground="arguments"
|
|
|
|
```
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
This should be used if the daemon you want to monitor
|
2016-02-02 02:42:58 +08:00
|
|
|
forks and goes to the background by default. This should be set to the
|
|
|
|
command line option that instructs the daemon to stay in the foreground.
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
```sh
|
2018-10-10 06:49:02 +08:00
|
|
|
healthcheck_delay=seconds
|
|
|
|
```
|
|
|
|
|
|
|
|
This is the delay, in seconds, before the first health check is run.
|
2023-12-13 00:16:26 +08:00
|
|
|
If it is not set, we use the value of `healthcheck_timer`.
|
2018-10-10 06:49:02 +08:00
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
```sh
|
2018-10-10 06:49:02 +08:00
|
|
|
healthcheck_timer=seconds
|
|
|
|
```
|
|
|
|
|
|
|
|
This is the number of seconds between health checks. If it is not set,
|
|
|
|
no health checks will be run.
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
```sh
|
2018-10-23 06:49:25 +08:00
|
|
|
respawn_delay
|
|
|
|
```
|
|
|
|
|
|
|
|
This is the number of seconds to delay before attempting to respawn a
|
|
|
|
supervised process after it dies unexpectedly.
|
|
|
|
The default is to respawn immediately.
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
```sh
|
2018-10-23 06:49:25 +08:00
|
|
|
respawn_max=x
|
|
|
|
```
|
|
|
|
|
|
|
|
This is the maximum number of times to respawn a supervised process
|
2019-06-10 11:51:06 +08:00
|
|
|
during the given respawn period.
|
|
|
|
The default is 10. 0 means unlimited.
|
2018-10-23 06:49:25 +08:00
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
```sh
|
2018-10-23 06:49:25 +08:00
|
|
|
respawn_period=seconds
|
|
|
|
```
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
This works in conjunction with `respawn_max` and `respawn_delay` above to
|
2018-10-23 06:49:25 +08:00
|
|
|
decide if a process should not be respawned for some reason.
|
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
For example, if respawn period is 10 and `respawn_max` is 2, the process
|
2019-06-10 11:51:06 +08:00
|
|
|
would need to die 3 times within 10 seconds to no longer be respawned.
|
2023-12-13 00:16:26 +08:00
|
|
|
Note that `respawn_delay` will delay all of this, so in the above scenario
|
|
|
|
a `respawn_delay` of greater than 5 will cause infinite respawns.
|
2019-06-10 11:51:06 +08:00
|
|
|
|
2023-12-13 00:16:26 +08:00
|
|
|
By default, this is unset and `respawn_max` applies to the entire lifetime
|
2019-06-10 11:51:06 +08:00
|
|
|
of the service.
|