A service is created by calling the
service procedure, from the
(shepherd service) module (automatically visible from your
configuration file), as in this example:
(service '(sshd ssh-daemon) ;for convenience, give it two names #:start (make-forkexec-constructor '("/usr/sbin/sshd" "-D") #:pid-file "/etc/ssh/sshd.pid") #:stop (make-kill-destructor) #:respawn? #t)
The example above creates a service with two names,
ssh-daemon. It is started by invoking
and it is considered up and running as soon as its PID file
/etc/ssh/sshd.pid is available. It is stopped by terminating the
sshd process. Finally, should
prematurely, it is automatically respawned. We will look at
#:stop later (see Service De- and Constructors), but first, here is the reference of the
procedure and its optional keyword arguments.
Return a new service with the given provision, a list of symbols denoting what the service provides. The first symbol in the list is the canonical name of the service, thus it must be unique.
The meaning of keyword arguments is as follows:
#:requirement is, like provision, a list of symbols that
specify services. In this case, they name what this service depends on:
before the service can be started, services that provide those symbols
must be started.
Note that every name listed in
#:requirement must be registered
so it can be resolved (see Service Registry).
Specify whether the service should be respawned by
If this slot has the value
#t, then, assuming the service has an
associated process (its “running value” is a PID), restart the service
if that process terminates.
There is a limit to avoid endless respawning: when the service gets
respawned “too fast”, it is disabled—see
Specify the limit that prevents
shepherd from respawning too
quickly the service marked with
#:respawn? #t. Its default value
(default-respawn-limit) (see Service De- and Constructors).
The limit is expressed as a pair of integers: the first integer,
n, specifies a number of consecutive respawns and the second
integer, t, specifies a number of seconds. If the service gets
respawned more than n times over a period of t seconds, it
is automatically disabled (see
service-enabled?). Once it is disabled, the service must be
explicitly re-enabled using
herd enable service before
it can be started again.
Consider the service below:
(service '(xyz) #:start (make-forkexec-constructor …) #:stop (make-kill-destructor) #:respawn? #t #:respawn-limit '(3 . 5))
The effect is that this service will be respawned at most 3 times over a period of 5 seconds; if its associated process terminates a fourth time during that period, the service will be marked as disabled.
Whether the service is a one-shot service. A one-shot service is a service that, as soon as it has been successfully started, is marked as “stopped.” Other services can nonetheless require one-shot services. One-shot services are useful to trigger an action before other services are started, such as a cleanup or an initialization action.
As for other services, the
start method of a one-shot service must
return a truth value to indicate success, and false to indicate failure.
Whether the service is a transient service. A transient service
is automatically unregistered when it terminates, be it because its
stop method is called or because its associated process
This is useful in the uncommon case of synthesized services that may not be restarted once they have completed.
Specify the constructor of the service, which will be called to
start the service. This must be a procedure that accepts any number of
arguments; those arguments will be those supplied by the user, for
instance by passing them to
herd start. If the starting
attempt failed, it must return
#f or throw an exception;
otherwise, the return value is stored as the running value of the
See Service De- and Constructors, for info on common service constructors.
This is the service destructor: a procedure of one or more
arguments that should stop the service. It is called whenever the user
explicitly stops the service; its first argument is the running value of
the service, subsequent arguments are user-supplied. Its return value
will again be stored as the running value, so it should
#f if it is now possible again to start the service at a
See Service De- and Constructors, for info on common service destructors.
The procedure to call when the process associated with the service
terminates. It is passed the service, the PID of the terminating
process, and its exit status, an integer as returned by
waitpid in GNU Guile Reference Manual).
The default handler is the
procedure, which respawns the service if applicable.
The additional actions that can be performed on the service when it is
running. A typical example for this is the
restart action. The
actions macro can be used to defined actions (see below).
A special service that every other service implicitly depends on is the
root (also known as
shepherd) service. See The
root Service, for more information.
Services and their dependencies form a graph. At the command-line, you can view that export a representation of that graph that can be consumed by any application that understands the Graphviz format, such as xdot:
herd graph | xdot -
Service actions are defined using the
actions macro, as
Create a value for the
#:actions parameter of
Each name is a symbol and each proc the corresponding
procedure that will be called to perform the action. A proc has
one argument, which will be the running value of the service.
(shepherd service) provides procedures to access
this information for a given service object:
Return the symbols provided by service.
Return the canonical name of service, which is the first
element of the list returned by
Return the list of services required by service as a list of symbols.
Return true if service is a one-shot/transient service.
Return true if service is meant to be respawned if its associated process terminates prematurely.
Return the respawn limit of service, expressed as a pair—see
Return the documentation (a string) of service.