2 Jump Start

The Shepherd comes with two main commands: shepherd, which is the daemon that manages services (see Invoking shepherd), and herd, the command to monitor and control shepherd (see Invoking herd). The shepherd command itself may run as an “init system”, also known as PID 11, where it manages system services, or as a user, where it manages user services.

As a user and system administrator, the herd command is your main entry point; it allows you to get an overview of the services and their status:

herd status

... to get detailed information about a specific service, including recently-logged messages:

herd status sshd

... and to start, stop, restart, enable, or disable services, among other possible actions:

herd start nginx
herd stop tor
herd disable tor
herd restart guix-daemon

Each service may depend on other services. Services and their dependencies form a graph, which you can view, for instance with the help of xdot, by running:

herd graph | xdot -

Since shepherd knows about these dependencies, the herd start nginx command above starts not just the nginx service, but also every service it depends on. Likewise, herd stop tor stops not just tor but also everything that depends on it.

Services may define custom actions in addition to start, stop, and the other actions mentioned above. For example, the log-rotation service has a custom files action to list log files subject to rotation (see Log Rotation Service):

herd files log-rotation

A special service is root, which is used for controlling the Shepherd itself (see The root Service). Its status action displays info about the shepherd process, including messages it recently logged, possibly on behalf of other services:

herd status root

The load action of root lets you dynamically load new service definitions from a configuration file, which we’ll discuss later; note that this action takes the file name as an extra argument:

herd load root ~/additional-services.scm

To view a log of service events, including the time at which each service was started or stopped, run:

herd log

Last, you can view documentation about services and their actions:

$ herd doc root
The root service is used to operate on shepherd itself.
$ herd doc root action power-off
power-off: Halt the system and turn it off.

That’s pretty much all there is to know from the user and system administrator viewpoint.

Packagers, distro developers, and advanced system administrator, certainly noticed that we haven’t talked about a crucial aspect for them: the configuration file for shepherd. That’s certainly the most interesting and unique bit of the Shepherd: configuration is a Scheme program. You do not need to be an expert in the Scheme programming language to write it though: for common uses, configuration is entirely declarative and contains the same information you would find in a systemd .service file or anything similar. You can define services that spawn a process, others that wait for incoming connections and pass it on to a daemon (inetd-style or systemd-style socket activation), as well as timed services that run a program periodically. See Service Examples, to get started.

What’s interesting is that you can go beyond the kind of services Shepherd offers you: You need a service that mounts/unmounts file systems? A service that sets up networking? One that runs a daemon in a container? This is where extensibility shines: you can write services that do this—and more. See Defining Services, for a reference of the programming interface to define services. And, whether or not you use Guix System, check out the variety of services it provides (see Services in GNU Guix Reference Manual).


Footnotes

(1)

In that case it is the first process started by the system, hence the process identifier (PID) 1.