1start-stop-daemon(8) dpkg suite start-stop-daemon(8)
2
6 start-stop-daemon - start and stop system daemon programs
7
9 start-stop-daemon [option...] command
10
12 start-stop-daemon is used to control the creation and termination of
13 system-level processes. Using one of the matching options, start-stop-
14 daemon can be configured to find existing instances of a running
15 process.
16 Note: Unless --pid or --pidfile are specified, start-stop-daemon
18 behaves similar to killall(1). start-stop-daemon will scan the process
19 table looking for any processes which match the process name, parent
20 pid, uid, and/or gid (if specified). Any matching process will prevent
21 --start from starting the daemon. All matching processes will be sent
22 the TERM signal (or the one specified via --signal or --retry) if
23 --stop is specified. For daemons which have long-lived children which
24 need to live through a --stop, you must specify a pidfile.
25
27 -S, --start [--] arguments
28 Check for the existence of a specified process. If such a process
29 exists, start-stop-daemon does nothing, and exits with error status
30 1 (0 if --oknodo is specified). If such a process does not exist,
31 it starts an instance, using either the executable specified by
32 --exec or, if specified, by --startas. Any arguments given after
33 -- on the command line are passed unmodified to the program being
34 started.
35 -K, --stop
37 Checks for the existence of a specified process. If such a process
38 exists, start-stop-daemon sends it the signal specified by
39 --signal, and exits with error status 0. If such a process does
40 not exist, start-stop-daemon exits with error status 1 (0 if
41 --oknodo is specified). If --retry is specified, then start-stop-
42 daemon will check that the process(es) have terminated.
43 -T, --status
45 Check for the existence of a specified process, and returns an exit
46 status code, according to the LSB Init Script Actions (since
47 version 1.16.1).
48 -H, --help
50 Show usage information and exit.
51 -V, --version
53 Show the program version and exit.
54
56 Matching options
57 --pid pid
58 Check for a process with the specified pid (since version 1.17.6).
59 The pid must be a number greater than 0.
60 --ppid ppid
62 Check for a process with the specified parent pid ppid (since
63 version 1.17.7). The ppid must be a number greater than 0.
64 -p, --pidfile pidfile
66 Check whether a process has created the file pidfile.
67 Note: Using this matching option alone might cause unintended
69 processes to be acted on, if the old process terminated without
70 being able to remove the pidfile.
71 Warning: Using this match option with a world-writable pidfile or
73 using it alone with a daemon that writes the pidfile as an
74 unprivileged (non-root) user will be refused with an error (since
75 version 1.19.3) as this is a security risk, because either any user
76 can write to it, or if the daemon gets compromised, the contents of
77 the pidfile cannot be trusted, and then a privileged runner (such
78 as an init script executed as root) would end up acting on any
79 system process. Using /dev/null is exempt from these checks.
80 -x, --exec executable
82 Check for processes that are instances of this executable. The
83 executable argument should be an absolute pathname.
84 Note: This might not work as intended with interpreted scripts, as
86 the executable will point to the interpreter. Take into account
87 processes running from inside a chroot will also be matched, so
88 other match restrictions might be needed.
89 -n, --name process-name
91 Check for processes with the name process-name. The process-name is
92 usually the process filename, but it could have been changed by the
93 process itself.
94 Note: On most systems this information is retrieved from the
96 process comm name from the kernel, which tends to have a relatively
97 short length limit (assuming more than 15 characters is non-
98 portable).
99 -u, --user username|uid
101 Check for processes owned by the user specified by username or uid.
102 Note: Using this matching option alone will cause all processes
104 matching the user to be acted on.
105 Generic options
107 -g, --group group|gid
108 Change to group or gid when starting the process.
109 -s, --signal signal
111 With --stop, specifies the signal to send to processes being
112 stopped (default TERM).
113 -R, --retry timeout|schedule
115 With --stop, specifies that start-stop-daemon is to check whether
116 the process(es) do finish. It will check repeatedly whether any
117 matching processes are running, until none are. If the processes do
118 not exit it will then take further action as determined by the
119 schedule.
120 If timeout is specified instead of schedule, then the schedule
122 signal/timeout/KILL/timeout is used, where signal is the signal
123 specified with --signal.
124 schedule is a list of at least two items separated by slashes (/);
126 each item may be -signal-number or [-]signal-name, which means to
127 send that signal, or timeout, which means to wait that many seconds
128 for processes to exit, or forever, which means to repeat the rest
129 of the schedule forever if necessary.
130 If the end of the schedule is reached and forever is not specified,
132 then start-stop-daemon exits with error status 2. If a schedule is
133 specified, then any signal specified with --signal is ignored.
134 -a, --startas pathname
136 With --start, start the process specified by pathname. If not
137 specified, defaults to the argument given to --exec.
138 -t, --test
140 Print actions that would be taken and set appropriate return value,
141 but take no action.
142 -o, --oknodo
144 Return exit status 0 instead of 1 if no actions are (would be)
145 taken.
146 -q, --quiet
148 Do not print informational messages; only display error messages.
149 -c, --chuid username|uid[:group|gid]
151 Change to this username/uid before starting the process. You can
152 also specify a group by appending a :, then the group or gid in the
153 same way as you would for the chown(1) command (user:group). If a
154 user is specified without a group, the primary GID for that user is
155 used. When using this option you must realize that the primary and
156 supplemental groups are set as well, even if the --group option is
157 not specified. The --group option is only for groups that the user
158 isn't normally a member of (like adding per process group
159 membership for generic users like nobody).
160 -r, --chroot root
162 Change directory and chroot to root before starting the process.
163 Please note that the pidfile is also written after the chroot.
164 -d, --chdir path
166 Change directory to path before starting the process. This is done
167 after the chroot if the -r|--chroot option is set. When not
168 specified, start-stop-daemon will change directory to the root
169 directory before starting the process.
170 -b, --background
172 Typically used with programs that don't detach on their own. This
173 option will force start-stop-daemon to fork before starting the
174 process, and force it into the background.
175 Warning: start-stop-daemon cannot check the exit status if the
177 process fails to execute for any reason. This is a last resort, and
178 is only meant for programs that either make no sense forking on
179 their own, or where it's not feasible to add the code for them to
180 do this themselves.
181 --notify-await
183 Wait for the background process to send a readiness notification
184 before considering the service started (since version 1.19.3).
185 This implements parts of the systemd readiness protocol, as
186 specified in the sd_notify(3) man page. The following variables
187 are supported:
188 READY=1
190 The program is ready to give service, so we can exit safely.
191 EXTEND_TIMEOUT_USEC=number
193 The program requests to extend the timeout by number
194 microseconds. This will reset the current timeout to the
195 specified value.
196 ERRNO=number
198 The program is exiting with an error. Do the same and print
199 the user-friendly string for the errno value.
200 --notify-timeout timeout
202 Set a timeout for the --notify-await option (since version 1.19.3).
203 When the timeout is reached, start-stop-daemon will exit with an
204 error code, and no readiness notification will be awaited. The
205 default is 60 seconds.
206 -C, --no-close
208 Do not close any file descriptor when forcing the daemon into the
209 background (since version 1.16.5). Used for debugging purposes to
210 see the process output, or to redirect file descriptors to log the
211 process output. Only relevant when using --background.
212 -O, --output pathname
214 Redirect stdout and stderr to pathname when forcing the daemon into
215 the background (since version 1.20.6). Only relevant when using
216 --background.
217 -N, --nicelevel int
219 This alters the priority of the process before starting it.
220 -P, --procsched policy:priority
222 This alters the process scheduler policy and priority of the
223 process before starting it (since version 1.15.0). The priority
224 can be optionally specified by appending a : followed by the value.
225 The default priority is 0. The currently supported policy values
226 are other, fifo and rr.
227 -I, --iosched class:priority
229 This alters the IO scheduler class and priority of the process
230 before starting it (since version 1.15.0). The priority can be
231 optionally specified by appending a : followed by the value. The
232 default priority is 4, unless class is idle, then priority will
233 always be 7. The currently supported values for class are idle,
234 best-effort and real-time.
235 -k, --umask mask
237 This sets the umask of the process before starting it (since
238 version 1.13.22).
239 -m, --make-pidfile
241 Used when starting a program that does not create its own pid file.
242 This option will make start-stop-daemon create the file referenced
243 with --pidfile and place the pid into it just before executing the
244 process. Note, the file will only be removed when stopping the
245 program if --remove-pidfile is used.
246 Note: This feature may not work in all cases. Most notably when the
248 program being executed forks from its main process. Because of
249 this, it is usually only useful when combined with the --background
250 option.
251 --remove-pidfile
253 Used when stopping a program that does not remove its own pid file
254 (since version 1.17.19). This option will make start-stop-daemon
255 remove the file referenced with --pidfile after terminating the
256 process.
257 -v, --verbose
259 Print verbose informational messages.
260
262 0 The requested action was performed. If --oknodo was specified, it's
263 also possible that nothing had to be done. This can happen when
264 --start was specified and a matching process was already running,
265 or when --stop was specified and there were no matching processes.
266 1 If --oknodo was not specified and nothing was done.
268 2 If --stop and --retry were specified, but the end of the schedule
270 was reached and the processes were still running.
271 3 Any other error.
273 When using the --status command, the following status codes are
275 returned:
276 0 Program is running.
278 1 Program is not running and the pid file exists.
280 3 Program is not running.
282 4 Unable to determine program status.
284
286 Start the food daemon, unless one is already running (a process named
287 food, running as user food, with pid in food.pid):
288 start-stop-daemon --start --oknodo --user food --name food \
290 --pidfile /run/food.pid --startas /usr/sbin/food \
291 --chuid food -- --daemon
292 Send SIGTERM to food and wait up to 5 seconds for it to stop:
294 start-stop-daemon --stop --oknodo --user food --name food \
296 --pidfile /run/food.pid --retry 5
297 Demonstration of a custom schedule for stopping food:
299 start-stop-daemon --stop --oknodo --user food --name food \
301 --pidfile /run/food.pid --retry=TERM/30/KILL/5
3021.21.9 2022-07-01 start-stop-daemon(8)