diff options
Diffstat (limited to 'usr.sbin/daemon/daemon.8')
| -rw-r--r-- | usr.sbin/daemon/daemon.8 | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/usr.sbin/daemon/daemon.8 b/usr.sbin/daemon/daemon.8 new file mode 100644 index 000000000000..52fbc230ac77 --- /dev/null +++ b/usr.sbin/daemon/daemon.8 @@ -0,0 +1,288 @@ +.\" Copyright (c) 1999 Berkeley Software Design, Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Berkeley Software Design Inc's name may not be used to endorse or +.\" promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN INC BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 25, 2024 +.Dt DAEMON 8 +.Os +.Sh NAME +.Nm daemon +.Nd run detached from the controlling terminal +.Sh SYNOPSIS +.Nm +.Op Fl cfHrS +.Op Fl p Ar child_pidfile +.Op Fl P Ar supervisor_pidfile +.Op Fl t Ar title +.Op Fl u Ar user +.Op Fl m Ar output_mask +.Op Fl o Ar output_file +.Op Fl s Ar syslog_priority +.Op Fl T Ar syslog_tag +.Op Fl l Ar syslog_facility +.Op Fl R Ar restart_delay_seconds +.Op Fl C Ar restart_count +.Ar command arguments ... +.Sh DESCRIPTION +The +.Nm +utility detaches itself from the controlling terminal and +executes the program specified by its arguments. +Privileges may be lowered to the specified user. +The output of the daemonized process may be redirected to syslog and to a +log file. +.Pp +The options are as follows: +.Bl -tag -width indent +.It Fl C , Fl -restart-count Ar restart_count +Restart the process at most +.Ar restart_count +times. +When zero is specified, +.Nm +will exit. +The maximum restart count is +.Cm 128 . +This option is used together with option +.Fl -restart . +.It Fl c , Fl -change-dir +Change the current working directory to the root +.Pq Dq Pa / . +.It Fl f , Fl -close-fds +Redirect standard input, standard output and standard error to +.Pa /dev/null . +When this option is used together with any of the options related to file +or syslog output, the standard file descriptors are first redirected to +.Pa /dev/null , +then stdout and/or stderr is redirected to a file or to syslog as +specified by the other options. +.It Fl H , Fl -sighup +Close +.Pa output_file +and re-open it when signal +.Dv SIGHUP +is received, for interoperability with +.Xr newsyslog 8 +and similar log rotation / archival mechanisms. +If +.Fl -output-file +is not specified, this flag is ignored. +.It Fl l , Fl -syslog-facility Ar syslog_facility +These facilities are accepted: +.Cm auth , authpriv , console , cron , daemon , +.Cm ftp , kern , lpr , mail , news , ntp , security , +.Cm syslog , user , uucp , +and +local facilities from +.Cm local0 +to +.Cm local7 . +The default is +.Cm daemon . +.It Fl m , Fl -output-mask Ar output_mask +Redirect output from the child process stdout +.Pq Cm 1 , +stderr +.Pq Cm 2 , +or both +.Pq Cm 3 . +This value specifies what is sent to syslog and the log file. +The default is +.Cm 3 . +.It Fl o , Fl -output-file Ar output_file +Append output from the daemonized process to +.Pa output_file . +If the file does not exist, it is created with permissions 0600. +When this option is used together with options +.Fl -change-dir +and +.Fl -sighup +the absolute path needs to be provided to ensure +.Nm +can re-open the file after a +.Dv SIGHUP . +.It Fl P , Fl -supervisor-pidfile Ar supervisor_pidfile +Write the ID of the +.Nm +process into the +.Ar supervisor_pidfile +using the +.Xr pidfile 3 +functionality. +The program is executed in a spawned child process while the +.Nm +waits until it terminates to keep the +.Ar supervisor_pidfile +locked and removes it after the process exits. +The +.Ar supervisor_pidfile +owner is the user who runs the +.Nm +regardless of whether the +.Fl -user +option is used or not. +.It Fl p , Fl -child-pidfile Ar child_pidfile +Write the ID of the created process into the +.Ar child_pidfile +using the +.Xr pidfile 3 +functionality. +The program is executed in a spawned child process while the +.Nm +waits until it terminates to keep the +.Ar child_pidfile +locked and removes it after the process exits. +The +.Ar child_pidfile +owner is the user who runs the +.Nm +regardless of whether the +.Fl -user +option is used or not. +.It Fl R , Fl -restart-delay Ar restart_delay_seconds +Supervise and restart the program after the specified delay +if it has been terminated. +Valid values are 1-31536000 (up to 1 year). +.It Fl r , Fl -restart +Supervise and restart the program after a one-second delay if it has +been terminated. +.It Fl S , Fl -syslog +Enable syslog output. +This is implicitly applied if other syslog parameters are provided. +The default values are daemon, notice, and daemon for facility, priority, and +tag, respectively. +.It Fl s , Fl -syslog-priority Ar syslog_priority +These priorities are accepted: +.Cm emerg , alert , crit , err , warning , +.Cm notice , info , +and +.Cm debug . +The default is +.Cm notice . +.It Fl T , Fl -syslog-tag Ar syslog_tag +Set the tag which is appended to all syslog messages. +The default is +.Cm daemon . +.It Fl t , Fl -title Ar title +Set the title for the daemon process. +The default is the daemonized invocation. +.It Fl u , Fl -user Ar user +Login name of the user to execute the program under. +Environment variables +.Ev HOME , USER , +and +.Ev SHELL +are set accordingly. +Requires adequate superuser privileges. +.El +.Pp +If any of the options +.Fl -child-pidfile , +.Fl -output-mask , +.Fl -restart , +.Fl -restart-delay , +.Fl -supervisor-pidfile , +.Fl -syslog , +.Fl -syslog-facility +.Fl -syslog-priority , +.Fl -syslog-tag , +or +.Fl -output , +are specified, the program is executed in a spawned child process. +The +.Nm +waits until it terminates to keep the pid file(s) locked and removes them +after the process exits or restarts the program. +In this case if the monitoring +.Nm +receives software termination signal +.Pq Dv SIGTERM +it forwards it to the +spawned process. +Normally it will cause the child to exit, remove the pidfile(s) +and then terminate. +.Pp +If neither file or syslog output are selected, all output is redirected to the +.Nm +process and written to stdout. +The +.Fl -close-fds +option may be used to suppress the stdout output completely. +.Pp +The +.Fl -supervisor-pidfile +option is useful combined with the +.Fl -restart +option as +.Ar supervisor_pidfile +contains the ID of the supervisor +not the child. +This is especially important if you use +.Fl -restart +in an rc script as the +.Fl -child-pidfile +option will give you the child's ID to signal when you attempt to +stop the service, causing +.Nm +to restart the child. +.Sh EXIT STATUS +The +.Nm +utility exits 1 if an error is returned by the +.Xr daemon 3 +library routine, 2 if +.Ar child_pidfile +or +.Ar supervisor_pidfile +is requested, but cannot be opened, 3 if process is already running (pidfile +exists and is locked), 4 if +.Ar syslog_priority +is not accepted, 5 if +.Ar syslog_facility +is not accepted, 6 if +.Ar output_mask +is not within the accepted range, 7 if +.Ar output_file +cannot be opened for appending, and otherwise 0. +.Sh DIAGNOSTICS +If the command cannot be executed, an error message is printed to +standard error. +The exact behavior depends on the logging parameters and the +.Fl -close-fds +flag. +.Sh SEE ALSO +.Xr nohup 1 , +.Xr setregid 2 , +.Xr setreuid 2 , +.Xr daemon 3 , +.Xr exec 3 , +.Xr pidfile 3 , +.Xr termios 4 , +.Xr tty 4 +.Sh HISTORY +The +.Nm +utility first appeared in +.Fx 4.7 . |