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-root-service

Ce service représente le PID 1.