Next: , Previous: , Up: Top   [Contents][Index]


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 the 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 priviledges, 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. 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 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 service 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

The 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. (If you may at some point find this too restrictive because you want to use variants of the same service which are started in different ways, consider using different services for those variants instead, which all provide the same virtual service and thus conflict with each other, if this is desired. That’s one of the reasons why virtual services exist, after all.)

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 in order, the status action displays some general information about the service, like what it provides, what it depends on and with which other services it conflicts (because they provide a virtual service that is also provided by that particular service).

Another special action is list-actions, which displays a list of the additional actions a service provides; obviously, it can also be called when the service is not running. Services cannot provide their own implementation of list-actions.

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

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:


Next: , Previous: , Up: Top   [Contents][Index]