This chapter gives a short overview of the Shepherd. It is enough if you just need the basic features of it. As it is not assumed that readers are familiar with all the involved issues, a very experienced user might be annoyed by the often very detailed descriptions in this introduction. Those users are encouraged to just skip to the reference section.
Note that all the full file names in the following text are based on
the assumption that you have installed the Shepherd with an empty prefix. If
your Shepherd installation for example resides in /usr/local
instead, add this directory name in front of the absolute file names
mentioned below.
When shepherd gets started, it reads and evaluates a
configuration file. When it is started with superuser privileges, it
tries to use /etc/shepherd.scm. When started as normal user, it
looks for a file called $XDG_CONFIG_HOME/shepherd/init.scm. If
the XDG_CONFIG_HOME environment variable is not defined,
$HOME/.config/shepherd/init.scm is used instead (see Managing User Services). With the option --config (or, for short,
-c), you can specify where to look instead. So if you want to
start shepherd with an alternative file, use one of the
following commands:
shepherd --config=/etc/shepherd.scm.old shepherd -c /etc/shepherd.scm.old
As the final “d” suggests, shepherd is just
a daemon that (usually) runs in the
background, so you will not interact with it directly. After it is
started, shepherd will listen on a socket special file, usually
/var/run/shepherd/socket, for further commands. You use the tool
herd to send these commands to shepherd. Usage of herd is simple and
straightforward: To start a service called apache, you use:
herd start apache
When you do this, all its dependencies will get resolved. For
example, a webserver is quite likely to depend on working networking,
thus it will depend on a service called networking. So if you
want to start apache, and networking is not yet running, it
will automatically be started as well. The current status of all the
services defined in the configuration file can be queried like this:
herd status
Or, to get additional details about each service, run:
herd detailed-status
In this example, this would show the networking and apache
services as started. If you just want to know the status of the
apache service, run:
herd status apache
You may also view a log of service events, including the time at which each service was started or stopped, by running:
herd log
Services and their dependencies form a graph, which you can view, for instance with the help of xdot, by running:
herd graph | xdot -
You can stop
a service and all the services that depend on it will be stopped.
Using the example above, if you stop networking, the service
apache will be stopped as well—which makes perfect sense,
as it cannot work without the network being up. To actually stop a
service, you use the following, probably not very surprising, command:
herd stop networking
There are two more actions you can perform on every service: the
actions enable and disable are used to prevent and allow
starting of the particular service. If a service is intended to be
restarted whenever it terminates (how this can be done will not be
covered in this introduction), but it is respawning too often in a
short period of time (by default 5 times in 5 seconds), it will
automatically be disabled. After you have fixed the problem that
caused it from being respawned too fast, you can start it again with
the commands:
herd enable foo herd start foo
But there is far more you can do than just that. Services can not
only simply depend on other services, they can also depend on
virtual services. A virtual service is a service that is
provided by one or more services additionally. For instance, a service
called exim might provide the virtual service
mailer-daemon. That could as well be provided by a service
called smail, as both are mailer-daemons. If a service needs
any mailer-daemon, no matter which one, it can just depend on
mailer-daemon, and one of those who provide it gets started (if
none is running yet) when resolving dependencies. The nice thing is
that, if trying to start one of them fails, shepherd will go on and try to
start the next one, so you can also use virtual services for
specifying fallbacks.
Additionally to all that, you can perform service-specific actions.
Coming back to our original example, apache is able to
reload its modules, therefore the action reload-modules might
be available:
herd reload-modules apache
Service-specific actions can only be used when the service is started, i.e. the only thing you can do to a stopped service is starting it. An exception exists, see below.
There are two actions which are special, because even if services
can implement them on their own, a default implementation is provided
by shepherd (another reason why they are special is that the default
implementations can be called even when the service is not running;
this inconsistency is just to make it more intuitive to get
information about the status of a service, see below).
These actions are restart and status. The default
implementation of restart calls stop and start on the
affected service, taking care to also restart any dependent services. The
default implementation of status displays some general information
about the service, like what it provides, and what it depends on.
A special service is root, which is used for controlling the
Shepherd itself. You can also reference to this service as
shepherd. It implements various actions. For example, the
status action displays which services are started and which ones
are stopped, whereas detailed-status has the effect of applying
the default implementation of status to all services one after
another. The load action is unusual insofar as it shows a
feature that is actually available to all services, but which we have
not seen yet: It takes an additional argument. You can use load
to load arbitrary code into the Shepherd at runtime, like this:
herd load shepherd ~/additional-services.scm
In the same vein the special action doc describes its service
when called without an argument or describes a service-specific action
when called with the action as the additional arguments. You can even
get the list of the service-specific actions a service provides when
using with the additional argument list-actions.
$ herd doc root The root service is used to operate on shepherd itself. $ herd doc root list-actions root (help status halt power-off load eval unload reload daemonize cd restart) $ herd doc root action power-off power-off: Halt the system and turn it off.
This is enough now about the herd and shepherd programs, we
will now take a look at how to configure the Shepherd. In the configuration
file, we need mainly the definition of services. We can also do
various other things there, like starting a few services already.
FIXME: Finish. For now, look at the doc/examples/ subdirectory.
...
Ok, to summarize:
shepherd is a daemon, herd the program that controls it.
root/shepherd service is used to control
shepherd itself.