usr.sbin/daemon/daemon.8

   1 .\" Copyright (c) 1999 Berkeley Software Design, Inc. All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\" 3. Berkeley Software Design Inc's name may not be used to endorse or
  12 .\"    promote products derived from this software without specific prior
  13 .\"    written permission.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN INC BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: head/usr.sbin/daemon/daemon.8 353025 2019-10-02 23:19:34Z ian $
  28 .\"
  29 .Dd May 14, 2020
  30 .Dt DAEMON 8
  31 .Os
  32 .Sh NAME
  33 .Nm daemon
  34 .Nd run detached from the controlling terminal
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl cfrS
  38 .Op Fl p Ar child_pidfile
  39 .Op Fl P Ar supervisor_pidfile
  40 .Op Fl t Ar title
  41 .Op Fl u Ar user
  42 .Op Fl m Ar output_mask
  43 .Op Fl o Ar output_file
  44 .Op Fl s Ar syslog_priority
  45 .Op Fl T Ar syslog_tag
  46 .Op Fl l Ar syslog_facility
  47 .Op Fl R Ar restart_delay_seconds
  48 .Ar command arguments ...
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility detaches itself from the controlling terminal and
  53 executes the program specified by its arguments.
  54 Privileges may be lowered to the specified user.
  55 The output of the daemonized process may be redirected to syslog and to a
  56 log file.
  57 .Pp
  58 The options are as follows:
  59 .Bl -tag -width indent
  60 .It Fl c
  61 Change the current working directory to the root
  62 .Pq Dq Pa / .
  63 .It Fl f
  64 Redirect standard input, standard output and standard error to
  65 .Pa /dev/null .
  66 When this option is used together with any of the options related to file
  67 or syslog output, the standard file descriptors are first redirected to
  68 .Pa /dev/null ,
  69 then stdout and/or stderr is redirected to a file or to syslog as
  70 specified by the other options.
  71 .It Fl S
  72 Enable syslog output.
  73 This is implicitly applied if other syslog parameters are provided.
  74 The default values are daemon, notice, and daemon for facility, priority, and
  75 tag, respectively.
  76 .It Fl o Ar output_file
  77 Append output from the daemonized process to
  78 .Pa output_file .
  79 If the file does not exist, it is created with permissions 0600.
  80 For a proper automatic log file rotation of programs started with
  81 .Nm
  82 it is recommended to create a PID file with the
  83 .Fl p
  84 option and configure
  85 .Xr newsyslog.conf 5
  86 to send
  87 .Dv SIGUSR1
  88 to the process ID in this file.
  89 .It Fl m Ar output_mask
  90 Redirect output from the child process stdout (1), stderr (2), or both (3).
  91 This value specifies what is sent to syslog and the log file.
  92 The default is 3.
  93 .It Fl p Ar child_pidfile
  94 Write the ID of the created process into the
  95 .Ar child_pidfile
  96 using the
  97 .Xr pidfile 3
  98 functionality.
  99 The program is executed in a spawned child process while the
 100 .Nm
 101 waits until it terminates to keep the
 102 .Ar child_pidfile
 103 locked and removes it after the process exits.
 104 The
 105 .Ar child_pidfile
 106 owner is the user who runs the
 107 .Nm
 108 regardless of whether the
 109 .Fl u
 110 option is used or not.
 111 .It Fl P Ar supervisor_pidfile
 112 Write the ID of the
 113 .Nm
 114 process into the
 115 .Ar supervisor_pidfile
 116 using the
 117 .Xr pidfile 3
 118 functionality.
 119 The program is executed in a spawned child process while the
 120 .Nm
 121 waits until it terminates to keep the
 122 .Ar supervisor_pidfile
 123 locked and removes it after the process exits.
 124 The
 125 .Ar supervisor_pidfile
 126 owner is the user who runs the
 127 .Nm
 128 regardless of whether the
 129 .Fl u
 130 option is used or not.
 131 .It Fl r
 132 Supervise and restart the program after a one-second delay if it has
 133 been terminated.
 134 .It Fl R Ar restart_delay_seconds
 135 Supervise and restart the program after the specified delay
 136 if it has been terminated.
 137 .It Fl t Ar title
 138 Set the title for the daemon process.
 139 The default is the daemonized invocation.
 140 .It Fl u Ar user
 141 Login name of the user to execute the program under.
 142 Requires adequate superuser privileges.
 143 .It Fl s Ar syslog_priority
 144 These priorities are accepted: emerg, alert, crit, err, warning,
 145 notice, info, and debug.
 146 The default is notice.
 147 .It Fl l Ar syslog_facility
 148 These facilities are accepted: auth, authpriv, console, cron, daemon,
 149 ftp, kern, lpr, mail, news, ntp, security, syslog, user, uucp, and
 150 local0, ..., local7.
 151 The default is daemon.
 152 .It Fl T Ar syslog_tag
 153 Set the tag which is appended to all syslog messages.
 154 The default is daemon.
 155 .El
 156 .Pp
 157 If any of the options
 158 .Fl p ,
 159 .Fl P ,
 160 .Fl r ,
 161 .Fl o ,
 162 .Fl s ,
 163 .Fl T ,
 164 .Fl m ,
 165 .Fl S ,
 166 or
 167 .Fl l
 168 are specified, the program is executed in a spawned child process.
 169 The
 170 .Nm
 171 waits until it terminates to keep the pid file(s) locked and removes them
 172 after the process exits or restarts the program.
 173 In this case if the monitoring
 174 .Nm
 175 receives software termination signal (SIGTERM) it forwards it to the
 176 spawned process.
 177 Normally it will cause the child to exit, remove the pidfile(s)
 178 and then terminate.
 179 .Pp
 180 If neither file or syslog output are selected, all output is redirected to the
 181 .Nm
 182 process and written to stdout.
 183 The
 184 .Fl f
 185 option may be used to suppress the stdout output completely.
 186 .Pp
 187 The
 188 .Fl P
 189 option is useful combined with the
 190 .Fl r
 191 option as
 192 .Ar supervisor_pidfile
 193 contains the ID of the supervisor
 194 not the child.
 195 This is especially important if you use
 196 .Fl r
 197 in an rc script as the
 198 .Fl p
 199 option will give you the child's ID to signal when you attempt to
 200 stop the service, causing
 201 .Nm
 202 to restart the child.
 203 .Sh EXIT STATUS
 204 The
 205 .Nm
 206 utility exits 1 if an error is returned by the
 207 .Xr daemon 3
 208 library routine, 2 if
 209 .Ar child_pidfile
 210 or
 211 .Ar supervisor_pidfile
 212 is requested, but cannot be opened, 3 if process is already running (pidfile
 213 exists and is locked), 4 if
 214 .Ar syslog_priority
 215 is not accepted, 5 if
 216 .Ar syslog_facility
 217 is not accepted, 6 if
 218 .Ar output_mask
 219 is not within the accepted range, 7 if
 220 .Ar output_file
 221 cannot be opened for appending, and otherwise 0.
 222 .Sh DIAGNOSTICS
 223 If the command cannot be executed, an error message is printed to
 224 standard error.
 225 The exact behavior depends on the logging parameters and the
 226 .Fl f
 227 flag.
 228 .Sh SEE ALSO
 229 .Xr nohup 1 ,
 230 .Xr setregid 2 ,
 231 .Xr setreuid 2 ,
 232 .Xr daemon 3 ,
 233 .Xr exec 3 ,
 234 .Xr pidfile 3 ,
 235 .Xr termios 4 ,
 236 .Xr tty 4 ,
 237 .Xr newsyslog.conf 5
 238 .Sh HISTORY
 239 The
 240 .Nm
 241 utility first appeared in
 242 .Fx 4.7 .