File: runsv.8

package info (click to toggle)
runit 2.1.2-9.2
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 1,660 kB
  • ctags: 1,087
  • sloc: ansic: 5,701; sh: 664; makefile: 361
file content (223 lines) | stat: -rw-r--r-- 4,859 bytes parent folder | download | duplicates (3)
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
.TH runsv 8
.SH NAME
runsv \- starts and monitors a service and optionally an appendant log
service
.SH SYNOPSIS
.B runsv
.I service
.SH DESCRIPTION
.I service
must be a directory.
.P
.B runsv
switches to the directory
.I service
and starts ./run.
If ./run exits and ./finish exists,
.B runsv
starts ./finish.
If ./finish doesn't exist or ./finish exits,
.B runsv
restarts ./run.
.P
If ./run or ./finish exit immediately,
.B runsv
waits a second before starting ./finish or restarting ./run.
.P
Two arguments are given to ./finish.
The first one is ./run's exit code, or -1 if ./run didn't exit normally.
The second one is the least significant byte of the exit status as
determined by
.BR waitpid (2);
for instance it is 0 if ./run exited normally, and the signal number
if ./run was terminated by a signal.
If
.B runsv
cannot start ./run for some reason, the exit code is 111 and the status is 0.
.P
If the file
.IR service /down
exists,
.B runsv
does not start ./run immediately.
The control interface (see below) can be used to start the service and to
give other commands to
.BR runsv .
.P
If the directory
.IR service /log
exists,
.B runsv
creates a pipe, redirects
.IR service /run's
and
.IR service /finish's
standard output to the pipe, switches to the directory
.IR service /log
and starts ./run script. The standard input of the log service
is redirected to read from the pipe.
.P
.B runsv
maintains status information in a binary format (compatible to the
daemontools'
.B supervise
program) in
.IR service /supervise/status
and
.IR service /log/supervise/status,
and in a human-readable format in
.IR service /supervise/stat,
.IR service /log/supervise/stat,
.IR service /supervise/pid,
.IR service /log/supervise/pid.
.SH CONTROL
The named pipes
.IR service /supervise/control,
and (optionally)
.IR service /log/supervise/control
are provided to give commands to
.BR runsv .
You can use
.BR sv (8)
to control the service or just write one of the following characters to
the named pipe:
.TP
.B u
Up.
If the service is not running, start it.
If the service stops, restart it.
.TP
.B d
Down.
If the service is running, send it a TERM signal, and then a CONT signal.
If ./run exits, start ./finish if it exists.
After it stops, do not restart service.
.TP
.B o
Once.
If the service is not running, start it.
Do not restart it if it stops.
.TP
.B p
Pause.
If the service is running, send it a STOP signal.
.TP
.B c
Continue.
If the service is running, send it a CONT signal.
.TP
.B h
Hangup.
If the service is running, send it a HUP signal.
.TP
.B a
Alarm.
If the service is running, send it a ALRM signal.
.TP
.B i
Interrupt.
If the service is running, send it a INT signal.
.TP
.B q
Quit.
If the service is running, send it a QUIT signal.
.TP
.B 1
User-defined 1.
If the service is running, send it a USR1 signal.
.TP
.B 2
User-defined 2.
If the service is running, send it a USR2 signal.
.TP
.B t
Terminate.
If the service is running, send it a TERM signal.
.TP
.B k
Kill.
If the service is running, send it a KILL signal.
.TP
.B x
Exit.
If the service is running, send it a TERM signal, and then a CONT signal.
Do not restart the service.
If the service is down, and no log service exists,
.B runsv
exits.
If the service is down and a log service exists,
.B runsv
closes the standard input of the log service, and waits for it to terminate.
If the log service is down,
.B runsv
exits.
This command is ignored if it is given to
.IR service /log/supervise/control.
.P
Example: to send a TERM signal to the socklog-unix service, either do
  # sv term /etc/service/socklog-unix
 or
  # printf t >/etc/service/socklog-unix/supervise/control
.P
.BR printf (1)
usually blocks if no
.B runsv
process is running in the service directory.
.SH CUSTOMIZE CONTROL
For each control character
.I c
sent to the control pipe,
.B runsv
first checks if
.I service\fR/control/\fIc
exists and is executable.
If so, it starts
.I service\fR/control/\fIc
and waits for it to terminate, before interpreting the command.
If the program exits with return code 0,
.B runsv
refrains from sending the service the corresponding signal.
The command
.I o
is always considered as command
.IR u .
On command
.I d
first
.I service\fR/control/t
is checked, and then
.I service\fR/control/d.
On command
.I x
first
.I service\fR/control/t
is checked, and then
.I service\fR/control/x.
The control of the optional log service cannot be customized.
.SH SIGNALS
If
.B runsv
receives a TERM signal, it acts as if the character x was written to the
control pipe.
.SH EXIT CODES
.B runsv
exits 111 on an error on startup or if another
.B runsv
is running in
.IR service .
.P
.B runsv
exits 0 if it was told to exit.
.SH SEE ALSO
sv(8),
chpst(8),
svlogd(8),
runit(8),
runit-init(8),
runsvdir(8),
runsvchdir(8),
utmpset(8)
.P
http://smarden.org/runit/
.SH AUTHOR
Gerrit Pape <pape@smarden.org>