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