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 SIGHUP is received, for interoperability with
  73 .Xr newsyslog 1
  74 and similar log rotation / archival mechanisms.  If
  75 .Fl -output-file
  76 is not specified, this flag is ignored.
  77 .It Fl S , Fl -syslog
  78 Enable syslog output.
  79 This is implicitly applied if other syslog parameters are provided.
  80 The default values are daemon, notice, and daemon for facility, priority, and
  81 tag, respectively.
  82 .It Fl o , Fl -output-file Ar output_file
  83 Append output from the daemonized process to
  84 .Pa output_file .
  85 If the file does not exist, it is created with permissions 0600.
  86 When this option is used together with options
  87 .Fl -change-dir
  88 and
  89 .Fl -sighup
  90 the absolute path needs to be provided to ensure
  91 .Nm
  92 can re-open the file after a SIGHUP.
  93 .It Fl m , Fl -output-mask Ar output_mask
  94 Redirect output from the child process stdout (1), stderr (2), or both (3).
  95 This value specifies what is sent to syslog and the log file.
  96 The default is 3.
  97 .It Fl p , Fl -child-pidfile Ar child_pidfile
  98 Write the ID of the created process into the
  99 .Ar child_pidfile
 100 using the
 101 .Xr pidfile 3
 102 functionality.
 103 The program is executed in a spawned child process while the
 104 .Nm
 105 waits until it terminates to keep the
 106 .Ar child_pidfile
 107 locked and removes it after the process exits.
 108 The
 109 .Ar child_pidfile
 110 owner is the user who runs the
 111 .Nm
 112 regardless of whether the
 113 .Fl -user
 114 option is used or not.
 115 .It Fl P , Fl -supervisor-pidfile Ar supervisor_pidfile
 116 Write the ID of the
 117 .Nm
 118 process into the
 119 .Ar supervisor_pidfile
 120 using the
 121 .Xr pidfile 3
 122 functionality.
 123 The program is executed in a spawned child process while the
 124 .Nm
 125 waits until it terminates to keep the
 126 .Ar supervisor_pidfile
 127 locked and removes it after the process exits.
 128 The
 129 .Ar supervisor_pidfile
 130 owner is the user who runs the
 131 .Nm
 132 regardless of whether the
 133 .Fl -user
 134 option is used or not.
 135 .It Fl r , Fl -restart
 136 Supervise and restart the program after a one-second delay if it has
 137 been terminated.
 138 .It Fl R , Fl -restart-delay Ar restart_delay_seconds
 139 Supervise and restart the program after the specified delay
 140 if it has been terminated.
 141 .It Fl t , Fl -title Ar title
 142 Set the title for the daemon process.
 143 The default is the daemonized invocation.
 144 .It Fl u , Fl -user Ar user
 145 Login name of the user to execute the program under.
 146 Requires adequate superuser privileges.
 147 .It Fl s , Fl -syslog-priority Ar syslog_priority
 148 These priorities are accepted: emerg, alert, crit, err, warning,
 149 notice, info, and debug.
 150 The default is notice.
 151 .It Fl l , Fl -syslog-facility Ar syslog_facility
 152 These facilities are accepted: auth, authpriv, console, cron, daemon,
 153 ftp, kern, lpr, mail, news, ntp, security, syslog, user, uucp, and
 154 local0, ..., local7.
 155 The default is daemon.
 156 .It Fl T , Fl -syslog-tag Ar syslog_tag
 157 Set the tag which is appended to all syslog messages.
 158 The default is daemon.
 159 .El
 160 .Pp
 161 If any of the options
 162 .Fl -child-pidfile ,
 163 .Fl -output-mask ,
 164 .Fl -restart ,
 165 .Fl -restart-delay ,
 166 .Fl -supervisor-pidfile ,
 167 .Fl -syslog ,
 168 .Fl -syslog-facility
 169 .Fl -syslog-priority ,
 170 .Fl -syslog-tag ,
 171 or
 172 .Fl -output ,
 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 -close-fds
 190 option may be used to suppress the stdout output completely.
 191 .Pp
 192 The
 193 .Fl -supervisor-pidfile
 194 option is useful combined with the
 195 .Fl -restart
 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 -restart
 202 in an rc script as the
 203 .Fl -child-pidfile
 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 -close-fds
 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 .