summaryrefslogtreecommitdiff
path: root/doc/s6-svc.html
blob: 0ca3bd765c1612955ccdf801950953ba7a824575 (plain)
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
<html>
  <head>
    <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="http://skarnet.org/default.css" /> -->
  </head>
<body>

<p>
<a href="index.html">s6</a><br />
<a href="http://skarnet.org/software/">Software</a><br />
<a href="http://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 [ -D | -U ] [ -t <em>timeout</em> ] [ -abqhkti12pcoduxO ] <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>&nbsp;: send a SIGALRM to the supervised process </li>
 <li> <tt>-b</tt>&nbsp;: send a SIGABRT to the supervised process </li>
 <li> <tt>-q</tt>&nbsp;: send a SIGQUIT to the supervised process </li>
 <li> <tt>-h</tt>&nbsp;: send a SIGHUP to the supervised process </li>
 <li> <tt>-k</tt>&nbsp;: send a SIGKILL to the supervised process </li>
 <li> <tt>-t</tt>&nbsp;: send a SIGTERM to the supervised process </li>
 <li> <tt>-i</tt>&nbsp;: send a SIGINT to the supervised process </li>
 <li> <tt>-1</tt>&nbsp;: send a SIGUSR1 to the supervised process </li>
 <li> <tt>-2</tt>&nbsp;: send a SIGUSR2 to the supervised process </li>
 <li> <tt>-p</tt>&nbsp;: send a SIGSTOP to the supervised process </li>
 <li> <tt>-c</tt>&nbsp;: send a SIGCONT to the supervised process </li>
 <li> <tt>-o</tt>&nbsp;: once. Equivalent to "-uO". </li>
 <li> <tt>-d</tt>&nbsp;: down. If the supervised process is up, send it
a SIGTERM and a SIGCONT. Do not restart it. </li>
 <li> <tt>-u</tt>&nbsp;: up. If the supervised process is down, start it.
Automatically restart it when it dies. </li>
 <li> <tt>-x</tt>&nbsp;: 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. </li>
 <li> <tt>-O</tt>&nbsp;: Once at most. 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>-t&nbsp;<em>timeout</em></tt>&nbsp;: if the <tt>-D</tt> or
<tt>-U</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>-D</tt>&nbsp;: s6-svc will not exit until the service is down. </li>
 <li> <tt>-U</tt>&nbsp;: s6-svc will not exit until the service is up and
<a href="notifywhenup.html">ready</a> as notified by the daemon itself.
Be careful to only use this command on services that send readiness
notifications and are managed by <a href="s6-notifywhenup.html">s6-notifywhenup</a>,
else the command will never be successful. </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 -t /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 -Dd /service/ftpd </pre>
<p>
 Take down the ftpd server and block until the process is really down.
</p>

<pre> s6-svc -Uu -t 5000 /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 -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. A 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 the <tt>-D</tt> or <tt>-U</tt> option, 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>-D</tt> or <tt>-U</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>

</body>
</html>