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
  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
  90 and
  91 .Fl H
  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 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 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 u
 116 option is used or not.
 117 .It Fl P 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 u
 136 option is used or not.
 137 .It Fl r
 138 Supervise and restart the program after a one-second delay if it has
 139 been terminated.
 140 .It Fl R Ar restart_delay_seconds
 141 Supervise and restart the program after the specified delay
 142 if it has been terminated.
 143 .It Fl t Ar title
 144 Set the title for the daemon process.
 145 The default is the daemonized invocation.
 146 .It Fl u Ar user
 147 Login name of the user to execute the program under.
 148 Requires adequate superuser privileges.
 149 .It Fl s 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 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 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 p ,
 165 .Fl P ,
 166 .Fl r ,
 167 .Fl o ,
 168 .Fl s ,
 169 .Fl T ,
 170 .Fl m ,
 171 .Fl S ,
 172 or
 173 .Fl l
 174 are specified, the program is executed in a spawned child process.
 175 The
 176 .Nm
 177 waits until it terminates to keep the pid file(s) locked and removes them
 178 after the process exits or restarts the program.
 179 In this case if the monitoring
 180 .Nm
 181 receives software termination signal (SIGTERM) it forwards it to the
 182 spawned process.
 183 Normally it will cause the child to exit, remove the pidfile(s)
 184 and then terminate.
 185 .Pp
 186 If neither file or syslog output are selected, all output is redirected to the
 187 .Nm
 188 process and written to stdout.
 189 The
 190 .Fl f
 191 option may be used to suppress the stdout output completely.
 192 .Pp
 193 The
 194 .Fl P
 195 option is useful combined with the
 196 .Fl r
 197 option as
 198 .Ar supervisor_pidfile
 199 contains the ID of the supervisor
 200 not the child.
 201 This is especially important if you use
 202 .Fl r
 203 in an rc script as the
 204 .Fl p
 205 option will give you the child's ID to signal when you attempt to
 206 stop the service, causing
 207 .Nm
 208 to restart the child.
 209 .Sh EXIT STATUS
 210 The
 211 .Nm
 212 utility exits 1 if an error is returned by the
 213 .Xr daemon 3
 214 library routine, 2 if
 215 .Ar child_pidfile
 216 or
 217 .Ar supervisor_pidfile
 218 is requested, but cannot be opened, 3 if process is already running (pidfile
 219 exists and is locked), 4 if
 220 .Ar syslog_priority
 221 is not accepted, 5 if
 222 .Ar syslog_facility
 223 is not accepted, 6 if
 224 .Ar output_mask
 225 is not within the accepted range, 7 if
 226 .Ar output_file
 227 cannot be opened for appending, and otherwise 0.
 228 .Sh DIAGNOSTICS
 229 If the command cannot be executed, an error message is printed to
 230 standard error.
 231 The exact behavior depends on the logging parameters and the
 232 .Fl f
 233 flag.
 234 .Sh SEE ALSO
 235 .Xr nohup 1 ,
 236 .Xr setregid 2 ,
 237 .Xr setreuid 2 ,
 238 .Xr daemon 3 ,
 239 .Xr exec 3 ,
 240 .Xr pidfile 3 ,
 241 .Xr termios 4 ,
 242 .Xr tty 4
 243 .Sh HISTORY
 244 The
 245 .Nm
 246 utility first appeared in
 247 .Fx 4.7 .