s6-svc.html (9576B)
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-svc program</title> 7 <meta name="Description" content="s6: the s6-svc program" /> 8 <meta name="Keywords" content="s6 command s6-svc supervise command service" /> 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-svc program </h1> 20 21 <p> 22 s6-svc sends commands to a running <a href="s6-supervise.html">s6-supervise</a> 23 process. In other words, it's used to control a supervised process; among 24 other benefits, it allows an administrator to send signals to daemons without 25 knowing their PIDs, and without using horrible hacks such as .pid files. 26 </p> 27 28 <h2> Interface </h2> 29 30 <pre> 31 s6-svc [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -T <em>timeout</em> ] [ -s <em>signal</em> | -abqhkti12pcy ] [ -roduDUxO ] <em>servicedir</em> 32 </pre> 33 34 <p> 35 s6-svc sends the given series of commands to the 36 <a href="s6-supervise.html">s6-supervise</a> process monitoring the 37 <em>servicedir</em> directory, then exits 0. It exits 111 if it cannot send 38 a command, or 100 if no s6-supervise process is running on <em>servicedir</em>. 39 </p> 40 41 <h2> Options </h2> 42 43 <ul> 44 <li> <tt>-a</tt> : send a SIGALRM to the supervised process </li> 45 <li> <tt>-b</tt> : send a SIGABRT to the supervised process </li> 46 <li> <tt>-q</tt> : send a SIGQUIT to the supervised process </li> 47 <li> <tt>-h</tt> : send a SIGHUP to the supervised process </li> 48 <li> <tt>-k</tt> : send a SIGKILL to the supervised process </li> 49 <li> <tt>-t</tt> : send a SIGTERM to the supervised process </li> 50 <li> <tt>-i</tt> : send a SIGINT to the supervised process </li> 51 <li> <tt>-1</tt> : send a SIGUSR1 to the supervised process </li> 52 <li> <tt>-2</tt> : send a SIGUSR2 to the supervised process </li> 53 <li> <tt>-p</tt> : send a SIGSTOP to the supervised process </li> 54 <li> <tt>-c</tt> : send a SIGCONT to the supervised process </li> 55 <li> <tt>-y</tt> : send a SIGWINCH to the supervised process </li> 56 <li> <tt>-s <em>signal</em></tt> : send <em>signal</em> to the 57 supervised process. <em>signal</em> can be given as its name (case- 58 insensitive) or its number, but only the signals listed above are 59 accepted - you cannot, for instance, manually send a SIGSEGV to the 60 supervised process. </li> 61 </ul> <br /> 62 <ul> 63 <li> <tt>-o</tt> : once. Equivalent to "-uO". </li> 64 <li> <tt>-d</tt> : down. If the supervised process is up, send it 65 a SIGTERM (by default) then a SIGCONT (to make sure even stopped processes 66 receive the signal aimed to kill them) and do not restart it. 67 The SIGTERM default can be changed by editing the <tt>./down-signal</tt> 68 file in the <a href="servicedir.html">service directory</a>. </li> 69 <li> <tt>-D</tt> : down, and create a <tt>./down</tt> file so the 70 service does not restart automatically if the supervisor dies. This 71 option is mostly used by automated systems working on top of s6; as a 72 human user, you probably don't need it. </li> 73 <li> <tt>-u</tt> : up. If the supervised process is down, start it. 74 Automatically restart it when it dies. </li> 75 <li> <tt>-U</tt> : up, and remove any <tt>./down</tt> file that may 76 exist, in order to make sure the service is automatically restarted even 77 if the supervisor dies. This option is mostly used by automated systems 78 working on top of s6; as a human user, you probably don't need it. </li> 79 <li> <tt>-x</tt> : exit. When the service is asked to be down and 80 the supervised process dies, s6-supervise will exit too. This command should 81 normally never be used on a working system. Note that if this command is 82 sent and a <tt>./finish</tt> script exists for the service, the last 83 <tt>./finish</tt> invocation before 84 <a href="s6-supervise.html">s6-supervise</a> exits will run with its stdin 85 and stdout redirected to <tt>/dev/null</tt>. </li> 86 <li> <tt>-O</tt> : mark the service to run once at most. iow: do not 87 restart the supervised process when it dies. If it is down when the command 88 is received, do not even start it. </li> 89 <li> <tt>-Q</tt> : once at most, and create a <tt>./down</tt> file. 90 Like <tt>-D</tt>, but do not terminate the service if it is currently 91 running. </li> 92 <li> <tt>-r</tt> : If the service is up, restart it, by sending it a 93 signal to kill it and letting <a href="s6-supervise.html">s6-supervise</a> 94 start it again. By default, the signal is a SIGTERM; this can be configured 95 via the <tt>./down-signal</tt> file in the <a href="servicedir.html">service 96 directory</a>. </li> 97 <li> <tt>-T <em>timeout</em></tt> : if the <tt>-w<em>state</em></tt> 98 option has been given, <tt>-T</tt> specifies a timeout 99 (in milliseconds) after which s6-svc will exit 1 with an error message if 100 the service still hasn't reached the desired state. By default, the 101 timeout is 0, which means that s6-svc will block indefinitely. </li> 102 <li> <tt>-wd</tt> : s6-svc will not exit until the service is down, 103 i.e. until the <tt>run</tt> process has died. </li> 104 <li> <tt>-wD</tt> : s6-svc will not exit until the service is down 105 <em>and</em> ready to be brought up, i.e. a possible <tt>finish</tt> script has 106 exited. </li> 107 <li> <tt>-wu</tt> : s6-svc will not exit until the service is up, 108 i.e. there is a process running the <tt>run</tt> executable. </li> 109 <li> <tt>-wU</tt> : s6-svc will not exit until the service is up <em>and</em> 110 <a href="notifywhenup.html">ready</a> as notified by the daemon itself. 111 If the <a href="servicedir.html">service directory</a> does not contain 112 a <tt>notification-fd</tt> file to tell 113 <a href="s6-supervise.html">s6-supervise</a> to accept readiness 114 notification, s6-svc will print a warning and act as if the <tt>-wu</tt> 115 option had been given instead. </li> 116 <li> <tt>-wr</tt> : s6-svc will not exit until the service has been 117 started or restarted. </li> 118 <li> <tt>-wR</tt> : s6-svc will not exit until the service has been 119 started or restarted and has notified readiness. </li> 120 121 </ul> 122 123 <h2> Usage examples </h2> 124 125 <pre> s6-svc -h /service/httpd </pre> 126 <p> 127 Send a SIGHUP to the process represented by the <tt>/service/httpd</tt> 128 service directory. Traditionally, this makes web servers reload their 129 configuration file. 130 </p> 131 132 <pre> s6-svc -r /service/sshd </pre> 133 <p> 134 Kill (and automatically restart, if the wanted state of the service is up) 135 the process represented by the <tt>/service/sshd</tt> service directory - 136 typically the sshd server. 137 </p> 138 139 <pre> s6-svc -wD -d /service/ftpd </pre> 140 <p> 141 Take down the ftpd server and block until the process is down and 142 the finish script has completed. 143 </p> 144 145 <pre> s6-svc -wU -T 5000 -u /service/ftpd </pre> 146 <p> 147 Bring up the ftpd server and block until it has sent notification that it 148 is ready. Exit 1 if it is still not ready after 5 seconds. 149 </p> 150 151 <pre> s6-svc -wR -t /service/ftpd </pre> 152 <p> 153 Send a SIGTERM to the ftpd server; wait for 154 <a href="s6-supervise.html">s6-supervise</a> to restart it, and block 155 until it has notified that it is ready to serve again. See the NOTES 156 section below for a caveat. 157 </p> 158 159 <pre> s6-svc -a /service/httpd/log </pre> 160 <p> 161 Send a SIGALRM to the logger process for the httpd server. If this logger 162 process is <a href="s6-log.html">s6-log</a>, this triggers a log rotation. 163 </p> 164 165 <h2> Internals </h2> 166 167 <ul> 168 <li> s6-svc writes control commands into the <tt><em>servicedir</em>/supervise/control</tt> 169 FIFO. An s6-supervise process running on <em>servicedir</em> will be listening to this FIFO, 170 and will read and interpret those commands. </li> 171 <li> When invoked with one of the <tt>-w</tt> options, s6-svc executes into 172 <a href="s6-svlisten1.html">s6-svlisten1</a>, which will listen to service state 173 changes and spawn another s6-svc instance (without the <tt>-w</tt> option) 174 that will send the commands to the service. Any error message written during 175 the waiting period will mention it is being written by s6-svlisten1; this is normal. </li> 176 </ul> 177 178 <h2> Notes </h2> 179 180 <ul> 181 <li> The <tt>-t</tt> and <tt>-r</tt> options make <a href="s6-supervise.html">s6-supervise</a> 182 send a signal to the service if it is up; but if the service is currently down, 183 they do nothing, and in particular they do not instruct s6-supervise to bring the 184 service up. Consequently, <tt>s6-svc -rwr <em>servicedir</em></tt> may wait forever 185 for the service to be up, if it is currently wanted down. To avoid that, make sure 186 your service is wanted up by using <tt>s6-svc -ruwr <em>servicedir</em></tt> instead. </li> 187 <li> The <tt>U</tt> and <tt>D</tt> letters, which convey the same idea as <tt>u</tt> 188 and <tt>d</tt> (<em>up</em> and <em>down</em>) but with added emphasis, do not have the 189 same meaning in the <tt>-U</tt>/<tt>-D</tt> and <tt>-wU</tt>/<tt>-wD</tt> options. 190 In the <tt>-U</tt>/<tt>-D</tt> case, they mean "change the external service configuration 191 to match what the supervisor has been instructed that the starting state of the service 192 should be". In the <tt>-wU</tt>/<tt>-wD</tt> case, they mean "wait until the service 193 has reached the wanted state <em>and also</em> is ready" (or "ready to be started again" 194 for <tt>-wD</tt>). The thing to remember is "it's up/down, with something more", but 195 the "something" isn't the same. </li> 196 </ul> 197 198 </body> 199 </html>