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