]>
Commit | Line | Data |
---|---|---|
8bff25f4 ER |
1 | .TH START\-STOP\-DAEMON 8 "15th March 1997" "Debian Project" "dpkg utilities" |
2 | .SH NAME | |
3 | start\-stop\-daemon \- start and stop system daemon programs | |
4 | .SH SYNOPSIS | |
5 | .B start\-stop\-daemon | |
6 | .BR \-S | \-\-start | |
7 | .IR options | |
8 | .RB [ \-\- ] | |
9 | .IR arguments | |
10 | .HP | |
11 | .B start\-stop\-daemon | |
12 | .BR \-K | \-\-stop | |
13 | .IR options | |
14 | .HP | |
15 | .B start\-stop\-daemon | |
16 | .BR \-H | \-\-help | |
17 | .HP | |
18 | .B start\-stop\-daemon | |
19 | .BR \-V | \-\-version | |
20 | .SH DESCRIPTION | |
21 | .B start\-stop\-daemon | |
22 | is used to control the creation and termination of system-level processes. | |
23 | Using the | |
24 | .BR \-\-exec ", " \-\-pidfile ", " \-\-user ", and " \-\-name " options," | |
25 | .B start\-stop\-daemon | |
26 | can be configured to find existing instances of a running process. | |
27 | ||
28 | With | |
29 | .BR \-\-start , | |
30 | .B start\-stop\-daemon | |
31 | checks for the existence of a specified process. | |
32 | If such a process exists, | |
33 | .B start\-stop\-daemon | |
34 | does nothing, and exits with error status 1 (0 if | |
35 | .BR \-\-oknodo | |
36 | is specified). | |
37 | If such a process does not exist, it starts an | |
38 | instance, using either the executable specified by | |
39 | .BR \-\-exec , | |
40 | (or, if specified, by | |
41 | .BR \-\-startas ). | |
42 | Any arguments given after | |
43 | .BR \-\- | |
44 | on the command line are passed unmodified to the program being | |
45 | started. | |
46 | ||
47 | With | |
48 | .BR \-\-stop , | |
49 | .B start\-stop\-daemon | |
50 | also checks for the existence of a specified process. | |
51 | If such a process exists, | |
52 | .B start\-stop\-daemon | |
53 | sends it the signal specified by | |
54 | .BR \-\-signal , | |
55 | and exits with error status 0. | |
56 | If such a process does not exist, | |
57 | .B start\-stop\-daemon | |
58 | exits with error status 1 | |
59 | (0 if | |
60 | .BR \-\-oknodo | |
61 | is specified). If | |
62 | .B \-\-retry | |
63 | is specified then | |
64 | .B start\-stop\-daemon | |
65 | will check that the process(es) have terminated. | |
66 | ||
67 | Note that unless | |
68 | .BR \-\-pidfile , | |
69 | is specified, then | |
70 | .B start\-stop\-daemon | |
71 | behaves similarly to | |
72 | .B killall(1). | |
73 | .B start\-stop\-daemon | |
74 | will scan the process table looking for any processes which | |
75 | match the process name, uid, and/or gid (if specified). Any | |
76 | matching process will prevent | |
77 | .BR \-\-start | |
78 | from starting the daemon. All matching processes will be | |
79 | sent the KILL signal if | |
80 | .BR \-\-stop | |
81 | is specified. For daemons which have long-lived children | |
82 | which need to live through a | |
83 | .BR \-\-stop | |
84 | you must specify a pidfile. | |
85 | ||
86 | .SH OPTIONS | |
87 | ||
88 | .TP | |
89 | \fB\-x\fP|\fB\-\-exec\fP \fIexecutable\fP | |
90 | Check for processes that are instances of this executable (according to | |
91 | .B /proc/\fIpid\fB/exe\fP | |
92 | ). | |
93 | .TP | |
94 | \fB\-p\fP|\fB\-\-pidfile\fP \fIpid-file\fP | |
95 | Check whether a process has created the file | |
96 | .IR pid-file . | |
97 | .TP | |
98 | \fB\-u\fP|\fB\-\-user\fP \fIusername\fP|\fIuid\fP | |
99 | Check for processes owned by the user specified by | |
100 | .I username | |
101 | or | |
102 | .IR uid . | |
103 | .TP | |
104 | \fB\-g\fP|\fB\-\-group\fP \fIgroup\fP|\fIgid\fP | |
105 | Change to \fIgroup\fP or \fIgid\fP when starting the process. | |
106 | .TP | |
107 | \fB\-n\fP|\fB\-\-name\fP \fIprocess-name\fP | |
108 | Check for processes with the name | |
109 | .I process-name | |
110 | (according to | |
111 | .BR /proc/\fIpid\fB/stat\fP ). | |
112 | .TP | |
113 | \fB\-s\fP|\fB\-\-signal\fP \fIsignal\fP | |
114 | With | |
115 | .BR \-\-stop , | |
116 | specifies the signal to send to processes being stopped (default 15). | |
117 | .TP | |
118 | \fB\-R\fP|\fB\-\-retry\fP \fItimeout\fP|\fIschedule\fP | |
119 | With | |
120 | .BR \-\-stop , | |
121 | specifies that | |
122 | .B start\-stop\-daemon | |
123 | is to check whether the process(es) | |
124 | do finish. It will check repeatedly whether any matching processes | |
125 | are running, until none are. If the processes do not exit it will | |
126 | then take further action as determined by the schedule. | |
127 | ||
128 | If | |
129 | .I timeout | |
130 | is specified instead of | |
131 | .I schedule | |
132 | then the schedule | |
133 | .IB signal / timeout /KILL/ timeout | |
134 | is used, where | |
135 | .I signal | |
136 | is the signal specified with | |
137 | .BR \-\-signal . | |
138 | ||
139 | .I schedule | |
140 | is a list of at least two items separated by slashes | |
141 | .RB ( / ); | |
142 | each item may be | |
143 | .BI \- signal-number | |
144 | or [\fB\-\fP]\fIsignal-name\fP, | |
145 | which means to send that signal, | |
146 | or | |
147 | .IR timeout , | |
148 | which means to wait that many seconds for processes to | |
149 | exit, | |
150 | or | |
151 | .BR forever , | |
152 | which means to repeat the rest of the schedule forever if | |
153 | necessary. | |
154 | ||
155 | If the end of the schedule is reached and | |
156 | .BR forever | |
157 | is not specified, then | |
158 | .B start\-stop\-daemon | |
159 | exits with error status 2. | |
160 | If a schedule is specified, then any signal specified | |
161 | with | |
162 | .B \-\-signal | |
163 | is ignored. | |
164 | .TP | |
165 | \fB\-a\fP|\fB\-\-startas\fP \fIpathname\fP | |
166 | With | |
167 | .BR \-\-start , | |
168 | start the process specified by | |
169 | .IR pathname . | |
170 | If not specified, defaults to the argument given to | |
171 | .BR \-\-exec . | |
172 | .TP | |
173 | .BR \-t | \-\-test | |
174 | Print actions that would be taken and set appropriate return value, | |
175 | but take no action. | |
176 | .TP | |
177 | .BR \-o | \-\-oknodo | |
178 | Return exit status 0 instead of 1 if no actions are (would be) taken. | |
179 | .TP | |
180 | .BR \-q | \-\-quiet | |
181 | Do not print informational messages; only display error messages. | |
182 | .TP | |
183 | \fB\-c\fP|\fB\-\-chuid\fP \fIusername\fR|\fIuid\fP | |
184 | Change to this username/uid before starting the process. You can also | |
185 | specify a group by appending a | |
186 | .BR : , | |
187 | then the group or gid in the same way | |
188 | as you would for the `chown' command (\fIuser\fP\fB:\fP\fIgroup\fP). | |
189 | When using this option | |
190 | you must realize that the primary and supplemental groups are set as well, | |
191 | even if the | |
192 | .B \-\-group | |
193 | option is not specified. The | |
194 | .B \-\-group | |
195 | option is only for | |
196 | groups that the user isn't normally a member of (like adding per/process | |
197 | group membership for generic users like | |
198 | .BR nobody ). | |
199 | .TP | |
200 | \fB\-r\fP|\fB\-\-chroot\fP \fIroot\fP | |
201 | Chdir and chroot to | |
202 | .I root | |
203 | before starting the process. Please note that the pidfile is also written | |
204 | after the chroot. | |
205 | .TP | |
69bdc5ba JK |
206 | .BR \-D ", " \-\-dropcap " \fIcapabilities1,capabilities2\fP" |
207 | Drop theses capabilities separated by commas. | |
208 | .TP | |
8bff25f4 ER |
209 | \fB\-d\fP|\fB\-\-chdir\fP \fIpath\fP |
210 | Chdir to | |
211 | .I path | |
212 | before starting the process. This is done after the chroot if the | |
213 | \fB\-r\fP|\fB\-\-chroot\fP option is set. When not specified, | |
214 | start\-stop\-daemon will chdir to the root directory before starting | |
215 | the process. | |
216 | .TP | |
217 | .BR \-b | \-\-background | |
218 | Typically used with programs that don't detach on their own. This option | |
219 | will force | |
220 | .B start\-stop\-daemon | |
221 | to fork before starting the process, and force it into the background. | |
222 | .B WARNING: start\-stop\-daemon | |
223 | cannot check the exit status if the process fails to execute for | |
224 | .B any | |
225 | reason. This is a last resort, and is only meant for programs that either | |
226 | make no sense forking on their own, or where it's not feasible to add the | |
227 | code for it to do this itself. | |
228 | .TP | |
229 | \fB\-N\fP|\fB\-\-nicelevel\fP \fIint\fP | |
230 | This alters the prority of the process before starting it. | |
231 | .TP | |
232 | .BR \-m | \-\-make\-pidfile | |
233 | Used when starting a program that does not create its own pid file. This | |
234 | option will make | |
235 | .B start\-stop\-daemon | |
236 | create the file referenced with | |
237 | .B \-\-pidfile | |
238 | and place the pid into it just before executing the process. Note, it will | |
239 | not be removed when stopping the program. | |
240 | .B NOTE: | |
241 | This feature may not work in all cases. Most notably when the program | |
242 | being executed forks from its main process. Because of this it is usually | |
243 | only useful when combined with the | |
244 | .B \-\-background | |
245 | option. | |
246 | .TP | |
247 | .BR \-v | \-\-verbose | |
248 | Print verbose informational messages. | |
249 | .TP | |
250 | .BR \-H | \-\-help | |
251 | Print help information; then exit. | |
252 | .TP | |
253 | .BR \-V | \-\-version | |
254 | Print version information; then exit. | |
255 | ||
256 | .SH AUTHORS | |
257 | Marek Michalkiewicz <marekm@i17linuxb.ists.pwr.wroc.pl> based on | |
258 | a previous version by Ian Jackson <ian@chiark.greenend.org.uk>. | |
259 | ||
260 | Manual page by Klee Dienes <klee@mit.edu>, partially reformatted | |
261 | by Ian Jackson. |