Previous: , Up: Defining Services   [Contents][Index]


6.2.15.4 Shepherd Services

The (gnu services shepherd) module provides a way to define services managed by the GNU Shepherd, which is the GuixSD initialization system—the first process that is started when the system boots, also known as PID 1 (see Introduction in The GNU Shepherd Manual).

Services in the Shepherd can depend on each other. For instance, the SSH daemon may need to be started after the syslog daemon has been started, which in turn can only happen once all the file systems have been mounted. The simple operating system defined earlier (see Using the Configuration System) results in a service graph like this:

Typical shepherd service graph.

You can actually generate such a graph for any operating system definition using the guix system shepherd-graph command (see guix system shepherd-graph).

The %shepherd-root-service is a service object representing PID 1, of type shepherd-root-service-type; it can be extended by passing it lists of <shepherd-service> objects.

Data Type: shepherd-service

The data type representing a service managed by the Shepherd.

provision

This is a list of symbols denoting what the service provides.

These are the names that may be passed to herd start, herd status, and similar commands (see Invoking herd in The GNU Shepherd Manual). See the provides slot in The GNU Shepherd Manual, for details.

requirements (default: '())

List of symbols denoting the Shepherd services this one depends on.

respawn? (default: #t)

Whether to restart the service when it stops, for instance when the underlying process dies.

start
stop (default: #~(const #f))

The start and stop fields refer to the Shepherd’s facilities to start and stop processes (see Service De- and Constructors in The GNU Shepherd Manual). They are given as G-expressions that get expanded in the Shepherd configuration file (see G-Expressions).

actions (default: '())

This is a list of shepherd-action objects (see below) defining actions supported by the service, in addition to the standard start and stop actions. Actions listed here become available as herd sub-commands:

herd action service [arguments…]
documentation

A documentation string, as shown when running:

herd doc service-name

where service-name is one of the symbols in provision (see Invoking herd in The GNU Shepherd Manual).

modules (default: %default-modules)

This is the list of modules that must be in scope when start and stop are evaluated.

Data Type: shepherd-action

This is the data type that defines additional actions implemented by a Shepherd service (see above).

name

Symbol naming the action.

documentation

This is a documentation string for the action. It can be viewed by running:

herd doc service action action
procedure

This should be a gexp that evaluates to a procedure of at least one argument, which is the “running value” of the service (see Slots of services in The GNU Shepherd Manual).

The following example defines an action called say-hello that kindly greets the user:

(shepherd-action
  (name 'say-hello)
  (documentation "Say hi!")
  (procedure #~(lambda (running . args)
                 (format #t "Hello, friend! arguments: ~s\n"
                         args)
                 #t)))

Assuming this action is added to the example service, then you can do:

# herd say-hello example
Hello, friend! arguments: ()
# herd say-hello example a b c
Hello, friend! arguments: ("a" "b" "c")

This, as you can see, is a fairly sophisticated way to say hello. See Service Convenience in The GNU Shepherd Manual, for more info on actions.

Scheme Variable: shepherd-root-service-type

The service type for the Shepherd “root service”—i.e., PID 1.

This is the service type that extensions target when they want to create shepherd services (see Service Types and Services, for an example). Each extension must pass a list of <shepherd-service>.

Scheme Variable: %shepherd-root-service

This service represents PID 1.


Previous: , Up: Defining Services   [Contents][Index]