runsv.8 (4923B)
1 .TH runsv 8 2 .SH NAME 3 runsv \- starts and monitors a service and optionally an appendant log 4 service 5 .SH SYNOPSIS 6 .B runsv 7 .I service 8 .SH DESCRIPTION 9 .I service 10 must be a directory. 11 .P 12 .B runsv 13 switches to the directory 14 .I service 15 and starts ./run. 16 If ./run exits and ./finish exists, 17 .B runsv 18 starts ./finish. 19 If ./finish doesn't exist or ./finish exits, 20 .B runsv 21 restarts ./run. 22 .P 23 If ./run or ./finish exit immediately, 24 .B runsv 25 waits a second before starting ./finish or restarting ./run. 26 .P 27 Two arguments are given to ./finish. 28 The first one is ./run's exit code, or -1 if ./run didn't exit normally. 29 The second one is the least significant byte of the exit status as 30 determined by 31 .BR waitpid (2); 32 for instance it is 0 if ./run exited normally, and the signal number 33 if ./run was terminated by a signal. 34 If 35 .B runsv 36 cannot start ./run for some reason, the exit code is 111 and the status is 0. 37 .P 38 If the file 39 .IR service /down 40 exists, 41 .B runsv 42 does not start ./run immediately. 43 The control interface (see below) can be used to start the service and to 44 give other commands to 45 .BR runsv . 46 .P 47 If the directory 48 .IR service /log 49 exists, 50 .B runsv 51 creates a pipe, redirects 52 .IR service /run's 53 and 54 .IR service /finish's 55 standard output to the pipe, switches to the directory 56 .IR service /log 57 and starts ./run (and ./finish) exactly as described above for the 58 .I service 59 directory. 60 The standard input of the log service is redirected to read from the pipe. 61 .P 62 .B runsv 63 maintains status information in a binary format (compatible to the 64 daemontools' 65 .B supervise 66 program) in 67 .IR service /supervise/status 68 and 69 .IR service /log/supervise/status, 70 and in a human-readable format in 71 .IR service /supervise/stat, 72 .IR service /log/supervise/stat, 73 .IR service /supervise/pid, 74 .IR service /log/supervise/pid. 75 .SH CONTROL 76 The named pipes 77 .IR service /supervise/control, 78 and (optionally) 79 .IR service /log/supervise/control 80 are provided to give commands to 81 .BR runsv . 82 You can use 83 .BR sv (8) 84 to control the service or just write one of the following characters to 85 the named pipe: 86 .TP 87 .B u 88 Up. 89 If the service is not running, start it. 90 If the service stops, restart it. 91 .TP 92 .B d 93 Down. 94 If the service is running, send it a TERM signal, and then a CONT signal. 95 If ./run exits, start ./finish if it exists. 96 After it stops, do not restart service. 97 .TP 98 .B o 99 Once. 100 If the service is not running, start it. 101 Do not restart it if it stops. 102 .TP 103 .B p 104 Pause. 105 If the service is running, send it a STOP signal. 106 .TP 107 .B c 108 Continue. 109 If the service is running, send it a CONT signal. 110 .TP 111 .B h 112 Hangup. 113 If the service is running, send it a HUP signal. 114 .TP 115 .B a 116 Alarm. 117 If the service is running, send it a ALRM signal. 118 .TP 119 .B i 120 Interrupt. 121 If the service is running, send it a INT signal. 122 .TP 123 .B q 124 Quit. 125 If the service is running, send it a QUIT signal. 126 .TP 127 .B 1 128 User-defined 1. 129 If the service is running, send it a USR1 signal. 130 .TP 131 .B 2 132 User-defined 2. 133 If the service is running, send it a USR2 signal. 134 .TP 135 .B t 136 Terminate. 137 If the service is running, send it a TERM signal. 138 .TP 139 .B k 140 Kill. 141 If the service is running, send it a KILL signal. 142 .TP 143 .B x 144 Exit. 145 If the service is running, send it a TERM signal, and then a CONT signal. 146 Do not restart the service. 147 If the service is down, and no log service exists, 148 .B runsv 149 exits. 150 If the service is down and a log service exists, 151 .B runsv 152 closes the standard input of the log service, and waits for it to terminate. 153 If the log service is down, 154 .B runsv 155 exits. 156 This command is ignored if it is given to 157 .IR service /log/supervise/control. 158 .P 159 Example: to send a TERM signal to the socklog-unix service, either do 160 # sv term /var/service/socklog-unix 161 or 162 # printf t >/var/service/socklog-unix/supervise/control 163 .P 164 .BR printf (1) 165 usually blocks if no 166 .B runsv 167 process is running in the service directory. 168 .SH CUSTOMIZE CONTROL 169 For each control character 170 .I c 171 sent to the control pipe, 172 .B runsv 173 first checks if 174 .I service\fR/control/\fIc 175 exists and is executable. 176 If so, it starts 177 .I service\fR/control/\fIc 178 and waits for it to terminate, before interpreting the command. 179 If the program exits with return code 0, 180 .B runsv 181 refrains from sending the service the corresponding signal. 182 The command 183 .I o 184 is always considered as command 185 .IR u . 186 On command 187 .I d 188 first 189 .I service\fR/control/t 190 is checked, and then 191 .I service\fR/control/d. 192 On command 193 .I x 194 first 195 .I service\fR/control/t 196 is checked, and then 197 .I service\fR/control/x. 198 The control of the optional log service cannot be customized. 199 .SH SIGNALS 200 If 201 .B runsv 202 receives a TERM signal, it acts as if the character x was written to the 203 control pipe. 204 .SH EXIT CODES 205 .B runsv 206 exits 111 on an error on startup or if another 207 .B runsv 208 is running in 209 .IR service . 210 .P 211 .B runsv 212 exits 0 if it was told to exit. 213 .SH SEE ALSO 214 sv(8), 215 chpst(8), 216 svlogd(8), 217 runit(8), 218 runit-init(8), 219 runsvdir(8), 220 runsvchdir(8), 221 utmpset(8) 222 .P 223 http://smarden.org/runit/ 224 .SH AUTHOR 225 Gerrit Pape <pape@smarden.org>