diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
commit | b86570f63e533abcbcb97c2572e0e5732a96307b (patch) | |
tree | cabc83be691530ae685c45a8bc7620ccc0e1ebdf /man/start-stop-daemon.pod | |
parent | Initial commit. (diff) | |
download | dpkg-upstream.tar.xz dpkg-upstream.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | man/start-stop-daemon.pod | 509 |
1 files changed, 509 insertions, 0 deletions
diff --git a/man/start-stop-daemon.pod b/man/start-stop-daemon.pod new file mode 100644 index 0000000..499e945 --- /dev/null +++ b/man/start-stop-daemon.pod @@ -0,0 +1,509 @@ +# dpkg manual page - start-stop-daemon(8) +# +# Copyright © 1999 Klee Dienes <klee@mit.edu> +# Copyright © 1999 Ben Collins <bcollins@debian.org> +# Copyright © 2000-2001 Wichert Akkerman <wakkerma@debian.org> +# Copyright © 2002-2003 Adam Heath <doogie@debian.org> +# Copyright © 2004 Scott James Remnant <keybuk@debian.org> +# Copyright © 2008-2016, 2018 Guillem Jover <guillem@debian.org> +# +# This is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <https://www.gnu.org/licenses/>. + +=encoding utf8 + +=head1 NAME + +start-stop-daemon - start and stop system daemon programs + +=head1 SYNOPSIS + +B<start-stop-daemon> +[I<option>...] I<command> + +=head1 DESCRIPTION + +B<start-stop-daemon> +is used to control the creation and termination of system-level processes. +Using one of the matching options, B<start-stop-daemon> +can be configured to find existing instances of a running process. + +B<Note:> Unless +B<--pid> +or +B<--pidfile> +are specified, +B<start-stop-daemon> +behaves similar to +B<killall>(1). +B<start-stop-daemon> +will scan the process table looking for any processes which +match the process name, parent pid, uid, and/or gid (if specified). Any +matching process will prevent +B<--start> +from starting the daemon. All matching processes will be sent the TERM +signal (or the one specified via B<--signal> or B<--retry>) if +B<--stop> +is specified. For daemons which have long-lived children +which need to live through a +B<--stop>, +you must specify a pidfile. + +=head1 COMMANDS + +=over + +=item B<-S>, B<--start> [B<-->] I<arguments> + +Check for the existence of a specified process. +If such a process exists, +B<start-stop-daemon> +does nothing, and exits with error status 1 (0 if +B<--oknodo> +is specified). +If such a process does not exist, it starts an +instance, using either the executable specified by +B<--exec> +or, if specified, by +B<--startas>. +Any arguments given after +B<--> +on the command line are passed unmodified to the program being +started. + +=item B<-K>, B<--stop> + +Checks for the existence of a specified process. +If such a process exists, +B<start-stop-daemon> +sends it the signal specified by +B<--signal>, +and exits with error status 0. +If such a process does not exist, +B<start-stop-daemon> +exits with error status 1 +(0 if +B<--oknodo> +is specified). If +B<--retry> +is specified, then +B<start-stop-daemon> +will check that the process(es) have terminated. + +=item B<-T>, B<--status> + +Check for the existence of a specified process, and returns an exit status +code, according to the LSB Init Script Actions (since version 1.16.1). + +=item B<-H>, B<--help> + +Show usage information and exit. + +=item B<-V>, B<--version> + +Show the program version and exit. + +=back + +=head1 OPTIONS + +=head2 Matching options + +=over + +=item B<--pid> I<pid> + +Check for a process with the specified I<pid> (since version 1.17.6). +The I<pid> must be a number greater than 0. + +=item B<--ppid> I<ppid> + +Check for a process with the specified parent pid I<ppid> +(since version 1.17.7). +The I<ppid> must be a number greater than 0. + +=item B<-p>, B<--pidfile> I<pidfile> + +Check whether a process has created the file I<pidfile>. + +B<Note:> Using this matching option alone might cause unintended processes to +be acted on, if the old process terminated without being able to remove the +I<pidfile>. + +B<Warning:> Using this match option with a world-writable pidfile or using +it alone with a daemon that writes the pidfile as an unprivileged (non-root) +user will be refused with an error (since version 1.19.3) as this is a +security risk, because either any user can write to it, or if the daemon +gets compromised, the contents of the pidfile cannot be trusted, and then +a privileged runner (such as an init script executed as root) would end up +acting on any system process. +Using I</dev/null> is exempt from these checks. + +=item B<-x>, B<--exec> I<executable> + +Check for processes that are instances of this I<executable>. The +I<executable> argument should be an absolute pathname. + +B<Note:> This might +not work as intended with interpreted scripts, as the executable will point +to the interpreter. Take into account processes running from inside a chroot +will also be matched, so other match restrictions might be needed. + +=item B<-n>, B<--name> I<process-name> + +Check for processes with the name I<process-name>. The I<process-name> +is usually the process filename, but it could have been changed by the +process itself. + +B<Note:> On most systems this information is retrieved from +the process comm name from the kernel, which tends to have a relatively +short length limit (assuming more than 15 characters is non-portable). + +=item B<-u>, B<--user> I<username>|I<uid> + +Check for processes owned by the user specified by I<username> or +I<uid>. + +B<Note:> Using this matching option alone will cause all processes +matching the user to be acted on. + +=back + +=head2 Generic options + +=over + +=item B<-g>, B<--group> I<group>|I<gid> + +Change to I<group> or I<gid> when starting the process. + +=item B<-s>, B<--signal> I<signal> + +With +B<--stop>, +specifies the signal to send to processes being stopped (default TERM). + +=item B<-R>, B<--retry> I<timeout>|I<schedule> + +With +B<--stop>, +specifies that +B<start-stop-daemon> +is to check whether the process(es) +do finish. It will check repeatedly whether any matching processes +are running, until none are. If the processes do not exit it will +then take further action as determined by the schedule. + +If +I<timeout> +is specified instead of +I<schedule>, +then the schedule +I<signal>B</>I<timeout>B</KILL/>I<timeout> +is used, where +I<signal> +is the signal specified with +B<--signal>. + +I<schedule> +is a list of at least two items separated by slashes +(B</>); +each item may be +B<->I<signal-number> +or [B<->]I<signal-name>, +which means to send that signal, +or +I<timeout>, +which means to wait that many seconds for processes to +exit, +or +B<forever>, +which means to repeat the rest of the schedule forever if +necessary. + +If the end of the schedule is reached and +B<forever> +is not specified, then +B<start-stop-daemon> +exits with error status 2. +If a schedule is specified, then any signal specified +with +B<--signal> +is ignored. + +=item B<-a>, B<--startas> I<pathname> + +With +B<--start>, +start the process specified by +I<pathname>. +If not specified, defaults to the argument given to +B<--exec>. + +=item B<-t>, B<--test> + +Print actions that would be taken and set appropriate return value, +but take no action. + +=item B<-o>, B<--oknodo> + +Return exit status 0 instead of 1 if no actions are (would be) taken. + +=item B<-q>, B<--quiet> + +Do not print informational messages; only display error messages. + +=item B<-c>, B<--chuid> I<username>|I<uid>[B<:>I<group>|I<gid>] + +Change to this username/uid before starting the process. You can also +specify a group by appending a +B<:>, +then the group or gid in the same way +as you would for the B<chown>(1) command (I<user>B<:>I<group>). +If a user is specified without a group, the primary GID for that user is used. +When using this option +you must realize that the primary and supplemental groups are set as well, +even if the +B<--group> +option is not specified. The +B<--group> +option is only for +groups that the user isn't normally a member of (like adding per process +group membership for generic users like +B<nobody>). + +=item B<-r>, B<--chroot> I<root> + +Change directory and chroot to +I<root> +before starting the process. Please note that the pidfile is also written +after the chroot. + +=item B<-d>, B<--chdir> I<path> + +Change directory to +I<path> +before starting the process. This is done after the chroot if the +B<-r>|B<--chroot> option is set. When not specified, +B<start-stop-daemon> +will change directory to the root directory before starting the process. + +=item B<-b>, B<--background> + +Typically used with programs that don't detach on their own. This option +will force +B<start-stop-daemon> +to fork before starting the process, and force it into the background. + +B<Warning: start-stop-daemon> +cannot check the exit status if the process fails to execute for +B<any> +reason. This is a last resort, and is only meant for programs that either +make no sense forking on their own, or where it's not feasible to add the +code for them to do this themselves. + +=item B<--notify-await> + +Wait for the background process to send a readiness notification before +considering the service started (since version 1.19.3). +This implements parts of the systemd readiness protocol, as specified +in the B<sd_notify>(3) man page. +The following variables are supported: + +=over + +=item B<READY=1> + +The program is ready to give service, so we can exit safely. + +=item B<EXTEND_TIMEOUT_USEC=>I<number> + +The program requests to extend the timeout by I<number> microseconds. +This will reset the current timeout to the specified value. + +=item B<ERRNO=>I<number> + +The program is exiting with an error. +Do the same and print the user-friendly string for the B<errno> value. + +=back + +=item B<--notify-timeout> I<timeout> + +Set a timeout for the B<--notify-await> option (since version 1.19.3). +When the timeout is reached, B<start-stop-daemon> will exit with an +error code, and no readiness notification will be awaited. +The default is B<60> seconds. + +=item B<-C>, B<--no-close> + +Do not close any file descriptor when forcing the daemon into the background +(since version 1.16.5). +Used for debugging purposes to see the process output, or to redirect file +descriptors to log the process output. +Only relevant when using B<--background>. + +=item B<-O>, B<--output> I<pathname> + +Redirect B<stdout> and B<stderr> to I<pathname> when forcing the daemon into +the background (since version 1.20.6). +Only relevant when using B<--background>. + +=item B<-N>, B<--nicelevel> I<int> + +This alters the priority of the process before starting it. + +=item B<-P>, B<--procsched> I<policy>B<:>I<priority> + +This alters the process scheduler policy and priority of the process before +starting it (since version 1.15.0). +The priority can be optionally specified by appending a B<:> +followed by the value. The default I<priority> is 0. The currently +supported policy values are B<other>, B<fifo> and B<rr>. + +=item B<-I>, B<--iosched> I<class>B<:>I<priority> + +This alters the IO scheduler class and priority of the process before starting +it (since version 1.15.0). +The priority can be optionally specified by appending a B<:> followed +by the value. The default I<priority> is 4, unless I<class> is B<idle>, +then I<priority> will always be 7. The currently supported values for +I<class> are B<idle>, B<best-effort> and B<real-time>. + +=item B<-k>, B<--umask> I<mask> + +This sets the umask of the process before starting it (since version 1.13.22). + +=item B<-m>, B<--make-pidfile> + +Used when starting a program that does not create its own pid file. This +option will make +B<start-stop-daemon> +create the file referenced with +B<--pidfile> +and place the pid into it just before executing the process. Note, the +file will only be removed when stopping the program if +B<--remove-pidfile> is used. + +B<Note:> +This feature may not work in all cases. Most notably when the program +being executed forks from its main process. Because of this, it is usually +only useful when combined with the +B<--background> +option. + +=item B<--remove-pidfile> + +Used when stopping a program that does not remove its own pid file +(since version 1.17.19). +This option will make +B<start-stop-daemon> +remove the file referenced with +B<--pidfile> +after terminating the process. + +=item B<-v>, B<--verbose> + +Print verbose informational messages. + +=back + +=head1 EXIT STATUS + +=over + +=item B<0> + +The requested action was performed. If +B<--oknodo> +was specified, it's also possible that nothing had to be done. +This can happen when +B<--start> +was specified and a matching process was already running, or when +B<--stop> +was specified and there were no matching processes. + +=item B<1> + +If +B<--oknodo> +was not specified and nothing was done. + +=item B<2> + +If +B<--stop> +and +B<--retry> +were specified, but the end of the schedule was reached and the processes were +still running. + +=item B<3> + +Any other error. + +=back + +When using the B<--status> command, the following status codes are +returned: + +=over + +=item B<0> + +Program is running. + +=item B<1> + +Program is not running and the pid file exists. + +=item B<3> + +Program is not running. + +=item B<4> + +Unable to determine program status. + +=back + +=head1 EXAMPLE + +Start the B<food> daemon, unless one is already running (a process named +food, running as user food, with pid in food.pid): + +=over + + start-stop-daemon --start --oknodo --user food --name food \ + --pidfile /run/food.pid --startas /usr/sbin/food \ + --chuid food -- --daemon + +=back + +Send B<SIGTERM> to B<food> and wait up to 5 seconds for it to stop: + +=over + + start-stop-daemon --stop --oknodo --user food --name food \ + --pidfile /run/food.pid --retry 5 + +=back + +Demonstration of a custom schedule for stopping B<food>: + +=over + + start-stop-daemon --stop --oknodo --user food --name food \ + --pidfile /run/food.pid --retry=TERM/30/KILL/5 + +=back |