DragonFly On-Line Manual Pages
SVC(8) DragonFly System Manager's Manual 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.
DragonFly 3.9 November 10, 2014 DragonFly 3.9