3.1 Invoking shepherd

The shepherd program has the following synopsis:

shepherd [option…]

It accepts the following options:

-c file

Read and evaluate file as the configuration script on startup.

file is evaluated in the context of a fresh module where bindings from the (shepherd service) module and Guile’s (oop goops) are available, in addition to the default set of Guile bindings. In particular, this means that code in file may use register-services, the <service> class, and related tools (see Services).


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]

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.


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

-p [file]
-s 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 ID2, 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).


Synonym for --silent.



On GNU/Linux, the /run/user/uid directory is typically created by elogind or by systemd, which are available in most distributions.