Services Shepherd (Manuel de référence de GNU Guix)

11.19.4 Services Shepherd

Le module (gnu services shepherd) fournit une manière de définir les services gérés par le GNU Shepherd, qui est le système d’initialisation — le premier processus démarré lorsque le système démarre, aussi connu comme étant le PID 1 (voir Introduction dans The GNU Shepherd Manual).

Les services dans le Shepherd peuvent dépendre les uns des autres. Par exemple, le démon SSH peut avoir besoin d’être démarré après le démon syslog, qui à son tour doit être démarré après le montage des systèmes de fichiers. Le système d’exploitation simple déclaré précédemment (voir Utiliser le système de configuration) crée un graphe de service comme ceci :

Vous pouvez générer un tel graphe pour n’importe quelle définition de système d’exploitation avec la commande guix system shepherd-graph (voir guix system shepherd-graph).

La variable %shepherd-root-service est un objet de service représentant le PID 1, de type shepherd-root-service-type ; il peut être étendu en lui passant des listes d’objets <shepherd-service>.

Type de données :shepherd-service

Le type de données représentant un service géré par le Shepherd.

provision

C’est une liste de symboles dénotant ce que le service fournit.

Ce sont les noms qui peuvent être passés à herd start, herd status et les commandes similaires (voir Invoking herd dans The GNU Shepherd Manual). Voir Defining Services dans The GNU Shepherd Manual, pour plus de détails.

requirement (par défaut : '())

Liste de symboles dénotant les services du Shepherd dont celui-ci dépend.

one-shot? (par défaut : #f)

Indique si ce service est ponctuel. Les services ponctuels s’arrêtent immédiatement à la fin de leur action start. Voir Slots of services dans The GNU Shepherd Manual, pour plus d’infos.

respawn? (par défaut : #t)

Indique s’il faut redémarrer le service lorsqu’il s’arrête, par exemple si le processus sous-jacent meurt.

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. Voir Defining Services dans 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 (par défaut : #~(const #f))

Les champs start et stop se réfèrent à la capacité du Shepherd de démarrer et d’arrêter des processus (voir Service De- and Constructors dans The GNU Shepherd Manual). Ils sont donnés comme des G-expressions qui sont étendues dans le fichier de configuration du Shepherd (voir G-Expressions).

actions (par défaut : '()) ¶

C’est une liste d’objets shepherd-action (voir plus bas) définissant des actions supportées par le service, en plus des actions start et stop standards. Les actions listées ici sont disponibles en tant que sous-commande de herd :

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 (voir Service Collection dans The GNU Shepherd Manual).

For example, the snippet below defines a service for the Shepherd’s built-in REPL (read-eval-print loop) service (voir REPL Service dans 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? (par défaut : #t)

Indique si ce service doit être démarré automatiquement par le Shepherd. Si la valeur est #f, le service doit être démarré manuellement avec herd start.

documentation

Une chaîne de documentation, montrée lorsqu’on lance :

herd doc service-name

où service-name est l’un des symboles dans provision (voir Invoking herd dans The GNU Shepherd Manual).

modules (par défaut : %default-modules)

C’est la liste des modules qui doivent être dans le contexte lorsque start et stop sont évalués.

L’exemple ci-dessous défini un service Shepherd qui lance syslogd, le démon de journalisation du système des utilitaires réseau de GNU (voir syslogd dans 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))))

Les éléments clés de cet exemple sont les champs start et stop : ce sont des bouts de code échelonné qui utilisent la procédure make-forkexec-constructor fournie par le Shepherd et son dual, make-kill-destructor (voir Service De- and Constructors dans The GNU Shepherd Manual). Le champ start fera créer un syslogd au shepherd avec les options données. Remarquez que nous passons config après --rcfile, qui est un fichier de configuration déclaré plus haut (le contenu de ce fichier a été omis). De même, le champ stop décrit comment ce service sera arrêté. Dans ce cas, il est arrêté par l’appel système kill sur son PID. Le code est échelonné par des G-expressions : #~ échelonne le code, tandis que #$ « descend » vers le code hôte (voir G-Expressions).

Type de données :shepherd-action

C’est le type de données qui définie des actions supplémentaires implémentées par un service Shepherd (voir au-dessus).

name

Symbole nommant l’action.

documentation

C’est une chaîne de documentation pour l’action. Elle peut être consultée avec :

herd doc service action action

procedure

Cela devrait être une gexp qui s’évalue en une procédure à au moins un argument, la « valeur de lancement » du service (voir Slots of services dans The GNU Shepherd Manual).

L’exemple suivant définie une action nommée dire-bonjour qui salue amicalement l’utilisateur :

(shepherd-action
  (name 'dire-bonjour)
  (documentation "Dit salut !")
  (procedure #~(lambda (running . args)
                 (format #t "Salut, l'ami ! arguments : ~s\n"
                         args)
                 #t)))

En supposant que cette action est ajoutée dans le service example, vous pouvez écrire :

# herd dire-bonjour example
Salut, l'ami ! arguments : ()
# herd dire-bonjour example a b c
Salut, l'ami ! arguments : ("a" "b" "c")

Comme vous pouvez le voir, c’est une manière assez sophistiquée de dire bonjour. Voir Defining Services dans The GNU Shepherd Manual, pour plus d’informations sur les actions.

Procédure :shepherd-configuration-action

Renvoie une action configuration pour afficher file, qui devrait être le nom du fichier de configuration du service.

Il peut être utile d’équiper les services avec cette action. Par exemple, le service pour le routeur anonyme Tor (voir tor-service-type) est défini globalement de cette façon :

(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.")))

Grâce à cette action, la personne administrant le système peut inspecter le fichier de configuration passé à tor avec cette commande shell :

cat $(herd configuration tor)

Cela peut être pratique pour déboguer !

Variable :shepherd-root-service-type

Le type de service pour le « service racine » du Shepherd — c.-à-d. le PID 1.

C’est le type de service que les extensions ciblent lorsqu’elles veulent créer un service shepherd (voir Types service et services, pour un exemple). Chaque extension doit passer une liste de <shepherd-service>. Sa valeur doit être un shepherd-configuration, décrit plus bas.

Type de données :shepherd-configuration

Ce type de données représente la configuration du Shepherd.

shepherd (par défaut : shepherd): Le paquet Shepherd à utiliser.
services (par défaut : '()): Une liste de <shepherd-service> à démarrer. Vous devriez probablement utiliser le mécanisme d’extensions des services à la place (voir Services Shepherd).

L’exemple suivant spécifie le paquet Shepherd pour le système d’exploitation :

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

Variable :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:

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

Variable :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

Voir Timer Service dans The GNU Shepherd Manual, for more info on the timer service.

Variable :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). Voir System Log Service dans 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 (voir Time dans 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.

Variable :%shepherd-root-service: Ce service représente le PID 1.