Adding upstream version 1.22.4.upstream/1.22.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 538 insertions, 0 deletions

diff --git a/man/start-stop-daemon.pod b/man/start-stop-daemon.pod
new file mode 100644
index 0000000..9bd6097
--- /dev/null
+++ b/man/start-stop-daemon.pod
@@ -0,0 +1,538 @@
+# 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
+L<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 L<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>: B<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 L<sd_notify(3)> manual 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>.
+
+This option might do nothing on some systems,
+where POSIX process scheduling is not supported.
+
+=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>.
+
+This option might do nothing on some systems,
+where Linux IO scheduling is not supported.
+
+=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 %RUNSTATEDIR%/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 %RUNSTATEDIR%/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 %RUNSTATEDIR%/food.pid --retry=TERM/30/KILL/5
+
+=back