runsv.8.html (6515B)
1 2 3 4 <html> 5 <head> 6 <title>runsv(8) manual page</title> 7 </head> 8 <body bgcolor='white'> 9 <a href='http://smarden.org/pape/'>G. Pape</a><br><a href='index.html'>runit</A><hr><p> 10 11 <h2><a name='sect0'>Name</a></h2> 12 runsv - starts and monitors a service and optionally an appendant log 13 service 14 <h2><a name='sect1'>Synopsis</a></h2> 15 <b>runsv</b> <i>service</i> 16 <h2><a name='sect2'>Description</a></h2> 17 <i>service</i> must be a directory. <p> 18 <b>runsv</b> 19 switches to the directory <i>service</i> and starts ./run. If ./run exits and ./finish 20 exists, <b>runsv</b> starts ./finish. If ./finish doesn’t exist or ./finish exits, 21 <b>runsv</b> restarts ./run. <p> 22 If ./run or ./finish exit immediately, <b>runsv</b> waits a 23 second before starting ./finish or restarting ./run. <p> 24 Two arguments are given 25 to ./finish. The first one is ./run’s exit code, or -1 if ./run didn’t exit normally. 26 The second one is the least significant byte of the exit status as determined 27 by <i><b>waitpid</b>(2)</i>; for instance it is 0 if ./run exited normally, and the signal 28 number if ./run was terminated by a signal. If <b>runsv</b> cannot start ./run for 29 some reason, the exit code is 111 and the status is 0. <p> 30 If the file <i>service</i>/down 31 exists, <b>runsv</b> does not start ./run immediately. The control interface (see 32 below) can be used to start the service and to give other commands to <b>runsv</b>. 33 <p> 34 If the directory <i>service</i>/log exists, <b>runsv</b> creates a pipe, redirects <i>service</i>/run’s 35 and <i>service</i>/finish’s standard output to the pipe, switches to the directory 36 <i>service</i>/log and starts ./run (and ./finish) exactly as described above for 37 the <i>service</i> directory. The standard input of the log service is redirected 38 to read from the pipe. <p> 39 <b>runsv</b> maintains status information in a binary format 40 (compatible to the daemontools’ <b>supervise</b> program) in <i>service</i>/supervise/status 41 and <i>service</i>/log/supervise/status, and in a human-readable format in <i>service</i>/supervise/stat, 42 <i>service</i>/log/supervise/stat, <i>service</i>/supervise/pid, <i>service</i>/log/supervise/pid. 43 44 <h2><a name='sect3'>Control</a></h2> 45 The named pipes <i>service</i>/supervise/control, and (optionally) <i>service</i>/log/supervise/control 46 are provided to give commands to <b>runsv</b>. You can use <i><b>sv</b>(8)</i> to control the 47 service or just write one of the following characters to the named pipe: 48 49 <dl> 50 51 <dt><b>u</b> </dt> 52 <dd>Up. If the service is not running, start it. If the service stops, restart 53 it. </dd> 54 55 <dt><b>d</b> </dt> 56 <dd>Down. If the service is running, send it a TERM signal, and then a 57 CONT signal. If ./run exits, start ./finish if it exists. After it stops, do 58 not restart service. </dd> 59 60 <dt><b>o</b> </dt> 61 <dd>Once. If the service is not running, start it. Do not 62 restart it if it stops. </dd> 63 64 <dt><b>p</b> </dt> 65 <dd>Pause. If the service is running, send it a STOP 66 signal. </dd> 67 68 <dt><b>c</b> </dt> 69 <dd>Continue. If the service is running, send it a CONT signal. </dd> 70 71 <dt><b>h</b> </dt> 72 <dd>Hangup. 73 If the service is running, send it a HUP signal. </dd> 74 75 <dt><b>a</b> </dt> 76 <dd>Alarm. If the service 77 is running, send it a ALRM signal. </dd> 78 79 <dt><b>i</b> </dt> 80 <dd>Interrupt. If the service is running, 81 send it a INT signal. </dd> 82 83 <dt><b>q</b> </dt> 84 <dd>Quit. If the service is running, send it a QUIT signal. </dd> 85 86 <dt><b>1</b> </dt> 87 <dd>User-defined 1. If the service is running, send it a USR1 signal. </dd> 88 89 <dt><b>2</b> </dt> 90 <dd>User-defined 2. If the service is running, send it a USR2 signal. </dd> 91 92 <dt><b>t</b> </dt> 93 <dd>Terminate. If the service 94 is running, send it a TERM signal. </dd> 95 96 <dt><b>k</b> </dt> 97 <dd>Kill. If the service is running, send 98 it a KILL signal. </dd> 99 100 <dt><b>x</b> </dt> 101 <dd>Exit. If the service is running, send it a TERM signal, 102 and then a CONT signal. Do not restart the service. If the service is down, 103 and no log service exists, <b>runsv</b> exits. If the service is down and a log 104 service exists, <b>runsv</b> closes the standard input of the log service, and 105 waits for it to terminate. If the log service is down, <b>runsv</b> exits. This 106 command is ignored if it is given to <i>service</i>/log/supervise/control. </dd> 107 </dl> 108 <p> 109 Example: 110 to send a TERM signal to the socklog-unix service, either do # sv term 111 /service/socklog-unix<br> 112 or<br> 113 # printf t >/service/socklog-unix/supervise/control<br> 114 <p> 115 <i><b>printf</b>(1)</i> usually blocks if no <b>runsv</b> process is running in the service 116 directory. 117 <h2><a name='sect4'>Customize Control</a></h2> 118 For each control character <i>c</i> sent to the control 119 pipe, <b>runsv</b> first checks if <i>service</i>/control/<i>c</i> exists and is executable. 120 If so, it starts <i>service</i>/control/<i>c</i> and waits for it to terminate, before 121 interpreting the command. If the program exits with return code 0, <b>runsv</b> 122 refrains from sending the service the corresponding signal. The command 123 <i>o</i> is always considered as command <i>u</i>. On command <i>d</i> first <i>service</i>/control/<i>t</i> 124 is checked, and then <i>service</i>/control/<i>d</i>. On command <i>x</i> first <i>service</i>/control/<i>t</i> 125 is checked, and then <i>service</i>/control/<i>x</i>. The control of the optional log 126 service cannot be customized. 127 <h2><a name='sect5'>Signals</a></h2> 128 If <b>runsv</b> receives a TERM signal, it 129 acts as if the character x was written to the control pipe. 130 <h2><a name='sect6'>Exit Codes</a></h2> 131 <b>runsv</b> 132 exits 111 on an error on startup or if another <b>runsv</b> is running in <i>service</i>. 133 <p> 134 <b>runsv</b> exits 0 if it was told to exit. 135 <h2><a name='sect7'>See Also</a></h2> 136 <i>sv(8)</i>, <i>chpst(8)</i>, <i>svlogd(8)</i>, 137 <i>runit(8)</i>, <i>runit-init(8)</i>, <i>runsvdir(8)</i>, <i>runsvchdir(8)</i>, <i>utmpset(8)</i> <p> 138 <i>http://smarden.org/runit/</i> 139 140 <h2><a name='sect8'>Author</a></h2> 141 Gerrit Pape <pape@smarden.org> <p> 142 143 <hr><p> 144 <a name='toc'><b>Table of Contents</b></a><p> 145 <ul> 146 <li><a name='toc0' href='#sect0'>Name</a></li> 147 <li><a name='toc1' href='#sect1'>Synopsis</a></li> 148 <li><a name='toc2' href='#sect2'>Description</a></li> 149 <li><a name='toc3' href='#sect3'>Control</a></li> 150 <li><a name='toc4' href='#sect4'>Customize Control</a></li> 151 <li><a name='toc5' href='#sect5'>Signals</a></li> 152 <li><a name='toc6' href='#sect6'>Exit Codes</a></li> 153 <li><a name='toc7' href='#sect7'>See Also</a></li> 154 <li><a name='toc8' href='#sect8'>Author</a></li> 155 </ul> 156 </body> 157 </html>