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 .Dd January 14, 2021
  28 .Dt DAEMON 8
  29 .Os
  30 .Sh NAME
  31 .Nm daemon
  32 .Nd run detached from the controlling terminal
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl cfHrS
  36 .Op Fl p Ar child_pidfile
  37 .Op Fl P Ar supervisor_pidfile
  38 .Op Fl t Ar title
  39 .Op Fl u Ar user
  40 .Op Fl m Ar output_mask
  41 .Op Fl o Ar output_file
  42 .Op Fl s Ar syslog_priority
  43 .Op Fl T Ar syslog_tag
  44 .Op Fl l Ar syslog_facility
  45 .Op Fl R Ar restart_delay_seconds
  46 .Ar command arguments ...
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility detaches itself from the controlling terminal and
  51 executes the program specified by its arguments.
  52 Privileges may be lowered to the specified user.
  53 The output of the daemonized process may be redirected to syslog and to a
  54 log file.
  55 .Pp
  56 The options are as follows:
  57 .Bl -tag -width indent
  58 .It Fl c , Fl -change-dir
  59 Change the current working directory to the root
  60 .Pq Dq Pa / .
  61 .It Fl f , Fl -close-fds
  62 Redirect standard input, standard output and standard error to
  63 .Pa /dev/null .
  64 When this option is used together with any of the options related to file
  65 or syslog output, the standard file descriptors are first redirected to
  66 .Pa /dev/null ,
  67 then stdout and/or stderr is redirected to a file or to syslog as
  68 specified by the other options.
  69 .It Fl H , Fl -sighup
  70 Close
  71 .Pa output_file
  72 and re-open it when signal
  73 .Dv SIGHUP
  74 is received, for interoperability with
  75 .Xr newsyslog 1
  76 and similar log rotation / archival mechanisms.  If
  77 .Fl -output-file
  78 is not specified, this flag is ignored.
  79 .It Fl l , Fl -syslog-facility Ar syslog_facility
  80 These facilities are accepted:
  81 .Cm auth , authpriv , console , cron , daemon ,
  82 .Cm ftp , kern , lpr , mail , news , ntp , security ,
  83 .Cm syslog , user , uucp ,
  84 and
  85 local facilities from
  86 .Cm local0
  87 to
  88 .Cm local7 .
  89 The default is
  90 .Cm daemon .
  91 .It Fl m , Fl -output-mask Ar output_mask
  92 Redirect output from the child process stdout
  93 .Pq Cm 1 ,
  94 stderr
  95 .Pq Cm 2 ,
  96 or both
  97 .Pq Cm 3 .
  98 This value specifies what is sent to syslog and the log file.
  99 The default is
 100 .Cm 3 .
 101 .It Fl o , Fl -output-file Ar output_file
 102 Append output from the daemonized process to
 103 .Pa output_file .
 104 If the file does not exist, it is created with permissions 0600.
 105 When this option is used together with options
 106 .Fl -change-dir
 107 and
 108 .Fl -sighup
 109 the absolute path needs to be provided to ensure
 110 .Nm
 111 can re-open the file after a
 112 .Dv SIGHUP .
 113 .It Fl P , Fl -supervisor-pidfile Ar supervisor_pidfile
 114 Write the ID of the
 115 .Nm
 116 process into the
 117 .Ar supervisor_pidfile
 118 using the
 119 .Xr pidfile 3
 120 functionality.
 121 The program is executed in a spawned child process while the
 122 .Nm
 123 waits until it terminates to keep the
 124 .Ar supervisor_pidfile
 125 locked and removes it after the process exits.
 126 The
 127 .Ar supervisor_pidfile
 128 owner is the user who runs the
 129 .Nm
 130 regardless of whether the
 131 .Fl -user
 132 option is used or not.
 133 .It Fl p , Fl -child-pidfile Ar child_pidfile
 134 Write the ID of the created process into the
 135 .Ar child_pidfile
 136 using the
 137 .Xr pidfile 3
 138 functionality.
 139 The program is executed in a spawned child process while the
 140 .Nm
 141 waits until it terminates to keep the
 142 .Ar child_pidfile
 143 locked and removes it after the process exits.
 144 The
 145 .Ar child_pidfile
 146 owner is the user who runs the
 147 .Nm
 148 regardless of whether the
 149 .Fl -user
 150 option is used or not.
 151 .It Fl R , Fl -restart-delay Ar restart_delay_seconds
 152 Supervise and restart the program after the specified delay
 153 if it has been terminated.
 154 .It Fl r , Fl -restart
 155 Supervise and restart the program after a one-second delay if it has
 156 been terminated.
 157 .It Fl S , Fl -syslog
 158 Enable syslog output.
 159 This is implicitly applied if other syslog parameters are provided.
 160 The default values are daemon, notice, and daemon for facility, priority, and
 161 tag, respectively.
 162 .It Fl s , Fl -syslog-priority Ar syslog_priority
 163 These priorities are accepted:
 164 .Cm emerg , alert , crit , err , warning ,
 165 .Cm notice , info ,
 166 and
 167 .Cm debug .
 168 The default is
 169 .Cm notice .
 170 .It Fl T , Fl -syslog-tag Ar syslog_tag
 171 Set the tag which is appended to all syslog messages.
 172 The default is
 173 .Cm daemon .
 174 .It Fl t , Fl -title Ar title
 175 Set the title for the daemon process.
 176 The default is the daemonized invocation.
 177 .It Fl u , Fl -user Ar user
 178 Login name of the user to execute the program under.
 179 Requires adequate superuser privileges.
 180 .El
 181 .Pp
 182 If any of the options
 183 .Fl -child-pidfile ,
 184 .Fl -output-mask ,
 185 .Fl -restart ,
 186 .Fl -restart-delay ,
 187 .Fl -supervisor-pidfile ,
 188 .Fl -syslog ,
 189 .Fl -syslog-facility
 190 .Fl -syslog-priority ,
 191 .Fl -syslog-tag ,
 192 or
 193 .Fl -output ,
 194 are specified, the program is executed in a spawned child process.
 195 The
 196 .Nm
 197 waits until it terminates to keep the pid file(s) locked and removes them
 198 after the process exits or restarts the program.
 199 In this case if the monitoring
 200 .Nm
 201 receives software termination signal
 202 .Pq Dv SIGTERM
 203 it forwards it to the
 204 spawned process.
 205 Normally it will cause the child to exit, remove the pidfile(s)
 206 and then terminate.
 207 .Pp
 208 If neither file or syslog output are selected, all output is redirected to the
 209 .Nm
 210 process and written to stdout.
 211 The
 212 .Fl -close-fds
 213 option may be used to suppress the stdout output completely.
 214 .Pp
 215 The
 216 .Fl -supervisor-pidfile
 217 option is useful combined with the
 218 .Fl -restart
 219 option as
 220 .Ar supervisor_pidfile
 221 contains the ID of the supervisor
 222 not the child.
 223 This is especially important if you use
 224 .Fl -restart
 225 in an rc script as the
 226 .Fl -child-pidfile
 227 option will give you the child's ID to signal when you attempt to
 228 stop the service, causing
 229 .Nm
 230 to restart the child.
 231 .Sh EXIT STATUS
 232 The
 233 .Nm
 234 utility exits 1 if an error is returned by the
 235 .Xr daemon 3
 236 library routine, 2 if
 237 .Ar child_pidfile
 238 or
 239 .Ar supervisor_pidfile
 240 is requested, but cannot be opened, 3 if process is already running (pidfile
 241 exists and is locked), 4 if
 242 .Ar syslog_priority
 243 is not accepted, 5 if
 244 .Ar syslog_facility
 245 is not accepted, 6 if
 246 .Ar output_mask
 247 is not within the accepted range, 7 if
 248 .Ar output_file
 249 cannot be opened for appending, and otherwise 0.
 250 .Sh DIAGNOSTICS
 251 If the command cannot be executed, an error message is printed to
 252 standard error.
 253 The exact behavior depends on the logging parameters and the
 254 .Fl -close-fds
 255 flag.
 256 .Sh SEE ALSO
 257 .Xr nohup 1 ,
 258 .Xr setregid 2 ,
 259 .Xr setreuid 2 ,
 260 .Xr daemon 3 ,
 261 .Xr exec 3 ,
 262 .Xr pidfile 3 ,
 263 .Xr termios 4 ,
 264 .Xr tty 4
 265 .Sh HISTORY
 266 The
 267 .Nm
 268 utility first appeared in
 269 .Fx 4.7 .