2 Jump Start

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: