s6-svstat.html (7822B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: the s6-svstat program</title> 7 <meta name="Description" content="s6: the s6-svstat program" /> 8 <meta name="Keywords" content="s6 command s6-svstat servicedir checking supervision s6-supervise" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">s6</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> The s6-svstat program </h1> 20 21 <p> 22 s6-svstat prints a short, human-readable or programmatically parsable 23 summary of the state of a process monitored by 24 <a href="s6-supervise.html">s6-supervise</a>. 25 </p> 26 27 <h2> Interface </h2> 28 29 <pre> 30 s6-svstat [ -uwNrpest | -o up,wantedup,normallyup,ready,paused,pid,exitcode,signal,signum,updownsince,readysince,updownfor,readyfor ] [ -n ] <em>servicedir</em> 31 </pre> 32 33 <p> 34 s6-svstat gives information about the process being monitored 35 at the <em>servicedir</em> <a href="servicedir.html">service directory</a>, then 36 exits 0. 37 </p> 38 39 <p> 40 When s6-svstat is invoked without options, or with only the <tt>-n</tt> option, 41 it prints a human-readable summary of all the 42 available information on the service. In this case, the <tt>-n</tt> option 43 instructs it to print a signal number (instead of a signal name) if the 44 supervised process was killed by a signal. The summary includes the 45 following data: 46 </p> 47 48 <ul> 49 <li> whether the process is up or down, and if it's up, the number of 50 seconds that it has been up. </li> 51 <li> the process' pid, if it is up, or its last exit code or terminating 52 signal, if it is down </li> 53 <li> what its default state is, if it is different from its current state </li> 54 <li> the number of seconds since it last changed states </li> 55 <li> whether the service is <a href="notifywhenup.html">ready</a>, 56 as notified by the daemon itself, and 57 if it is, the number of seconds that it has been. 58 A service reported as down and ready simply means that it is ready 59 to be brought up. A service is down and not ready when it is in the 60 cleanup phase, i.e. the <tt>./finish</tt> script is still being executed. </li> 61 </ul> 62 63 <p> 64 When s6-svstat is invoked with one or several options other than <tt>-n</tt>, 65 it outputs programmatically parsable information instead. The output is a series of 66 space-separated values, one value per requested field. The valid options 67 are as follows. 68 </p> 69 70 <h2> Options </h2> 71 72 <ul> 73 <li> <tt>-o </tt><em>fields</em> : list fields to print. 74 <em>fields</em> is a list of comma-separated field names. The valid field 75 names are the following: 76 <ul> 77 <li> <tt>up</tt>: print <tt>true</tt> if the service is up and <tt>false</tt> if it is down. 78 <!-- 79 If the service is being throttled (i.e. technically up, but sleeping for a certain 80 amount of time before it is really launched), it prints <tt>throttled</tt> instead of <tt>true</tt>. 81 --> 82 </li> 83 <li> <tt>wantedup</tt>: print <tt>true</tt> if <a href="s6-supervise.html">s6-supervise</a> 84 is currently instructed to (re)start the service when it is down, and <tt>false</tt> if 85 <a href="s6-supervise.html">s6-supervise</a> is currently instructed to leave the service alone. </li> 86 <li> <tt>normallyup</tt>: print <tt>true</tt> if the service is supposed to start when 87 <a href="s6-supervise.html">s6-supervise</a> starts (i.e. no <tt>./down</tt> file), and <tt>false</tt> 88 if it is not (i.e. there is a <tt>./down</tt> file). </li> 89 <li> <tt>ready</tt>: print <tt>true</tt> if the service is ready, and <tt>false</tt> if 90 it is not. Note that a service can be both <em>down</em> and <em>ready</em>: it simply means that 91 it is ready to be started (i.e. no <tt>./finish</tt> script is currently running). To check for 92 service readiness, you should give this option along with <tt>up</tt>: the service is ready iff 93 <tt>s6-svstat -o up,ready</tt> prints <tt>true true</tt>. (The <tt>true true</tt> case will 94 never happen if the service does not support readiness notification.) </li> 95 <li> <tt>paused</tt>: print <tt>true</tt> if the service is paused (i.e. the process is 96 currently stopped) and <tt>false</tt> if it is not. It is a rare flag, you shouldn't normally 97 need to use this option. </li> 98 <li> <tt>pid</tt>: print the pid of the supervised process. If the service is currently down, 99 <tt>-1</tt> is printed instead. </li> 100 <li> <tt>exitcode</tt>: print the exit code of the last execution of <tt>./run</tt>. If the 101 service is currently up, or the last <tt>./run</tt> process was killed by a signal, 102 <tt>-1</tt> is printed instead. </li> 103 <li> <tt>signal</tt>: print the name of the signal the last <tt>./run</tt> process was 104 killed with. If the service is currently up, or the last <tt>./run</tt> process was not 105 killed by a signal, <tt>NA</tt> is printed instead. </li> 106 <li> <tt>signum</tt>: print the number of the signal the last <tt>./run</tt> process was 107 killed with. If the service is currently up, or the last <tt>./run</tt> process was not 108 killed by a signal, <tt>-1</tt> is printed instead. </li> 109 <li> <tt>updownsince</tt>: print a <a href="https://cr.yp.to/libtai/tai64.html">TAI64N 110 label</a> representing the absolute date when the service last changed states. </li> 111 <li> <tt>readysince</tt>: print a <a href="https://cr.yp.to/libtai/tai64.html">TAI64N 112 label</a> representing the absolute date when the service last became ready. Note that 113 this can either mean "service readiness" (if the service is currently up and ready), or 114 "down readiness", i.e. the last time when the service was down and ready to be started 115 (if the service is <em>not</em> currently up and ready). </li> 116 <li> <tt>updownfor</tt>: print the number of seconds that have elapsed since the 117 service last changed states. </li> 118 <li> <tt>readyfor</tt>: print the number of seconds that have elapsed since the 119 service last became ready (or ready to be started if it's currently not up and ready). </li> 120 </ul> 121 <li> <tt>-u</tt>: equivalent to <tt>-o up</tt>. </li> 122 <li> <tt>-w</tt>: equivalent to <tt>-o wantedup</tt>. </li> 123 <li> <tt>-N</tt>: equivalent to <tt>-o normallyup</tt>. </li> 124 <li> <tt>-r</tt>: equivalent to <tt>-o ready</tt>. </li> 125 <li> <tt>-p</tt>: equivalent to <tt>-o pid</tt>. </li> 126 <li> <tt>-e</tt>: equivalent to <tt>-o exitcode</tt>. </li> 127 <li> <tt>-s</tt>: equivalent to <tt>-o signal</tt>. </li> 128 <li> <tt>-t</tt>: equivalent to <tt>-o updownfor</tt>. </li> 129 </ul> 130 131 <h2> Exit codes </h2> 132 133 <ul> 134 <li> 0: success </li> 135 <li> 1: s6-supervise not running on <em>servicedir</em> </li> 136 <li> 100: wrong usage </li> 137 <li> 111: system call failed </li> 138 </ul> 139 140 <h2> Examples </h2> 141 142 <ul> 143 <li> <tt>s6-svstat -o up,ready</tt> (or its equivalent <tt>s6-svstat -ur</tt>) 144 will print <tt>true true</tt> if the service is up and 145 ready, <tt>true false</tt> if the service has been started but has not notified 146 readiness yet, <tt>false true</tt> if it is down and can be started, and 147 <tt>false false</tt> if it is down and there's a <tt>./finish</tt> script running 148 that needs to exit before the service can be restarted. </li> 149 <li> <tt>s6-svstat -o pid,exitcode,signal</tt> (or its equivalent <tt>s6-svstat -pes</tt>) 150 will print <tt>42 -1 NA</tt> if the service has 151 been started and <tt>./run</tt>'s pid is 42; it will print <tt>-1 0 NA</tt> if the 152 service is down and <tt>./run</tt> last exited 0; it will print <tt>-1 -1 SIGTERM</tt> 153 if the service is down and <tt>./run</tt> was last killed by a SIGTERM - as can 154 happen, for instance, when you down the service via a call to 155 <a href="s6-svc.html">s6-svc -d</a>. </li> 156 </ul> 157 158 </body> 159 </html>