1start-stop-daemon(8)              dpkg suite              start-stop-daemon(8)
2
3
4

NAME

6       start-stop-daemon - start and stop system daemon programs
7

SYNOPSIS

9       start-stop-daemon [option...] command
10

DESCRIPTION

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
17       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

COMMANDS

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
36       -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
44       -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
49       -H, --help
50           Show usage information and exit.
51
52       -V, --version
53           Show the program version and exit.
54

OPTIONS

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
61       --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
65       -p, --pidfile pidfile
66           Check whether a process has created the file pidfile.
67
68           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
72           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
81       -x, --exec executable
82           Check for processes that are instances of this executable. The
83           executable argument should be an absolute pathname.
84
85           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
90       -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
95           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
100       -u, --user username|uid
101           Check for processes owned by the user specified by username or uid.
102
103           Note: Using this matching option alone will cause all processes
104           matching the user to be acted on.
105
106   Generic options
107       -g, --group group|gid
108           Change to group or gid when starting the process.
109
110       -s, --signal signal
111           With --stop, specifies the signal to send to processes being
112           stopped (default TERM).
113
114       -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
121           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
125           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
131           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
135       -a, --startas pathname
136           With --start, start the process specified by pathname.  If not
137           specified, defaults to the argument given to --exec.
138
139       -t, --test
140           Print actions that would be taken and set appropriate return value,
141           but take no action.
142
143       -o, --oknodo
144           Return exit status 0 instead of 1 if no actions are (would be)
145           taken.
146
147       -q, --quiet
148           Do not print informational messages; only display error messages.
149
150       -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
161       -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
165       -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
171       -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
176           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
182       --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
189           READY=1
190               The program is ready to give service, so we can exit safely.
191
192           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
197           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
201       --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
207       -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
213       -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
218       -N, --nicelevel int
219           This alters the priority of the process before starting it.
220
221       -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
228           This option might do nothing on some systems, where POSIX process
229           scheduling is not supported.
230
231       -I, --iosched class:priority
232           This alters the IO scheduler class and priority of the process
233           before starting it (since version 1.15.0).  The priority can be
234           optionally specified by appending a : followed by the value. The
235           default priority is 4, unless class is idle, then priority will
236           always be 7. The currently supported values for class are idle,
237           best-effort and real-time.
238
239           This option might do nothing on some systems, where Linux IO
240           scheduling is not supported.
241
242       -k, --umask mask
243           This sets the umask of the process before starting it (since
244           version 1.13.22).
245
246       -m, --make-pidfile
247           Used when starting a program that does not create its own pid file.
248           This option will make start-stop-daemon create the file referenced
249           with --pidfile and place the pid into it just before executing the
250           process. Note, the file will only be removed when stopping the
251           program if --remove-pidfile is used.
252
253           Note: This feature may not work in all cases. Most notably when the
254           program being executed forks from its main process. Because of
255           this, it is usually only useful when combined with the --background
256           option.
257
258       --remove-pidfile
259           Used when stopping a program that does not remove its own pid file
260           (since version 1.17.19).  This option will make start-stop-daemon
261           remove the file referenced with --pidfile after terminating the
262           process.
263
264       -v, --verbose
265           Print verbose informational messages.
266

EXIT STATUS

268       0   The requested action was performed. If --oknodo was specified, it's
269           also possible that nothing had to be done.  This can happen when
270           --start was specified and a matching process was already running,
271           or when --stop was specified and there were no matching processes.
272
273       1   If --oknodo was not specified and nothing was done.
274
275       2   If --stop and --retry were specified, but the end of the schedule
276           was reached and the processes were still running.
277
278       3   Any other error.
279
280       When using the --status command, the following status codes are
281       returned:
282
283       0   Program is running.
284
285       1   Program is not running and the pid file exists.
286
287       3   Program is not running.
288
289       4   Unable to determine program status.
290

EXAMPLE

292       Start the food daemon, unless one is already running (a process named
293       food, running as user food, with pid in food.pid):
294
295        start-stop-daemon --start --oknodo --user food --name food \
296          --pidfile /run/food.pid --startas /usr/sbin/food \
297          --chuid food -- --daemon
298
299       Send SIGTERM to food and wait up to 5 seconds for it to stop:
300
301        start-stop-daemon --stop --oknodo --user food --name food \
302          --pidfile /run/food.pid --retry 5
303
304       Demonstration of a custom schedule for stopping food:
305
306        start-stop-daemon --stop --oknodo --user food --name food \
307          --pidfile /run/food.pid --retry=TERM/30/KILL/5
308
309
310
3111.21.21                           2023-02-25              start-stop-daemon(8)
Impressum