All of the procedures listed below return procedures generated from the supplied arguments. These procedures take one argument in the case of destructors and no arguments in the case of constructors.
The returned procedure will execute command in a shell and
#t if execution was successful, otherwise
For convenience, it takes multiple arguments which will be
make-system-constructor, but returns
execution of the command was successful,
#t if not.
Return a procedure that forks a child process, closes all file
descriptors except the standard output and standard error descriptors,
sets the current directory to directory, sets the umask to
file-creation-mask unless it is
#f, changes the environment
to environment-variables (using the
sets the current user to user the current group to group
unless they are
#f and supplementary groups to
supplementary-groups unless they are
'(), and executes
command (a list of strings.) When
create-session? is true, the child process creates a new session with
setsid and becomes its leader. The result of the procedure will be
the PID of the child process.
Note: This will not work as expected if the process “daemonizes” (forks); in that case, you will need to pass
#:pid-file, as explained below.
When pid-file is true, it must be the name of a PID file associated with the process being launched; the return value is the PID once that file has been created. If pid-file does not show up in less than pid-file-timeout seconds, the service is considered as failing to start.
When log-file is true, it names the file to which the service’s standard output and standard error are redirected. log-file is created if it does not exist, otherwise it is appended to.
setrlimit procedure is applied on the entries in
resource-limits. For example, a valid value would be:
'((nproc 10 100) ;number of processes (nofile 4096 4096)) ;number of open file descriptors
Return a procedure that sends signal to the process group of the
PID given as argument, where signal defaults to
This does work together with respawning services,
because in that case the
stop method of the
class sets the
running slot to
#f before actually
calling the destructor; if it would not do that, killing the process
in the destructor would immediately respawn the service.
make-forkexec-constructor procedure builds upon the following
Run command as the current process from directory, with
file-creation-mask if it’s true, with rlimits, and with
environment-variables (a list of strings like
File descriptors 1 and 2 are kept as is or redirected to
either log-port or log-file
if it’s true, whereas file descriptor 0
(standard input) points to input-port or /dev/null; all other file descriptors
are closed prior to yielding control to command. When
create-session? is true, call
setsid in GNU Guile Reference Manual).
By default, command is run as the current user. If the user
keyword argument is present and not false, change to user
immediately before invoking command. user may be a string,
indicating a user name, or a number, indicating a user ID. Likewise,
command will be run under the current group, unless the
group keyword argument is present and not false, and
supplementary-groups is not
fork+exec-command does the same as
exec-command, but in
a separate process whose PID it returns.
This parameter (see Parameters in GNU Guile Reference Manual) specifies the default list of environment variables to be defined when the procedures above create a new process.
It must be a list of strings where each string has the format
name=value. It defaults to what
returns when the program starts (see
environ in GNU Guile Reference Manual).
This parameter (see Parameters in GNU Guile Reference Manual)
specified the default PID file timeout in seconds, when
#:pid-file is used (see above). It defaults to 5 seconds.
One may also define services meant to be started on demand. In that case, shepherd listens for incoming connections on behalf of the program that handles them; when it accepts an incoming connection, it starts the program to handle them. The main benefit is that such services do not consume resources until they are actually used, and they do not slow down startup.
These services are implemented following the protocol of the venerable
inetd “super server” (see inetd in GNU
Inetutils). Many network daemons can be invoked in “inetd mode”;
this is the case, for instance, of
sshd, the secure shell
server of the OpenSSH project. The Shepherd lets you define inetd-style
services, specifically those in
nowait mode where the daemon is
passed the newly-accepted socket connection while
in charge of listening.
Listening endpoints for such services are described as records built
Return a new endpoint called name of address, an address as
make-socket-address, with the given style and
When address is of type
AF_INET6, the endpoint is
IPv6-only. Thus, if you want a service available both on IPv4
and IPv6, you need two endpoints. For example, below is a list of
endpoints to listen on port 4444 on all the network interfaces, both in
IPv4 and IPv6 (“0.0.0.0” for IPv4 and “::0” for IPv6):
(list (endpoint (make-socket-address AF_INET INADDR_ANY 4444)) (endpoint (make-socket-address AF_INET6 IN6ADDR_ANY 4444)))
This is the list you would pass to
When address is of type
AF_UNIX, socket-owner and
socket-group are strings or integers that specify its ownership and that
of its parent directory; socket-directory-permissions specifies the
permissions for its parent directory.
The inetd service constructor takes a command and a list of such endpoints:
Return a procedure that opens sockets listening to endpoints, a list
of objects as returned by
endpoint, and accepting connections in the
Upon a client connection, a transient service running command is spawned. Only up to max-connections simultaneous connections are accepted; when that threshold is reached, new connections are immediately closed.
The remaining arguments are as for
Return a procedure that terminates an inetd service.
The last type is systemd-style services. Like inetd-style services, those are started on demand when an incoming connection arrives, but using the protocol devised by the systemd service manager and referred to as socket activation. The main difference with inetd-style services is that shepherd hands over the listening socket(s) to the daemon; the daemon is then responsible for accepting incoming connections. A handful of environment variables are set in the daemon’s execution environment (see below), which usually checks them using the libsystemd or libelogind client library helper functions. The constructor and destructor for systemd-style daemons are described below.
Return a procedure that starts command, a program and list of
argument, as a systemd-style service listening on endpoints, a list of
command is started on demand on the first connection attempt on one of
endpoints. It is passed the listening sockets for endpoints in
file descriptors 3 and above; as such, it is equivalent to an
socket unit. The following environment variables are set in its environment:
It is set to the PID of the newly spawned process.
It contains the number of sockets available starting from file descriptor 3—i.e., the length of endpoints.
The colon-separated list of endpoint names.
This must be paired with
Return a procedure that terminates a systemd-style service as created by