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