Serviços de Shepherd (Manual de referência do GNU Guix)

11.19.4 Serviços de Shepherd

The (gnu services shepherd) module provides a way to define services managed by the GNU Shepherd, which is the initialization system—the first process that is started when the system boots, also known as PID 1 (veja Introduction em 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 (veja Usando o sistema de configuração) results in a service graph like this:

You can actually generate such a graph for any operating system definition using the guix system shepherd-graph command (veja 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.

Tipo de dados: 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 (veja Invoking herd em The GNU Shepherd Manual). Veja Defining Services em The GNU Shepherd Manual, for details.

requirement (default: '())

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

one-shot? (default: #f)

Whether this service is one-shot. One-shot services stop immediately after their start action has completed. Veja Slots of services em The GNU Shepherd Manual, for more info.

respawn? (padrão: #t)

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

respawn-limit (default: #f)

Set a limit on how many times and how frequently a service may be restarted by Shepherd before it is disabled. Veja Defining Services em The GNU Shepherd Manual, for details.

respawn-delay (default: #f)

When true, this is the delay in seconds before restarting a failed service.

start (default: #~(const #t))

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

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

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…]

free-form (default: #f)

When set, this field replaces the start, stop, and actions fields. It is meant to be used when the service definition comes from some other source, typically the service collection provided by the Shepherd proper (veja Service Collection em The GNU Shepherd Manual).

For example, the snippet below defines a service for the Shepherd’s built-in REPL (read-eval-print loop) service (veja REPL Service em The GNU Shepherd Manual):

(shepherd-service
  (provision '(repl))
  (modules '((shepherd service repl)))
  (free-form #~(repl-service)))

In this case, the service object is returned by the repl-service procedure of the Shepherd, so all the free-form G-expression does is call that procedure. Note that the provision field must be consistent with the actual service provision.

auto-start? (default: #t)

Whether this service should be started automatically by the Shepherd. If it is #f the service has to be started manually with herd start.

documentation

A documentation string, as shown when running:

herd doc service-name

where service-name is one of the symbols in provision (veja Invoking herd em 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.

The example below defines a Shepherd service that spawns syslogd, the system logger from the GNU Networking Utilities (veja syslogd em GNU Inetutils):

(let ((config (plain-file "syslogd.conf" "…")))
  (shepherd-service
    (documentation "Run the syslog daemon (syslogd).")
    (provision '(syslogd))
    (requirement '(user-processes))
    (start #~(make-forkexec-constructor
               (list #$(file-append inetutils "/libexec/syslogd")
                     "--rcfile" #$config)
               #:pid-file "/var/run/syslog.pid"))
    (stop #~(make-kill-destructor))))

Key elements in this example are the start and stop fields: they are staged code snippets that use the make-forkexec-constructor procedure provided by the Shepherd and its dual, make-kill-destructor (veja Service De- and Constructors em The GNU Shepherd Manual). The start field will have shepherd spawn syslogd with the given option; note that we pass config after --rcfile, which is a configuration file declared above (contents of this file are omitted). Likewise, the stop field tells how this service is to be stopped; in this case, it is stopped by making the kill system call on its PID. Code staging is achieved using G-expressions: #~ stages code, while #$ “escapes” back to host code (veja Expressões-G).

Tipo de dados: 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 (veja Slots of services em 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. Veja Defining Services em The GNU Shepherd Manual, for more info on actions.

Procedure: shepherd-configuration-action

Return a configuration action to display file, which should be the name of the service’s configuration file.

It can be useful to equip services with that action. For example, the service for the Tor anonymous router (veja tor-service-type) is defined roughly like this:

(let ((torrc (plain-file "torrc" …)))
  (shepherd-service
    (provision '(tor))
    (requirement '(user-processes loopback syslogd))

    (start #~(make-forkexec-constructor
              (list #$(file-append tor "/bin/tor") "-f" #$torrc)
              #:user "tor" #:group "tor"))
    (stop #~(make-kill-destructor))
    (actions (list (shepherd-configuration-action torrc)))
    (documentation "Run the Tor anonymous network overlay.")))

Thanks to this action, administrators can inspect the configuration file passed to tor with this shell command:

cat $(herd configuration tor)

This can come in as a handy debugging tool!

Variável: 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 (veja Tipos de Service e Serviços, for an example). Each extension must pass a list of <shepherd-service>. Its value must be a shepherd-configuration, as described below.

Tipo de dados: shepherd-configuration

This data type represents the Shepherd’s configuration.

shepherd (default: shepherd): The Shepherd package to use.
services (default: '()): A list of <shepherd-service> to start. You should probably use the service extension mechanism instead (veja Serviços de Shepherd).

The following example specifies the Shepherd package for the operating system:

(operating-system
  ;; ...
  (services (append (list openssh-service-type))
            ;; ...
            %desktop-services)
  ;; ...
  ;; Use own Shepherd package.
  (essential-services
   (modify-services (operating-system-default-essential-services
                     this-operating-system)
     (shepherd-root-service-type config => (shepherd-configuration
                                            (inherit config)
                                            (shepherd my-shepherd))))))

Variável: shepherd-transient-service-type

This service type represents the Shepherd’s transient service, which lets you spawn commands in the background and interact with them as regular Shepherd service; it is similar to systemd-run.

For example, the command below spawns rsync in the background, in an environment where the SSH_AUTH_SOCK environment variable has the given value:

herd spawn transient -E SSH_AUTH_SOCK=$SSH_AUTH_SOCK -- \
  rsync -e ssh -vur . backup.example.org:

Veja Transient Service Maker em The GNU Shepherd Manual, for more info on the transient service.

Variável: shepherd-timer-service-type

This is the service type representing the Shepherd’s timer service, which lets you schedule the execution of commands, similar to the venerable at command. Here is an example:

herd schedule timer at 07:00 -- mpg123 Music/alarm.mp3

Veja Timer Service em The GNU Shepherd Manual, for more info on the timer service.

Variável: shepherd-system-log-service-type

This service implements a system log, reading messages applications send to /dev/log and writing them to files or terminals according to user-defined rules. It provides functionality traditionally implemented by syslogd programs.

The value of services of this type must be a system-log-configuration record, as described below.

Data Type: system-log-configuration

Available system-log-configuration fields are:

provision (default: (system-log syslogd)) (type: list-of-symbols): The name(s) of the system log service.
requirement (default: (root-file-system)) (type: list-of-symbols): Dependencies of the system log service.
kernel-log-file (type: gexp-or-string-or-false): File from which kernel messages are read, /dev/kmsg by default.
message-destination (default: #f) (type: gexp-or-false): This gexp must evaluate to a procedure that, when passed a log message, returns the list of files to write it to; #f is equivalent to using (default-message-destination-procedure). Veja System Log Service em The GNU Shepherd Manual, for information on how to write that procedure.
date-format (type: gexp-or-string): String or string-valued gexp specifying how to format timestamps in log file. It must be a valid string for strftime (veja Time em GNU Guile Reference Manual), including delimiting space—e.g., "%c " for a format identical to that of traditional syslogd implementations.
history-size (type: gexp-or-integer): Number of logging messages kept in memory for the purposes of making them available to herd status system-log.
max-silent-time (type: gexp-or-integer): Time after which a mark is written to log files if nothing was logged during that time frame.

Variável: %shepherd-root-service: This service represents PID 1.