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,
14 start-stop-daemon can be configured to find existing instances of a
15 running 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
29 process exists, start-stop-daemon does nothing, and exits with
30 error status 1 (0 if --oknodo is specified). If such a process
31 does not exist, it starts an instance, using either the
32 executable specified by --exec or, if specified, by --startas.
33 Any arguments given after -- on the command line are passed
34 unmodified to the program being started.
35 -K, --stop
37 Checks for the existence of a specified process. If such a
38 process exists, start-stop-daemon sends it the signal specified
39 by --signal, and exits with error status 0. If such a process
40 does not exist, start-stop-daemon exits with error status 1 (0
41 if --oknodo is specified). If --retry is specified, then
42 start-stop-daemon will check that the process(es) have
43 terminated.
44 -T, --status
46 Check for the existence of a specified process, and returns an
47 exit status code, according to the LSB Init Script Actions
48 (since version 1.16.1).
49 -H, --help
51 Show usage information and exit.
52 -V, --version
54 Show the program version and exit.
55
57 Matching options
58 --pid pid
59 Check for a process with the specified pid (since version
60 1.17.6). The pid must be a number greater than 0.
61 --ppid ppid
63 Check for a process with the specified parent pid ppid (since
64 version 1.17.7). The ppid must be a number greater than 0.
65 -p, --pidfile pid-file
67 Check whether a process has created the file pid-file. Note:
68 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 pid-file.
71 -x, --exec executable
73 Check for processes that are instances of this executable. The
74 executable argument should be an absolute pathname. Note: this
75 might not work as intended with interpreted scripts, as the
76 executable will point to the interpreter. Take into account
77 processes running from inside a chroot will also be matched, so
78 other match restrictions might be needed.
79 -n, --name process-name
81 Check for processes with the name process-name. The process-name
82 is usually the process filename, but it could have been changed
83 by the process itself. Note: on most systems this information is
84 retrieved from the process comm name from the kernel, which
85 tends to have a relatively short length limit (assuming more
86 than 15 characters is non-portable).
87 -u, --user username|uid
89 Check for processes owned by the user specified by username or
90 uid. Note: using this matching option alone will cause all
91 processes matching the user to be acted on.
92 Generic options
94 -g, --group group|gid
95 Change to group or gid when starting the process.
96 -s, --signal signal
98 With --stop, specifies the signal to send to processes being
99 stopped (default TERM).
100 -R, --retry timeout|schedule
102 With --stop, specifies that start-stop-daemon is to check
103 whether the process(es) do finish. It will check repeatedly
104 whether any matching processes are running, until none are. If
105 the processes do not exit it will then take further action as
106 determined by the schedule.
107 If timeout is specified instead of schedule, then the schedule
109 signal/timeout/KILL/timeout is used, where signal is the signal
110 specified with --signal.
111 schedule is a list of at least two items separated by slashes
113 (/); each item may be -signal-number or [-]signal-name, which
114 means to send that signal, or timeout, which means to wait that
115 many seconds for processes to exit, or forever, which means to
116 repeat the rest of the schedule forever if necessary.
117 If the end of the schedule is reached and forever is not
119 specified, then start-stop-daemon exits with error status 2. If
120 a schedule is specified, then any signal specified with --signal
121 is ignored.
122 -a, --startas pathname
124 With --start, start the process specified by pathname. If not
125 specified, defaults to the argument given to --exec.
126 -t, --test
128 Print actions that would be taken and set appropriate return
129 value, but take no action.
130 -o, --oknodo
132 Return exit status 0 instead of 1 if no actions are (would be)
133 taken.
134 -q, --quiet
136 Do not print informational messages; only display error
137 messages.
138 -c, --chuid username|uid[:group|gid]
140 Change to this username/uid before starting the process. You can
141 also specify a group by appending a :, then the group or gid in
142 the same way as you would for the chown(1) command (user:group).
143 If a user is specified without a group, the primary GID for that
144 user is used. When using this option you must realize that the
145 primary and supplemental groups are set as well, even if the
146 --group option is not specified. The --group option is only for
147 groups that the user isn't normally a member of (like adding per
148 process group membership for generic users like nobody).
149 -r, --chroot root
151 Chdir and chroot to root before starting the process. Please
152 note that the pidfile is also written after the chroot.
153 -d, --chdir path
155 Chdir to path before starting the process. This is done after
156 the chroot if the -r|--chroot option is set. When not specified,
157 start-stop-daemon will chdir to the root directory before
158 starting the process.
159 -b, --background
161 Typically used with programs that don't detach on their own.
162 This option will force start-stop-daemon to fork before starting
163 the process, and force it into the background. Warning:
164 start-stop-daemon cannot check the exit status if the process
165 fails to execute for any reason. This is a last resort, and is
166 only meant for programs that either make no sense forking on
167 their own, or where it's not feasible to add the code for them
168 to do this themselves.
169 -C, --no-close
171 Do not close any file descriptor when forcing the daemon into
172 the background (since version 1.16.5). Used for debugging
173 purposes to see the process output, or to redirect file
174 descriptors to log the process output. Only relevant when using
175 --background.
176 -N, --nicelevel int
178 This alters the priority of the process before starting it.
179 -P, --procsched policy:priority
181 This alters the process scheduler policy and priority of the
182 process before starting it (since version 1.15.0). The priority
183 can be optionally specified by appending a : followed by the
184 value. The default priority is 0. The currently supported policy
185 values are other, fifo and rr.
186 -I, --iosched class:priority
188 This alters the IO scheduler class and priority of the process
189 before starting it (since version 1.15.0). The priority can be
190 optionally specified by appending a : followed by the value. The
191 default priority is 4, unless class is idle, then priority will
192 always be 7. The currently supported values for class are idle,
193 best-effort and real-time.
194 -k, --umask mask
196 This sets the umask of the process before starting it (since
197 version 1.13.22).
198 -m, --make-pidfile
200 Used when starting a program that does not create its own pid
201 file. This option will make start-stop-daemon create the file
202 referenced with --pidfile and place the pid into it just before
203 executing the process. Note, the file will only be removed when
204 stopping the program if --remove-pidfile is used. Note: This
205 feature may not work in all cases. Most notably when the program
206 being executed forks from its main process. Because of this, it
207 is usually only useful when combined with the --background
208 option.
209 --remove-pidfile
211 Used when stopping a program that does not remove its own pid
212 file (since version 1.17.19). This option will make
213 start-stop-daemon remove the file referenced with --pidfile
214 after terminating the process.
215 -v, --verbose
217 Print verbose informational messages.
218
220 0 The requested action was performed. If --oknodo was specified,
221 it's also possible that nothing had to be done. This can happen
222 when --start was specified and a matching process was already
223 running, or when --stop was specified and there were no matching
224 processes.
225 1 If --oknodo was not specified and nothing was done.
227 2 If --stop and --retry were specified, but the end of the
229 schedule was reached and the processes were still running.
230 3 Any other error.
232 When using the --status command, the following status codes are
234 returned:
235 0 Program is running.
237 1 Program is not running and the pid file exists.
239 3 Program is not running.
241 4 Unable to determine program status.
243
245 Start the food daemon, unless one is already running (a process named
246 food, running as user food, with pid in food.pid):
247 start-stop-daemon --start --oknodo --user food --name food \
249 --pidfile /run/food.pid --startas /usr/sbin/food \
250 --chuid food -- --daemon
251 Send SIGTERM to food and wait up to 5 seconds for it to stop:
253 start-stop-daemon --stop --oknodo --user food --name food \
255 --pidfile /run/food.pid --retry 5
256 Demonstration of a custom schedule for stopping food:
258 start-stop-daemon --stop --oknodo --user food --name food \
260 --pidfile /run/food.pid --retry=TERM/30/KILL/5
2611.18.25 2018-06-26 start-stop-daemon(8)