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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>s6: the s6-svc program</title>
<meta name="Description" content="s6: the s6-svc program" />
<meta name="Keywords" content="s6 command s6-svc supervise command service" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">s6</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The s6-svc program </h1>
<p>
s6-svc sends commands to a running <a href="s6-supervise.html">s6-supervise</a>
process. In other words, it's used to control a supervised process; among
other benefits, it allows an administrator to send signals to daemons without
knowing their PIDs, and without using horrible hacks such as .pid files.
</p>
<h2> Interface </h2>
<pre>
s6-svc [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -T <em>timeout</em> ] [ -s <em>signal</em> | -abqhkti12pcyrPCK ] [ -oduDUxO ] <em>servicedir</em>
</pre>
<p>
s6-svc sends the given series of commands to the
<a href="s6-supervise.html">s6-supervise</a> process monitoring the
<em>servicedir</em> directory, then exits 0. It exits 111 if it cannot send
a command, or 100 if no s6-supervise process is running on <em>servicedir</em>.
</p>
<h2> Options </h2>
<ul>
<li> <tt>-a</tt> : send a SIGALRM to the supervised process </li>
<li> <tt>-b</tt> : send a SIGABRT to the supervised process </li>
<li> <tt>-q</tt> : send a SIGQUIT to the supervised process </li>
<li> <tt>-h</tt> : send a SIGHUP to the supervised process </li>
<li> <tt>-k</tt> : send a SIGKILL to the supervised process </li>
<li> <tt>-t</tt> : send a SIGTERM to the supervised process </li>
<li> <tt>-i</tt> : send a SIGINT to the supervised process </li>
<li> <tt>-1</tt> : send a SIGUSR1 to the supervised process </li>
<li> <tt>-2</tt> : send a SIGUSR2 to the supervised process </li>
<li> <tt>-p</tt> : send a SIGSTOP to the supervised process </li>
<li> <tt>-c</tt> : send a SIGCONT to the supervised process </li>
<li> <tt>-y</tt> : send a SIGWINCH to the supervised process </li>
<li> <tt>-s <em>signal</em></tt> : send <em>signal</em> to the
supervised process. <em>signal</em> can be given as its name (case-
insensitive) or its number, but only the signals listed above are
accepted - you cannot, for instance, manually send a SIGSEGV to the
supervised process. </li>
</ul> <br>
<ul>
<li> <tt>-o</tt> : once. Equivalent to "-uO". </li>
<li> <tt>-d</tt> : down. If the supervised process is up, send it
a SIGTERM (by default) then a SIGCONT (to make sure even stopped processes
receive the signal aimed to kill them) and do not restart it.
The SIGTERM default can be changed by editing the <tt>./down-signal</tt>
file in the <a href="servicedir.html">service directory</a>. </li>
<li> <tt>-D</tt> : down, and create a <tt>./down</tt> file so the
service does not restart automatically if the supervisor dies. This
option is mostly used by automated systems working on top of s6; as a
human user, you probably don't need it. </li>
<li> <tt>-u</tt> : up. If the supervised process is down, start it.
Automatically restart it when it dies. </li>
<li> <tt>-U</tt> : up, and remove any <tt>./down</tt> file that may
exist, in order to make sure the service is automatically restarted even
if the supervisor dies. This option is mostly used by automated systems
working on top of s6; as a human user, you probably don't need it. </li>
<li> <tt>-x</tt> : exit. When the service is asked to be down and
the supervised process dies, s6-supervise will exit too. This command should
normally never be used on a working system. Note that if this command is
sent and a <tt>./finish</tt> script exists for the service, the last
<tt>./finish</tt> invocation before
<a href="s6-supervise.html">s6-supervise</a> exits will run with its stdin
and stdout redirected to <tt>/dev/null</tt>. </li>
<li> <tt>-O</tt> : mark the service to run once at most. iow: do not
restart the supervised process when it dies. If it is down when the command
is received, do not even start it. </li>
<li> <tt>-Q</tt> : once at most, and create a <tt>./down</tt> file.
Like <tt>-D</tt>, but do not terminate the service if it is currently
running. </li>
<li> <tt>-r</tt> : If the service is up, restart it, by sending it a
signal to kill it and letting <a href="s6-supervise.html">s6-supervise</a>
start it again. By default, the signal is a SIGTERM; this can be configured
via the <tt>./down-signal</tt> file in the <a href="servicedir.html">service
directory</a>. </li>
<li> <tt>-T <em>timeout</em></tt> : if the <tt>-w<em>state</em></tt>
option has been given, <tt>-T</tt> specifies a timeout
(in milliseconds) after which s6-svc will exit 1 with an error message if
the service still hasn't reached the desired state. By default, the
timeout is 0, which means that s6-svc will block indefinitely. </li>
<li> <tt>-wd</tt> : s6-svc will not exit until the service is down,
i.e. until the <tt>run</tt> process has died. </li>
<li> <tt>-wD</tt> : s6-svc will not exit until the service is down
<em>and</em> ready to be brought up, i.e. a possible <tt>finish</tt> script has
exited. </li>
<li> <tt>-wu</tt> : s6-svc will not exit until the service is up,
i.e. there is a process running the <tt>run</tt> executable. </li>
<li> <tt>-wU</tt> : s6-svc will not exit until the service is up <em>and</em>
<a href="notifywhenup.html">ready</a> as notified by the daemon itself.
If the <a href="servicedir.html">service directory</a> does not contain
a <tt>notification-fd</tt> file to tell
<a href="s6-supervise.html">s6-supervise</a> to accept readiness
notification, s6-svc will print a warning and act as if the <tt>-wu</tt>
option had been given instead. </li>
<li> <tt>-wr</tt> : s6-svc will not exit until the service has been
started or restarted. </li>
<li> <tt>-wR</tt> : s6-svc will not exit until the service has been
started or restarted and has notified readiness. </li>
</ul> <br>
<ul>
<li> <tt>-P</tt> : send a SIGSTOP to the <em>process group</em> of the supervised process </li>
<li> <tt>-C</tt> : send a SIGCONT to the <em>process group</em> of the supervised process </li>
<li> <tt>-K</tt> : send a SIGKILL to the <em>process group</em> of the supervised process </li>
</ul>
<h2> Usage examples </h2>
<pre> s6-svc -h /service/httpd </pre>
<p>
Send a SIGHUP to the process represented by the <tt>/service/httpd</tt>
service directory. Traditionally, this makes web servers reload their
configuration file.
</p>
<pre> s6-svc -r /service/sshd </pre>
<p>
Kill (and automatically restart, if the wanted state of the service is up)
the process represented by the <tt>/service/sshd</tt> service directory -
typically the sshd server.
</p>
<pre> s6-svc -wD -d /service/ftpd </pre>
<p>
Take down the ftpd server and block until the process is down and
the finish script has completed.
</p>
<pre> s6-svc -wU -T 5000 -u /service/ftpd </pre>
<p>
Bring up the ftpd server and block until it has sent notification that it
is ready. Exit 1 if it is still not ready after 5 seconds.
</p>
<pre> s6-svc -wR -t /service/ftpd </pre>
<p>
Send a SIGTERM to the ftpd server; wait for
<a href="s6-supervise.html">s6-supervise</a> to restart it, and block
until it has notified that it is ready to serve again. See the NOTES
section below for a caveat.
</p>
<pre> s6-svc -a /service/httpd/log </pre>
<p>
Send a SIGALRM to the logger process for the httpd server. If this logger
process is <a href="s6-log.html">s6-log</a>, this triggers a log rotation.
</p>
<h2> Internals </h2>
<ul>
<li> s6-svc writes control commands into the <tt><em>servicedir</em>/supervise/control</tt>
FIFO. An s6-supervise process running on <em>servicedir</em> will be listening to this FIFO,
and will read and interpret those commands. </li>
<li> When invoked with one of the <tt>-w</tt> options, s6-svc executes into
<a href="s6-svlisten1.html">s6-svlisten1</a>, which will listen to service state
changes and spawn another s6-svc instance (without the <tt>-w</tt> option)
that will send the commands to the service. Any error message written during
the waiting period will mention it is being written by s6-svlisten1; this is normal. </li>
</ul>
<h2> Notes </h2>
<ul>
<li> The <tt>-t</tt> and <tt>-r</tt> options make <a href="s6-supervise.html">s6-supervise</a>
send a signal to the service if it is up; but if the service is currently down,
they do nothing, and in particular they do not instruct s6-supervise to bring the
service up. Consequently, <tt>s6-svc -rwr <em>servicedir</em></tt> may wait forever
for the service to be up, if it is currently wanted down. To avoid that, make sure
your service is wanted up by using <tt>s6-svc -ruwr <em>servicedir</em></tt> instead. </li>
<li> The <tt>U</tt> and <tt>D</tt> letters, which convey the same idea as <tt>u</tt>
and <tt>d</tt> (<em>up</em> and <em>down</em>) but with added emphasis, do not have the
same meaning in the <tt>-U</tt>/<tt>-D</tt> and <tt>-wU</tt>/<tt>-wD</tt> options.
In the <tt>-U</tt>/<tt>-D</tt> case, they mean "change the external service configuration
to match what the supervisor has been instructed that the starting state of the service
should be". In the <tt>-wU</tt>/<tt>-wD</tt> case, they mean "wait until the service
has reached the wanted state <em>and also</em> is ready" (or "ready to be started again"
for <tt>-wD</tt>). The thing to remember is "it's up/down, with something more", but
the "something" isn't the same. </li>
</ul>
</body>
</html>
|
