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