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