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).
In that case it is the first process started by the system, hence the process identifier (PID) 1.