3.1 Invoking shepherd ¶

The shepherd program has the following synopsis:

shepherd [option...]

When shepherd starts, it reads and evaluates a configuration file—actually a Scheme program that uses the Shepherd’s programming interface to define, register, and start services (see Defining Services). When it is started with superuser privileges, it tries to read /etc/shepherd.scm; when started as a unprivileged user, it looks for a file called $XDG_CONFIG_HOME/shepherd/init.scm. If the XDG_CONFIG_HOME environment variable is undefined, $HOME/.config/shepherd/init.scm is used instead (see Managing User Services). The --config option described below lets you choose a different file.

As the final “d” suggests, shepherd is a daemon that runs in the background, so you will not interact with it directly. After it is started, shepherd listens on a socket, usually /var/run/shepherd/socket; the herd tool sends commands to shepherd using this socket (see Invoking herd).

The shepherd command accepts the following options:

‘-c file’

‘--config=file’

Read and evaluate file as the configuration file on startup.

Scheme code in file is evaluated in the context of a fresh module where bindings from the (shepherd service) module are available, in addition to the default set of Guile bindings. It may typically perform three actions:

1. defining services using the service procedure (see Defining Services);
2. registering those services with register-services (see Service Registry);
3. starting some or all of those services with start-in-the-background (see Interacting with Services).

See Service Examples, for examples of what file might look like.

Note that file is evaluated asynchronously: shepherd may start listening for client connections (with the herd command) before file has been fully loaded. Errors in file such as service startup failures or uncaught exceptions do not cause shepherd to stop. Instead the error is reported, leaving users the opportunity to inspect service state and, for example, to load an updated config file with:

herd load root file

‘-I’ ¶

‘--insecure’

Do not check if the directory where the socket—our communication rendez-vous with herd—is located has permissions 700. If this option is not specified, shepherd will abort if the permissions are not as expected.

‘-l [file]’ ¶

‘--logfile[=file]’

Log output into file.

For unprivileged users, the default log file is $XDG_STATE_HOME/shepherd/shepherd.log with $XDG_STATE_HOME defaulting to $HOME/.local/state.

When running as root, the default behavior is to connect to /dev/log, the syslog socket (see Overview of Syslog in The GNU C Library Reference Manual). A syslog daemon, syslogd, is expected to read messages from there (see syslogd in GNU Inetutils).

When /dev/log is unavailable, for instance because syslogd is not running, as is the case during system startup and shutdown, shepherd falls back to the Linux kernel ring buffer, /dev/kmsg. If /dev/kmsg is missing, as is the case on other operating systems, it falls back to /dev/console.

‘--pid[=file]’

When shepherd is ready to accept connections, write its PID to file or to the standard output if file is omitted.

‘-s file’ ¶

‘--socket=file’

Receive further commands on the socket special file file. If this option is not specified, localstatedir/run/shepherd/socket is taken when running as root; when running as an unprivileged user, shepherd listens to /run/user/uid/shepherd/socket, where uid is the user’s numerical ID³, or to $XDG_RUNTIME_DIR/shepherd when the XDG_RUNTIME_DIR environment variable is defined.

If - is specified as file name, commands will be read from standard input, one per line, as would be passed on a herd command line (see Invoking herd).

‘-S’

‘--silent’

Don’t do output to stdout.

‘--quiet’

Synonym for --silent.