SVC(8)

NAME
svc - build an environment and monitor/maintain a service or command

SYNOPSIS
svc [-options] directive label [arguments-to-directive]

DESCRIPTION
svc is a program which can build, monitor, and manage a simple environment and execute a command within that environment. It uses the procctl(2) system call to round-up all processes and sub-processes created under the environment. It can detect when the specific command or the command and all processes exit and perform some action, and it can do a few relatively simple support functions to terminate, restart, or terminate/re-initiate.

The following options are available:

-d  Debug mode. Additional debug output is printed. This will also force -f.

-f  Foreground mode. Instead of fork/detaching the service, the service itself runs in the foreground when the init directive is specified. The pid will not be printed in this case.

-h  Display quick help for directives and exit.

-p directory
    Specify the directory to store pidfiles and sockets in, and to search for active labels. If not specified, the default is /var/run. If specified as none, no pidfile will be created or maintained. The none specification is not recommended except in combination with -f -x.

-r timo
    Specify the restart delay and enable automatic restarts if the original command under management exits, even if other processes are still present. This option also modifies the behavior of the stop service command, causing it to kill only the main process under management. Any forked children will be left intact. This option is exclusive with -R.

-R timo
    Specify the restart delay and enable automatic restarts if all processes under management exit. This option also modifies the behavior of the stop service command, causing it to kill all processes under management. This option is exclusive with -r.

-x  Causes the service demon itself to exit if the service being monitored exits or is stopped. Specify as an option to the left of the init directive. svc will still use -r or -R to indicate what is considered a dead service (some or all of the processes). If neither is specified, -r is assumed. If specified, the timeout is irrelevant as there will be no restart.

    This option also issues a stopall directive before exiting. That is, it will still ensure that all processes running under the service, either direct or indirect, are dead before the service itself exits.

-s  Causes the service demon to issue a sync(2) command after stopping or killing a service.

-t timo
    When stopping processes under management, specify the amount of time allowed to elapse after sending a SIGTERM before sending a SIGKILL. If 0 is specified, only SIGKILL will be sent. The default is 10 seconds.

-u user
    Set the uid and gid of the command to execute based on the user. The uid or username must exist in the password file. The gid may be overridden by the -g or -G options. The service demon itself is not affected.

    Specified when initializing a new service, has no effect for other directives. Cannot be overridden in start or restart.

-g group
    Set the gid of the command to execute. This will override the user's gid set via the -u option. The service demon itself is not affected.

    Specified when initializing a new service, has no effect for other directives. Cannot be overridden in start or restart.

-G group-list
    Set the group-list of the command to execute. The service demon itself is not affected. This will completely override all other assumed or specified GIDs.

    Specified when initializing a new service, has no effect for other directives. Cannot be overridden in start or restart.

-l path
    Set the logfile path for the command. If not specified, no logfile will be created. However, the service monitor will still keep track of the last ~8KB or so of stdout/stderr output.

    Specified when initializing a new service, has no effect for other directives.

-m  May be used in combination with -c or -j to automatically mount /dev in a chroot or jail. It will be left mounted through stops and starts and will be unmounted when svc is told to exit.

    Specified when initializing a new service, has no effect for other directives.

-c directory
    Chroot into the specified directory when executing or re-executing the command. The service itself stays outside the chroot. If -m is also specified, the service will automatically mount /dev in the chroot if it does not already exist and unmount it when the service exits. The mount remains in place when the service is stopped.

    Specified when initializing a new service, has no effect for other directives. Cannot be overridden in start or restart.

-j directory
    Create a jail and operate in a manner similar to a chroot.

-k jail-spec
    Additional specification for the jail. See below.

-T title
    Tell svc to use setproctitle(3) to adjust what shows up in a ps command, to make process lists easier to diagnose.

-F restarts:pertimo
    Specify failure timing. If a service is automatically restarted more than the specified number within the specified period, the service is considered to be in a failed state when it next dies and will no longer be restarted.

    The situation will be syslogged and an email will be sent to service-errors with a description of the problem if the service is running as root. If the service is running as a user, the email is sent to the user. The system operator should generally setup a mail alias to point service-errors to the desired destination.

    This feature is disabled by default. If you only specify the restart count the rate will default to per 60 seconds. Specify as an option to the left of the init directive.

directive [arguments-to-directive]
    Specify a directive (see below).

label
    Specify a label to name or locate the service. Note that most directives allow a label prefix to be specified, affecting multiple services. If your label is postfixed by a number, you should use a fixed-width 0-fill field for the number or risk some confusion.

All timeouts and delays are specified in seconds.

If neither -r or -R is specified in the init directive, the service will not automatically restart if the underlying processes exit. The service demon will remain intact unless -x has been specified.

svc always creates a pid file in the pid directory named service.<label>.pid and maintains an open descriptor with an active exclusive flock(2) on the file. Scripts can determine whether the service demon itself is running or not via the lockf(1) utility, or may use the convenient status directive and check the exit code to get more detailed status. In addition, a service socket is created in the pid directory named service.<label>.sk which svc uses to communicate with a running service demon.

Note that the service demon itself will not exit when the executed command exits unless you have used the -x option, or the exit or kill directives.

Some RC services, such as sendmail, may maintain multiple service processes and name each one with a postfix to the label. By specifying just the prefix, your directives will affect all matching labels.

For build systems the -x option is typically used, sometimes with the -f option, and allowed to default to just waiting for the original command exec to exit. This will cause the service demon to then kill any remaining hanger-ons before exiting.

DIRECTIVES

init label exec-command [arguments]
    Start a new service with the specified label. This command will fail if the label is already in-use. This command will detach a new service demon, create a pidfile, and output the pid of the new service demon to stdout before returning.

    If the exec-command is a single word and not an absolute or relative path, the system command path will be searched for the command.

start
    Start a service that has been stopped. The label can be a wildcard prefix so, for example, if there are three sendmail services (sendmail01, sendmail02, sendmail03), then the label 'sendmail' will operate on all three.

    If the service is already running, this directive will be a NOP.

stop
    Stop a running service by sending a TERM signal and later a KILL signal if necessry, to some or all processes running under the service. The processes signaled depend on the original -r or -R options specified when the service was initiated. These options, along with -t may also be specified in this directive to override (but not permanently change) the original options.

    The service demon itself remains intact.

stopall
    This is a short-hand for -R 0 stop. It will kill all sub-processes of the service regardless of whether -r or -R was used in the original init directive.

restart
    Execute the stop operation, sleep for a few seconds based on the original -r or -R options, and then execute the start operation. These options, along with -t may also be specified in this directive to override (but not permanently change) the original options.

exit
    Execute the stop operation but override prior options and terminate ALL processes running under the service. The service demon itself then terminates and must be init'd again to restart.

    This function will also remove any stale pid and socket files.

kill
    Execute the stop operation but override prior options and terminate ALL processes running under the service. Also force the delay to 0, bypassing SIGTERM and causing SIGKILL to be sent. The service demon itself then terminates and must be init'd again to restart.

    This function will also remove any stale pid and socket files.

list
    List a subset of labels and their status. If no label is specified, all active labels are listed.

status
    Print the status of a particular label, exit with a 0 status if the service exists and is still considered to be running. Exit with 1 if the service exists but is considered to be stopped. Exit with 2 if the service does not exist. If multiple labels match, the worst condition found becomes the exit code.

    Scripts that use this feature can conveniently use the start directive to start any matching service that is considered stopped. The directive is a NOP for services that are considered to be running.

log The service demon monitors stdout/stderr output from programs it runs continuously and will remember the last ~8KB or so, which can be dumped via this directive.

logf
    This works the same as log but continues to monitor and dump the output until you ^C. In order to avoid potentially stalling the service under management, gaps may occur if the monitor is unable to keep up with the log output.

tailf
    This works similarly to logf but dumps fewer lines of log history before dovetailing into continuous monitoring.

logfile label [path]
    Re-open, set, or change the logfile path for the monitor, creating a new logfile if necessary. The logfile is created by the parent monitor (the one not running in a chroot or jail or as a particular user or group). This way the service under management cannot modify or destroy it.

    It is highly recommended that you specify an absolute path when changing the logfile. If you wish to disable the logfile, set it to /dev/null. Disabling the logfile does not prevent you from viewing the last ~8KB and/or monitoring any logged data.

help
    Display quick help for directives.

Description of nominal operation procctl(2) system call.

JAIL-SPECIFICATIONS
A simple jail just chroots into a directory, possibly mounts /dev, and allows all current IP bindings to be used. The service demon itself does not run in the jail, but will keep the jail intact across stop and start/restart operations by leaving a forked process intact inside. If the jail is destroyed, the service demon will re-create it if necessary on a start/restart. -k option may be used to specify additional parameters. Parameters are comma-delimited with no spaces. Values may be specified in the name=value format. For example: -k clean,ip=1.2.3.4,ip=5.6.7.8

clean
    The jail is handed a clean environment, similar to what jail(8) does.

ip=addr
    The jail is allowed to bind to the specified IP address. This option may be specified multiple times.

SIGNALS
Generally speaking signals should not be sent to a service demon. Instead, the command should be run with an appropriate directive to adjust running behavior. However, the service demon will act on signals as follows:

SIGTERM
    The service demon will execute the exit directive.

SIGHUP
    The service demon will execute the restart directive.

HISTORY
The svc utility first appeared in DragonFly 4.0.