1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
Using s6 with OpenRC
====================
Beginning with OpenRC-0.16, we support using the s6 supervision suite
from skarnet.org in place of start-stop-daemon for monitoring daemons [1].
## Setup
Documenting s6 in detail is beyond the scope of this guide. It will
document how to set up OpenRC services to communicate with s6.
### Use Default start, stop and status functions
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.
### Dependencies
All OpenRC service scripts that want their daemons monitored by s6
may have the following line added to their dependencies to make sure
the s6 scan directory is being monitored.
need s6-svscan
Starting with 0.63, it is not necessary to manually add this dependency.
OpenRC should deduce it automatically if your service file includes the
supervisor=s6 line. (See right below.)
### Variable Settings
The most important setting is the supervisor variable. At the top of
your service script, you should set this variable as follows:
supervisor=s6
Several other variables affect s6 services. Some of them are generic,
whether you're using start-stop-daemon, supervise-daemon or s6:
command, command_args, command_args_foreground: these variables will be
run as a shell command line. Do not start with "exec", the s6 backend
will add it automatically.
Some variables are used with supervisor=s6 the same way as with
supervisor=supervise-daemon:
output_logger, error_logger (mutually exclusive, you can only have
one logger; error_logger will log _both_ stdout and stderr, unless
you also define an output_log which will log your stdout separately
to a file.)
input_file, output_log, error_log (a corresponding _logger program
overrides a _log file)
directory, chroot, umask, command_user (command_user must be a username
appearing in your user database, not a numerical uid)
notify (only the fd:X method is supported: when ready, your daemon must
write a (possibly empty) line to file descriptor X)
stopsig (accepts signal names and numbers)
Some variables are specific to the supervisor=s6 backend:
error_logger=auto, s6_log_arguments: if you set your error_logger
(or your output_logger, but error_logger is recommended) to "auto",
then a logger service is automatically built using the s6-log
program, logging to the /var/log/$RC_SVCNAME directory with TAI64N
timestamps, automatic rotations every 1 MiB of data, and a maximum
of 10 archived files. You can fine-tune the settings given to s6-log
via the s6_log_arguments variable (but not the logging directory;
for more control you can still set error_logger manually, even to
an s6-log command line!)
timeout_ready=N: wait for up to N milliseconds for the service to
become up, and fail otherwise. If notify=fd:X has been set, it waits
for the service to be _ready_ instead, which is what you really want.
If N=0, OpenRC will wait indefinitely until the service is up/ready.
If this variable is not set, it will not wait at all and report
success as soon as the command to bring the service up has
successfully been sent.
timeout_down=N: wait for up to N milliseconds when stopping the service,
until s6 reports it as down. If it fails, the service might still be
successfully brought down. If N=0, OpenRC will wait indefinitely for
the service to die (this works well in conjunction with timeout_kill,
see below); if the variable is unset, it will not wait at all.
timeout_kill=N: when openrc tries to stop the service, s6 sends a SIGTERM
(or the value of stopsig). If that signal has not managed to bring the
service down after N milliseconds, a SIGKILL will be sent. This is
useful when you want to make sure your service is down; use in
conjunction with timeout_down. N=0 makes no sense here. Not setting
timeout_kill means no SIGKILL will be sent.
## How it works internally, starting with 0.63
The first time start() is called, OpenRC uses all the variables in the
service file to build a service directory for s6: a run script, possibly
a notification-fd file, etc. This service directory is then linked into
the scan directory and s6-svscan is told to register it and spawn a
s6-supervise process on it.
This means that all the information needed for your service should be
given, declaratively, in your service file (and your configuration file
if you have one). You do not need to build your service directory
yourself anymore, this is done automatically: in true OpenRC fashion,
the service file is the One True Source of information for running
your service.
The run script for the s6 service directory is built with in the
execline language, because execline makes script generation easier
than sh. However, the daemon execution itself is still done via
sh -c "$command $command_args $command_args_foreground"
for compatibility with other backends. In other words: you can forget
that execline is even there, all the user-facing parts use sh as their
interpreter and it's all you need to worry about.
When the service is stopped, the service directory is unlinked from the
scan directory, but the service directory itself remains. If the service
is started again, the same service directory is linked again: it does
not need to be rebuilt, unless the service file (typically in /etc/init.d)
or the configuration file (typically in /etc/conf.d) have changed since,
in which case it is created anew.
On shutdown, the existing service directories (minus their runtime data)
are stored into the OpenRC cache, and restored at the next boot.
### Logging
If you don't set a logger at all, the stdout and stderr of your service
will fall through to the catch-all logger of the s6-svscan service, which
logs all s6 services that don't have a dedicated logger. These logs are
accessible in /run/openrc/s6-logs (or whatever $RC_SVCDIR/s6-logs is on
your machine).
## Future direction
The s6 backend in OpenRC aims to be as close as possible to the
supervise-daemon backend, and most services should be able to use one
or the other interchangeably. More service file variables may be supported
in the future as supervise-daemon evolves; they will be documented in this
file. There is a also possibility that the preferred interface for defining
a service command line changes in a future version of OpenRC; in that case,
the change will apply to both supervise-daemon and s6 equally.
[1] https://skarnet.org/software/s6/
|
