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,
14       start-stop-daemon  can  be  configured  to find existing instances of a
15       running 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
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
36       -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
45       -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
50       -H, --help
51              Show usage information and exit.
52
53       -V, --version
54              Show the program version and exit.
55

OPTIONS

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
62       --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
66       -p, --pidfile pid-file
67              Check whether a process has created the file pid-file.
68
69              Note:  using  this  matching option alone might cause unintended
70              processes to be acted on, if the old process terminated  without
71              being able to remove the pid-file.
72
73              Warning:  using  this match option with a world-writable pidfile
74              or using it alone with a daemon that writes the  pidfile  as  an
75              unprivileged  (non-root)  user  will  be  refused  with an error
76              (since version 1.19.3) as  this  is  a  security  risk,  because
77              either  any  user  can  write  to  it,  or  if  the  daemon gets
78              compromised, the contents of the pidfile cannot be trusted,  and
79              then  a  privileged  runner  (such as an init script executed as
80              root)  would  end  up  acting  on  any  system  process.   Using
81              /dev/null is exempt from these checks.
82
83       -x, --exec executable
84              Check  for  processes that are instances of this executable. The
85              executable argument should be an absolute pathname.  Note:  this
86              might  not  work  as  intended  with interpreted scripts, as the
87              executable will point to  the  interpreter.  Take  into  account
88              processes  running from inside a chroot will also be matched, so
89              other match restrictions might be needed.
90
91       -n, --name process-name
92              Check for processes with the name process-name. The process-name
93              is  usually the process filename, but it could have been changed
94              by the process itself. Note: on most systems this information is
95              retrieved  from  the  process  comm  name from the kernel, which
96              tends to have a relatively short  length  limit  (assuming  more
97              than 15 characters is non-portable).
98
99       -u, --user username|uid
100              Check  for  processes owned by the user specified by username or
101              uid. Note: using this  matching  option  alone  will  cause  all
102              processes matching the user to be acted on.
103
104   Generic options
105       -g, --group group|gid
106              Change to group or gid when starting the process.
107
108       -s, --signal signal
109              With  --stop,  specifies  the  signal to send to processes being
110              stopped (default TERM).
111
112       -R, --retry timeout|schedule
113              With  --stop,  specifies  that  start-stop-daemon  is  to  check
114              whether  the  process(es)  do  finish.  It will check repeatedly
115              whether any matching processes are running, until none  are.  If
116              the  processes  do  not exit it will then take further action as
117              determined by the schedule.
118
119              If timeout is specified instead of schedule, then  the  schedule
120              signal/timeout/KILL/timeout  is used, where signal is the signal
121              specified with --signal.
122
123              schedule is a list of at least two items  separated  by  slashes
124              (/);  each  item  may be -signal-number or [-]signal-name, which
125              means to send that signal, or timeout, which means to wait  that
126              many  seconds  for processes to exit, or forever, which means to
127              repeat the rest of the schedule forever if necessary.
128
129              If the end of  the  schedule  is  reached  and  forever  is  not
130              specified, then start-stop-daemon exits with error status 2.  If
131              a schedule is specified, then any signal specified with --signal
132              is ignored.
133
134       -a, --startas pathname
135              With  --start,  start the process specified by pathname.  If not
136              specified, defaults to the argument given to --exec.
137
138       -t, --test
139              Print actions that would be taken  and  set  appropriate  return
140              value, but take no action.
141
142       -o, --oknodo
143              Return  exit  status 0 instead of 1 if no actions are (would be)
144              taken.
145
146       -q, --quiet
147              Do  not  print  informational  messages;  only   display   error
148              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
153              the same way as you would for the chown(1) command (user:group).
154              If a user is specified without a group, the primary GID for that
155              user  is used.  When using this option you must realize that the
156              primary and supplemental groups are set as  well,  even  if  the
157              --group  option is not specified. The --group option is only for
158              groups that the user isn't normally a member of (like adding per
159              process group membership for generic users like nobody).
160
161       -r, --chroot root
162              Chdir  and  chroot  to  root before starting the process. Please
163              note that the pidfile is also written after the chroot.
164
165       -d, --chdir path
166              Chdir to path before starting the process. This  is  done  after
167              the chroot if the -r|--chroot option is set. When not specified,
168              start-stop-daemon  will  chdir  to  the  root  directory  before
169              starting the process.
170
171       -b, --background
172              Typically  used  with  programs  that don't detach on their own.
173              This option will force start-stop-daemon to fork before starting
174              the  process,  and  force  it  into  the  background.   Warning:
175              start-stop-daemon cannot check the exit status  if  the  process
176              fails  to  execute for any reason. This is a last resort, and is
177              only meant for programs that either make  no  sense  forking  on
178              their  own,  or where it's not feasible to add the code for them
179              to do this themselves.
180
181       --notify-await
182              Wait for the background process to send a readiness notification
183              before  considering  the service started (since version 1.19.3).
184              This implements parts of  the  systemd  readiness  protocol,  as
185              specified in the sd_notify(3) man page.  The following variables
186              are supported:
187
188              READY=1
189                     The program is ready to give  service,  so  we  can  exit
190                     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
199                     print the user-friendly string for the errno value.
200
201       --notify-timeouttimeout
202              Set a timeout  for  the  --notify-await  option  (since  version
203              1.19.3).   When  the  timeout is reached, start-stop-daemon will
204              exit with an error code, and no readiness notification  will  be
205              awaited.  The default is 60 seconds.
206
207       -C, --no-close
208              Do  not  close  any file descriptor when forcing the daemon into
209              the background  (since  version  1.16.5).   Used  for  debugging
210              purposes  to  see  the  process  output,  or  to  redirect  file
211              descriptors to log the process output.  Only relevant when using
212              --background.
213
214       -N, --nicelevel int
215              This alters the priority of the process before starting it.
216
217       -P, --procsched policy:priority
218              This  alters  the  process  scheduler policy and priority of the
219              process before starting it (since version 1.15.0).  The priority
220              can  be  optionally  specified  by appending a : followed by the
221              value. The default priority is 0. The currently supported policy
222              values are other, fifo and rr.
223
224       -I, --iosched class:priority
225              This  alters  the IO scheduler class and priority of the process
226              before starting it (since version 1.15.0).  The priority can  be
227              optionally specified by appending a : followed by the value. The
228              default priority is 4, unless class is idle, then priority  will
229              always  be 7. The currently supported values for class are idle,
230              best-effort and real-time.
231
232       -k, --umask mask
233              This sets the umask of the process  before  starting  it  (since
234              version 1.13.22).
235
236       -m, --make-pidfile
237              Used  when  starting  a program that does not create its own pid
238              file. This option will make start-stop-daemon  create  the  file
239              referenced  with --pidfile and place the pid into it just before
240              executing the process. Note, the file will only be removed  when
241              stopping  the  program  if --remove-pidfile is used.  Note: This
242              feature may not work in all cases. Most notably when the program
243              being  executed forks from its main process. Because of this, it
244              is usually only  useful  when  combined  with  the  --background
245              option.
246
247       --remove-pidfile
248              Used  when  stopping  a program that does not remove its own pid
249              file  (since  version   1.17.19).    This   option   will   make
250              start-stop-daemon  remove  the  file  referenced  with --pidfile
251              after terminating the process.
252
253       -v, --verbose
254              Print verbose informational messages.
255

EXIT STATUS

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

EXAMPLE

282       Start the food daemon, unless one is already running (a  process  named
283       food, running as user food, with pid in food.pid):
284
285              start-stop-daemon --start --oknodo --user food --name food \
286                   --pidfile /run/food.pid --startas /usr/sbin/food \
287                   --chuid food -- --daemon
288
289       Send SIGTERM to food and wait up to 5 seconds for it to stop:
290
291              start-stop-daemon --stop --oknodo --user food --name food \
292                   --pidfile /run/food.pid --retry 5
293
294       Demonstration of a custom schedule for stopping food:
295
296              start-stop-daemon --stop --oknodo --user food --name food \
297                   --pidfile /run/food.pid --retry=TERM/30/KILL/5
298
299
300
3011.19.7                            2019-06-03              start-stop-daemon(8)
Impressum