sbin/svc/svc.8

   1 .\"
   2 .\" Copyright (c) 2014
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd November 10, 2014
  33 .Dt SVC 8
  34 .Os
  35 .Sh NAME
  36 .Nm svc
  37 .Nd build an environment and monitor/maintain a service or command
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl options
  41 .Ar directive
  42 .Ar label
  43 .Op arguments-to-directive
  44 .Sh DESCRIPTION
  45 .Nm
  46 is a program which can build, monitor, and manage a simple environment
  47 and execute a command within that environment.
  48 It uses the
  49 .Xr procctl 2
  50 system call to round-up all processes and sub-processes created under the
  51 environment.
  52 It can detect when the specific command or the command and all processes
  53 exit and perform some action, and it can do a few relatively simple support
  54 functions to terminate, restart, or terminate/re-initiate.
  55 .Pp
  56 The following options are available:
  57 .Bl -tag -width indent
  58 .It Fl d
  59 Debug mode.  Additional debug output is printed.
  60 This will also force
  61 .Fl f .
  62 .It Fl f
  63 Foreground mode.  Instead of fork/detaching the service, the service itself
  64 runs in the foreground when the
  65 .Ar init
  66 directive is specified.  The pid will not be printed in this case.
  67 .It Fl h
  68 Display quick help for directives and exit.
  69 .It Fl p Ar directory
  70 Specify the directory to store pidfiles and sockets in, and to search
  71 for active labels.
  72 If not specified, the default is
  73 .Pa /var/run .
  74 If specified as
  75 .Ar none ,
  76 no pidfile will be created or maintained.  The
  77 .Ar none
  78 specification is not recommended except in combination with
  79 .Fl f
  80 .Fl x .
  81 .It Fl r Ar timo
  82 Specify the restart delay and enable automatic restarts if the original
  83 command under management exits, even if other processes are still present.
  84 This option also modifies the behavior of the
  85 .Ar stop
  86 service command, causing it to kill only the main process under management.
  87 Any forked children will be left intact.
  88 This option is exclusive with
  89 .Fl R .
  90 .It Fl R Ar timo
  91 Specify the restart delay and enable automatic restarts if all processes
  92 under management exit.
  93 This option also modifies the behavior of the
  94 .Ar stop
  95 service command, causing it to kill all processes under management.
  96 This option is exclusive with
  97 .Fl r .
  98 .It Fl x
  99 Causes the service demon itself to exit if the service being monitored
 100 exits or is stopped.
 101 Specify as an option to the left of the
 102 .Ar init
 103 directive.
 104 .Nm
 105 will still use
 106 .Fl r
 107 or
 108 .Fl R
 109 to indicate what is considered a dead service (some or all of the processes).
 110 If neither is specified,
 111 .Fl r
 112 is assumed.  If specified, the timeout is irrelevant as there will be no
 113 restart.
 114 .Pp
 115 This option also issues a
 116 .Ar stopall
 117 directive before exiting.  That is, it will still ensure that all processes
 118 running under the service, either direct or indirect, are dead before the
 119 service itself exits.
 120 .It Fl s
 121 Causes the service demon to issue a
 122 .Xr sync 2
 123 command after stopping or killing a service.
 124 .It Fl t Ar timo
 125 When stopping processes under management, specify the amount of time
 126 allowed to elapse after sending a SIGTERM before sending a SIGKILL.
 127 If 0 is specified, only SIGKILL will be sent.
 128 The default is 10 seconds.
 129 .It Fl u Ar user
 130 Set the uid and gid of the command to execute based on the user.
 131 The uid or username must exist in the password file.
 132 The gid may be overridden by the
 133 .Fl g
 134 or
 135 .Fl G
 136 options.
 137 The service demon itself is not affected.
 138 .Pp
 139 Specified when initializing a new service, has no effect for other directives.
 140 Cannot be overridden in
 141 .Ar start
 142 or
 143 .Ar restart .
 144 .It Fl g Ar group
 145 Set the gid of the command to execute.
 146 This will override the user's gid set via the
 147 .Fl u
 148 option.
 149 The service demon itself is not affected.
 150 .Pp
 151 Specified when initializing a new service, has no effect for other directives.
 152 Cannot be overridden in
 153 .Ar start
 154 or
 155 .Ar restart .
 156 .It Fl G Ar group-list
 157 Set the group-list of the command to execute.  The service demon itself is not
 158 affected.
 159 This will completely override all other assumed or specified GIDs.
 160 .Pp
 161 Specified when initializing a new service, has no effect for other directives.
 162 Cannot be overridden in
 163 .Ar start
 164 or
 165 .Ar restart .
 166 .It Fl l Ar path
 167 Set the logfile path for the command.
 168 If not specified, no logfile will be created.
 169 However, the service monitor will still keep track of the last ~8KB or
 170 so of stdout/stderr output.
 171 .Pp
 172 Specified when initializing a new service, has no effect for other directives.
 173 .It Fl m
 174 May be used in combination with
 175 .Fl c
 176 or
 177 .Fl j
 178 to automatically mount /dev in a chroot or jail.
 179 It will be left mounted through stops and starts and will be unmounted
 180 when
 181 .Nm
 182 is told to exit.
 183 .Pp
 184 Specified when initializing a new service, has no effect for other directives.
 185 .It Fl c Ar directory
 186 Chroot into the specified directory when executing or re-executing the
 187 command.  The service itself stays outside the chroot.
 188 If
 189 .Fl m
 190 is also specified, the service will automatically mount /dev in the chroot
 191 if it does not already exist and unmount it when the service exits.  The
 192 mount remains in place when the service is stopped.
 193 .Pp
 194 Specified when initializing a new service, has no effect for other directives.
 195 Cannot be overridden in
 196 .Ar start
 197 or
 198 .Ar restart .
 199 .It Fl j Ar directory
 200 Create a jail and operate in a manner similar to a chroot.
 201 .It Fl k Ar jail-spec
 202 Additional specification for the jail.  See below.
 203 .It Fl T Ar title
 204 Tell
 205 .Nm
 206 to use
 207 .Xr setproctitle 3
 208 to adjust what shows up in a ps command, to make process lists easier to
 209 diagnose.
 210 .It Fl F Ar restarts:pertimo
 211 Specify failure timing.
 212 If a service is automatically restarted more than the specified number
 213 within the specified period, the service is considered to be in a failed
 214 state when it next dies and will no longer be restarted.
 215 .Pp
 216 The situation will be syslogged and an email will be sent to
 217 .Ar service-errors
 218 with a description of the problem if the service is running as root.
 219 If the service is running as a user, the email is sent to the user.
 220 The system operator should generally setup a mail alias to point
 221 .Ar service-errors
 222 to the desired destination.
 223 .Pp
 224 This feature is disabled by default.
 225 If you only specify the restart count the rate will default to
 226 per 60 seconds.
 227 Specify as an option to the left of the
 228 .Ar init
 229 directive.
 230 .It Ar directive Op arguments-to-directive
 231 Specify a directive (see below).
 232 .It Ar label
 233 Specify a label to name or locate the service.
 234 Note that most directives allow a label prefix to be specified, affecting
 235 multiple services.
 236 If your label is postfixed by a number, you should use a fixed-width
 237 0-fill field for the number or risk some confusion.
 238 .El
 239 .Pp
 240 All timeouts and delays are specified in seconds.
 241 .Pp
 242 If neither
 243 .Fl r
 244 or
 245 .Fl R
 246 is specified in the
 247 .Ar init
 248 directive, the service will not automatically restart if the underlying
 249 processes exit.  The service demon will remain intact unless
 250 .Fl x
 251 has been specified.
 252 .Pp
 253 .Nm
 254 always creates a pid file in the pid directory named
 255 .Pa service.<label>.pid
 256 and maintains an open descriptor with an active exclusive
 257 .Xr flock 2
 258 on the file.
 259 Scripts can determine whether the service demon itself is running or not
 260 via the
 261 .Xr lockf 1
 262 utility, or may use the convenient
 263 .Ar status
 264 directive and check the exit code to get more detailed status.
 265 In addition, a service socket is created in the pid directory named
 266 .Pa service.<label>.sk
 267 which
 268 .Nm
 269 uses to communicate with a running service demon.
 270 .Pp
 271 Note that the service demon itself will not exit when the executed command
 272 exits unless you have used the
 273 .Fl x
 274 option, or the
 275 .Ar exit
 276 or
 277 .Ar kill
 278 directives.
 279 .Pp
 280 Some RC services, such as sendmail, may maintain multiple service processes
 281 and name each one with a postfix to the label.
 282 By specifying just the prefix, your directives will affect all matching
 283 labels.
 284 .Pp
 285 For build systems the
 286 .Fl x
 287 option is typically used, sometimes with the
 288 .Fl f
 289 option, and allowed to default to just waiting for the original command
 290 exec to exit.
 291 This will cause the service demon to then kill any remaining hanger-ons
 292 before exiting.
 293 .Sh DIRECTIVES
 294 .Bl -tag -width indent
 295 .It Ar init Ar label Ar exec-command Op arguments
 296 Start a new service with the specified label.
 297 This command will fail if the label is already in-use.
 298 This command will detach a new service demon, create a pidfile, and
 299 output the pid of the new service demon to stdout before returning.
 300 .Pp
 301 If the
 302 .Ar exec-command
 303 is a single word and not an absolute or relative path, the system
 304 command path will be searched for the command.
 305 .It Ar start
 306 Start a service that has been stopped.
 307 The label can be a wildcard prefix so, for example, if there are
 308 three sendmail services (sendmail01, sendmail02, sendmail03), then
 309 the label 'sendmail' will operate on all three.
 310 .Pp
 311 If the service is already running, this directive will be a NOP.
 312 .It Ar stop
 313 Stop a running service by sending a TERM signal and later a KILL signal
 314 if necessry, to some or all processes
 315 running under the service.  The processes signaled depend on the original
 316 .Fl r
 317 or
 318 .Fl R
 319 options specified when the service was initiated.
 320 These options, along with
 321 .Fl t
 322 may also be specified in this directive to override
 323 (but not permanently change) the original options.
 324 .Pp
 325 The service demon itself remains intact.
 326 .It Ar stopall
 327 This is a short-hand for
 328 .Fl R Ar 0
 329 .Ar stop .
 330 It will kill all sub-processes of the service regardless of whether
 331 .Fl r
 332 or
 333 .Fl R
 334 was used in the original
 335 .Ar init
 336 directive.
 337 .It Ar restart
 338 Execute the
 339 .Ar stop
 340 operation, sleep for a few seconds based on the original
 341 .Fl r
 342 or
 343 .Fl R
 344 options, and then execute the
 345 .Ar start
 346 operation.
 347 These options, along with
 348 .Fl t
 349 may also be specified in this directive to override
 350 (but not permanently change) the original options.
 351 .It Ar exit
 352 Execute the
 353 .Ar stop
 354 operation but override prior options and terminate ALL processes
 355 running under the service.
 356 The service demon itself then terminates and must be init'd again
 357 to restart.
 358 .Pp
 359 This function will also remove any stale pid and socket files.
 360 .It Ar kill
 361 Execute the
 362 .Ar stop
 363 operation but override prior options and terminate ALL processes
 364 running under the service.
 365 Also force the delay to 0, bypassing SIGTERM and causing SIGKILL to be
 366 sent.
 367 The service demon itself then terminates and must be init'd again
 368 to restart.
 369 .Pp
 370 This function will also remove any stale pid and socket files.
 371 .It Ar list
 372 List a subset of labels and their status.
 373 If no label is specified, all active labels are listed.
 374 .It Ar status
 375 Print the status of a particular label, exit with a 0 status if
 376 the service exists and is still considered to be running.
 377 Exit with 1 if the service exists but is considered to be stopped.
 378 Exit with 2 if the service does not exist.
 379 If multiple labels match, the worst condition found becomes the exit code.
 380 .Pp
 381 Scripts that use this feature can conveniently use the
 382 .Ar start
 383 directive to start any matching service that is considered stopped.
 384 The directive is a NOP for services that are considered to be running.
 385 .It Ar log
 386 The service demon monitors stdout/stderr output from programs it runs
 387 continuously and will remember the last ~8KB or so, which can be
 388 dumped via this directive.
 389 .It Ar logf
 390 This works the same as
 391 .Ar log
 392 but continues to monitor and dump the output until you ^C.
 393 In order to avoid potentially stalling the service under management,
 394 gaps may occur if the monitor is unable to keep up with the log
 395 output.
 396 .It Ar tailf
 397 This works similarly to
 398 .Ar logf
 399 but dumps fewer lines of log history before dovetailing into
 400 continuous monitoring.
 401 .It Ar logfile Ar label Op path
 402 Re-open, set, or change the logfile path for the monitor,
 403 creating a new logfile if necessary.
 404 The logfile is created by the parent monitor (the one not running in
 405 a chroot or jail or as a particular user or group).
 406 This way the service under management cannot modify or destroy it.
 407 .Pp
 408 It is highly recommended that you specify an absolute path when
 409 changing the logfile.
 410 If you wish to disable the logfile, set it to /dev/null.
 411 Disabling the logfile does not prevent you from viewing the
 412 last ~8KB and/or monitoring any logged data.
 413 .It Ar help
 414 Display quick help for directives.
 415 .El
 416 .Pp
 417 Description of nominal operation
 418 .Xr procctl 2
 419 system call.
 420 .Sh JAIL-SPECIFICATIONS
 421 A simple jail just chroots into a directory, possibly mounts /dev, and
 422 allows all current IP bindings to be used.
 423 The service demon itself does not run in the jail, but will keep the
 424 jail intact across
 425 .Ar stop
 426 and
 427 .Ar start/restart
 428 operations by leaving a forked process intact inside.
 429 If the jail is destroyed, the service demon will re-create it if necessary
 430 on a
 431 .Ar start/restart .
 432 .Fl k
 433 option may be used to specify additional parameters.
 434 Parameters are comma-delimited with no spaces.
 435 Values may be specified in the name=value format.
 436 For example:
 437 .Fl k Ar clean,ip=1.2.3.4,ip=5.6.7.8
 438 .Bl -tag -width indent
 439 .It Ar clean
 440 The jail is handed a clean environment, similar to what
 441 .Xr jail 8
 442 does.
 443 .It Ar ip=addr
 444 The jail is allowed to bind to the specified IP address.  This option may
 445 be specified multiple times.
 446 .El
 447 .Sh SIGNALS
 448 Generally speaking signals should not be sent to a service demon.
 449 Instead, the command should be run with an appropriate directive to
 450 adjust running behavior.
 451 However, the service demon will act on signals as follows:
 452 .Bl -tag -width indent
 453 .It Dv SIGTERM
 454 The service demon will execute the
 455 .Ar exit
 456 directive.
 457 .It Dv SIGHUP
 458 The service demon will execute the
 459 .Ar restart
 460 directive.
 461 .El
 462 .Sh HISTORY
 463 The
 464 .Nm
 465 utility first appeared in
 466 .Dx 4.0 .