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