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
|
<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-svstat program</title>
<meta name="Description" content="s6: the s6-svstat program" />
<meta name="Keywords" content="s6 command s6-svstat servicedir checking supervision s6-supervise" />
<!-- <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-svstat program </h1>
<p>
s6-svstat prints a short, human-readable or programmatically parsable
summary of the state of a process monitored by
<a href="s6-supervise.html">s6-supervise</a>.
</p>
<h2> Interface </h2>
<pre>
s6-svstat [ -uwNrpest | -o up,wantedup,normallyup,ready,paused,pid,pgid,exitcode,signal,signum,updownsince,readysince,updownfor,readyfor ] [ -n ] <em>servicedir</em>
</pre>
<p>
s6-svstat gives information about the process being monitored
at the <em>servicedir</em> <a href="servicedir.html">service directory</a>, then
exits 0.
</p>
<p>
When s6-svstat is invoked without options, or with only the <tt>-n</tt> option,
it prints a human-readable summary of all the
available information on the service. In this case, the <tt>-n</tt> option
instructs it to print a signal number (instead of a signal name) if the
supervised process was killed by a signal. The summary includes the
following data:
</p>
<ul>
<li> whether the process is up or down, and if it's up, the number of
seconds that it has been up. </li>
<li> the process' pid, if it is up, or its last exit code or terminating
signal, if it is down </li>
<li> what its default state is, if it is different from its current state </li>
<li> the number of seconds since it last changed states </li>
<li> whether the service is <a href="notifywhenup.html">ready</a>,
as notified by the daemon itself, and
if it is, the number of seconds that it has been.
A service reported as down and ready simply means that it is ready
to be brought up. A service is down and not ready when it is in the
cleanup phase, i.e. the <tt>./finish</tt> script is still being executed. </li>
</ul>
<p>
When s6-svstat is invoked with one or several options other than <tt>-n</tt>,
it outputs programmatically parsable information instead. The output is a series of
space-separated values, one value per requested field. The valid options
are as follows.
</p>
<h2> Options </h2>
<ul>
<li> <tt>-o </tt><em>fields</em> : list fields to print.
<em>fields</em> is a list of comma-separated field names. The valid field
names are the following:
<ul>
<li> <tt>up</tt>: print <tt>true</tt> if the service is up and <tt>false</tt> if it is down.
<!--
If the service is being throttled (i.e. technically up, but sleeping for a certain
amount of time before it is really launched), it prints <tt>throttled</tt> instead of <tt>true</tt>.
-->
</li>
<li> <tt>wantedup</tt>: print <tt>true</tt> if <a href="s6-supervise.html">s6-supervise</a>
is currently instructed to (re)start the service when it is down, and <tt>false</tt> if
<a href="s6-supervise.html">s6-supervise</a> is currently instructed to leave the service alone. </li>
<li> <tt>normallyup</tt>: print <tt>true</tt> if the service is supposed to start when
<a href="s6-supervise.html">s6-supervise</a> starts (i.e. no <tt>./down</tt> file), and <tt>false</tt>
if it is not (i.e. there is a <tt>./down</tt> file). </li>
<li> <tt>ready</tt>: print <tt>true</tt> if the service is ready, and <tt>false</tt> if
it is not. Note that a service can be both <em>down</em> and <em>ready</em>: it simply means that
it is ready to be started (i.e. no <tt>./finish</tt> script is currently running). To check for
service readiness, you should give this option along with <tt>up</tt>: the service is ready iff
<tt>s6-svstat -o up,ready</tt> prints <tt>true true</tt>. (The <tt>true true</tt> case will
never happen if the service does not support readiness notification.) </li>
<li> <tt>paused</tt>: print <tt>true</tt> if the service is paused (i.e. the process is
currently stopped) and <tt>false</tt> if it is not. It is a rare flag, you shouldn't normally
need to use this option. </li>
<li> <tt>pid</tt>: print the pid of the supervised process. If the service is currently down,
<tt>-1</tt> is printed instead. </li>
<li> <tt>pgid</tt>: print the process group of the supervised process. If the service is
currently down, print the process group of the last living instance of the service. </li>
<li> <tt>exitcode</tt>: print the exit code of the last execution of <tt>./run</tt>. If the
service is currently up, or the last <tt>./run</tt> process was killed by a signal,
<tt>-1</tt> is printed instead. </li>
<li> <tt>signal</tt>: print the name of the signal the last <tt>./run</tt> process was
killed with. If the service is currently up, or the last <tt>./run</tt> process was not
killed by a signal, <tt>NA</tt> is printed instead. </li>
<li> <tt>signum</tt>: print the number of the signal the last <tt>./run</tt> process was
killed with. If the service is currently up, or the last <tt>./run</tt> process was not
killed by a signal, <tt>-1</tt> is printed instead. </li>
<li> <tt>updownsince</tt>: print a <a href="https://cr.yp.to/libtai/tai64.html">TAI64N
label</a> representing the absolute date when the service last changed states. </li>
<li> <tt>readysince</tt>: print a <a href="https://cr.yp.to/libtai/tai64.html">TAI64N
label</a> representing the absolute date when the service last became ready. Note that
this can either mean "service readiness" (if the service is currently up and ready), or
"down readiness", i.e. the last time when the service was down and ready to be started
(if the service is <em>not</em> currently up and ready). </li>
<li> <tt>updownfor</tt>: print the number of seconds that have elapsed since the
service last changed states. </li>
<li> <tt>readyfor</tt>: print the number of seconds that have elapsed since the
service last became ready (or ready to be started if it's currently not up and ready). </li>
</ul>
<li> <tt>-u</tt>: equivalent to <tt>-o up</tt>. </li>
<li> <tt>-w</tt>: equivalent to <tt>-o wantedup</tt>. </li>
<li> <tt>-N</tt>: equivalent to <tt>-o normallyup</tt>. </li>
<li> <tt>-r</tt>: equivalent to <tt>-o ready</tt>. </li>
<li> <tt>-p</tt>: equivalent to <tt>-o pid</tt>. </li>
<li> <tt>-g</tt>: equivalent to <tt>-o pgid</tt>. </li>
<li> <tt>-e</tt>: equivalent to <tt>-o exitcode</tt>. </li>
<li> <tt>-s</tt>: equivalent to <tt>-o signal</tt>. </li>
<li> <tt>-t</tt>: equivalent to <tt>-o updownfor</tt>. </li>
</ul>
<h2> Exit codes </h2>
<ul>
<li> 0: success </li>
<li> 1: s6-supervise not running on <em>servicedir</em> </li>
<li> 100: wrong usage </li>
<li> 111: system call failed </li>
</ul>
<h2> Examples </h2>
<ul>
<li> <tt>s6-svstat -o up,ready</tt> (or its equivalent <tt>s6-svstat -ur</tt>)
will print <tt>true true</tt> if the service is up and
ready, <tt>true false</tt> if the service has been started but has not notified
readiness yet, <tt>false true</tt> if it is down and can be started, and
<tt>false false</tt> if it is down and there's a <tt>./finish</tt> script running
that needs to exit before the service can be restarted. </li>
<li> <tt>s6-svstat -o pid,exitcode,signal</tt> (or its equivalent <tt>s6-svstat -pes</tt>)
will print <tt>42 -1 NA</tt> if the service has
been started and <tt>./run</tt>'s pid is 42; it will print <tt>-1 0 NA</tt> if the
service is down and <tt>./run</tt> last exited 0; it will print <tt>-1 -1 SIGTERM</tt>
if the service is down and <tt>./run</tt> was last killed by a SIGTERM - as can
happen, for instance, when you down the service via a call to
<a href="s6-svc.html">s6-svc -d</a>. </li>
</ul>
</body>
</html>
|
