SYSTEMD-NOTIFY(1)

NOM
systemd-notify – Gestionnaire de service de notifications sur le déroulement de l’amorçage et d’autres modifications d’état de démon

SYNOPSIS

systemd-notify [OPTIONS...] [VARIABLE=VALEUR...]

systemd-notify --exec [OPTIONS...] [VARIABLE=VALUE...] ; -- {LIGNE_COMMANDE...}

systemd-notify --fork [OPTIONS...] -- {LIGNE_COMMANDE...}

DESCRIPTION

systemd-notify peut être appelé par des scripts de service pour notifier le gestionnaire de service appelant de modifications d’état. Il peut être utilisé pour envoyer des informations arbitraires, encodées dans une liste de chaines de type bloc d’environnement. Plus important, il peut être utilisé pour des notifications de l’avancement de l’amorçage.

C’est en grande partie une enveloppe de sd_notify() et procure cette fonctionnalité aux scripts d’interpréteur de commandes. Pour plus de détails, consulter sd_notify(3).

La ligne de commande peut comporter une liste de variables d’environnement à envoyer comme composante de la mise à jour d’états.

Notez que systemd refuse la réception de mises à jour de cette commande à moins que NotifyAccess= ne soit réglé de façon appropriée pour l’unité de service à partir de laquelle la commande est appelée. Consulter systemd.service(5) pour plus de détails.

Notez que les notifications sd_notify() ne peuvent être attribuées correctement aux unités que si le processus émetteur est toujours présent au moment où le gestionnaire de service traite le message ou si le processus émetteur fait explicitement l'objet d'un suivi d'exécution par le gestionnaire de service. Ce dernier cas est celui où le gestionnaire de service fourche initialement le processus, c’est-à-dire pour tous les processus qui correspondent à NotifyAccess=main ou NotifyAccess=exec. Inversement, si un programme auxiliaire de l’unité envoie un message sd_notify() et quitte immédiatement, le gestionnaire de service peut ne pas pouvoir attribuer correctement le message à l’unité et, par conséquent, l’ignorer même si NotifyAccess=all est réglé pour elle. Pour corriger cela, systemd-notify attend jusqu’à ce que le message de notification soit traité par le gestionnaire de service. Lorsque l’option --no-block est utilisée, cette synchronisation pour la réception de notification est désactivée, et ainsi la situation de compétition susmentionnée peut se produire si le processus appelant n’est pas le gestionnaire de service ou n’est pas engendré par le gestionnaire de service.

systemd-notify essaie d’abord d’invoquer sd_notify() en prétendant détenir le PID du processus parent de systemd-notify (c’est-à-dire le processus appelant). Cela ne fonctionne que si cela est invoqué avec les privilèges suffisants. En cas d’échec, il se rabat sur une invocation sous son propre PID. Ce comportement est utile afin que, lorsque l’outil est invoqué par un script d’interpréteur de commandes, ce processus d’interpréteur — et pas le processus systemd-notify — apparaisse comme l’émetteur du message, ce qui est ensuite utile si le processus d’interpréteur est le processus principal d’un service, à cause des limitations de NotifyAccess=all. Utilisez le commutateur --pid= pour ajuster ce comportement.

OPTIONS

Les options suivantes sont comprises :

--ready
    Informer le gestionnaire de service appelant du démarrage du service ou de l’achèvement du rechargement de configuration. Cela est équivalent à systemd-notify READY=1. Pour plus de détails sur la sémantique de cette option, consulter sd_notify(3).

--reloading
    Informer le gestionnaire de service appelant du début du cycle de rechargement de configuration. Cela est équivalent à systemd-notify RELOADING=1 (mais implicitement définit le champ MONOTONIC_USEC= de la manière requise pour les services Type=notify-reload, consulter systemd.service(5) pour plus de détails). Pour plus de détails sur la sémantique de cette option, consulter sd_notify(3).

    Ajouté dans la version 253.

--stopping
    Informer le gestionnaire de service appelant du début de la phase d’extinction du service. Cela est équivalent à systemd-notify STOPPING=1. Pour plus de détails sur la sémantique de cette option, consulter sd_notify(3).

    Ajouté dans la version 253.

--pid=
    Informer le gestionnaire de service sur le PID principal du service. Cette option prend un PID comme argument. Si l’argument indiqué est « auto » ou s’il est omis, le PID du processus invoquant systemd-notify est utilisé, sauf si c’est le gestionnaire de service. Si l’argument indiqué est « self », le PID de la commande systemd-notify elle-même est utilisé et si « parent » est indiqué, le PID du processus appelant est utilisé — même si c’est le gestionnaire de service. --pid=auto est équivalent à systemd-notify --pid=$PID. Pour plus de détails sur la sémantique de cette option, consulter sd_notify(3).

    systemd-notify essaie d’abord d’invoquer sd_notify() en prétendant détenir le PID indiqué avec l’option --pid=. Cela ne fonctionne que si cela est invoqué avec les privilèges suffisants. En cas d’échec, il se rabat sur une invocation sous son propre PID. En réalité, cela signifie qu’une invocation avec privilèges de systemd-notify --pid= peut contourner les restrictions NotifyAccess=main ou NotifyAccess=exec appliquées à un service.

    Si cette option est utilisée par une invocation sans privilèges de systemd-notify par un processus qui devient le nouveau processus principal d’un service — et qui n’est pas le processus fourché par le gestionnaire de service (ou le processus principal actuel) —, alors il est essentiel de régler NotifyAccess=all dans le fichier d’unité de service, sinon la notification est ignorée pour des raisons de sécurité. Consulter systemd.service(5) pour plus de détails.

--uid=UTILISATEUR
    Définir l’ID d’utilisateur à partir duquel envoyer une notification. L’argument est un nom d’utilisateur UNIX ou un UID numérique. Si cette option est indiquée, le message de notification est envoyé avec l’UID spécifié comme expéditeur à la place de l’utilisateur sous lequel la commande a été invoquée. Cette option nécessite des privilèges suffisants pour pouvoir manipuler l’identité d’utilisateur du processus.

    Ajouté dans la version 237.

--status=
    Envoyer une chaine de forme libre et humainement lisible à partir du démon à destination du gestionnaire de service. Cette option prend une chaine comme argument. C’est équivalent à systemd-notify STATUS=.... Pour plus de détails sur la sémantique de cette option, consulter sd_notify(3). Cette information est affichée dans la sortie status de systemctl(1), entre autres endroits.

--booted
    Renvoyer 0 si le système a été amorcé avec systemd, une valeur différente de zéro autrement. Si cette option est passée, aucun message n’est envoyé. Cette option ne concerne donc pas les autres options. Pour plus de détails sur la sémantique de cette option, consulter sd_booted(3). Une autre façon de vérifier cet état est d’appeler systemctl(1) avec la commande is-system-running. Elle affiche « offline » si le système n’a pas été amorcé avec systemd, bien que la valeur de retour ait une signification différente.

--no-block
    Ne pas attendre de manière synchrone la fin de l’opération demandée. L’utilisation de cette option n’est recommandée seulement que lorsque systemd-notify est engendré par le gestionnaire de service ou quand le processus invoquant est engendré directement par le gestionnaire de service et possède suffisamment de privilèges pour permettre à systemd-notify d’envoyer la notification à son nom. L’envoi de notifications avec cette option peut provoquer des situations de compétition dans tous les autres cas.

    Ajouté dans la version 246.

--exec
    Si cette option est indiquée, systemd-notify exécute une autre ligne de commande après avoir terminé son opération, en remplaçant son propre processus. Si utilisée, la liste des affectations à inclure dans le message envoyé doit être suivie par un caractère « ; » (comme élément de séparation), suivi de la ligne de commande à exécuter. Cela permet le « chainage » de commandes, c’est-à-dire lancer une opération suivie immédiatement par une autre sans changer les PID.

    Remarquez que de nombreux interpréteurs de commandes interprètent « ; » comme leur propre séparateur de ligne de commande, par conséquent, quand systemd-notify est invoqué à partir d’un interpréteur, le point-virgule doit être protégé par « \; ».

    Ajouté dans la version 254.

--fd=
    Envoyer un descripteur de fichier avec le message de notification. Cela est utile lors d’une invocation dans des services qui ont le réglage FileDescriptorStoreMax= activé ; consulter systemd.service(5) pour plus de détails. Le descripteur de fichier spécifié doit être passé à systemd-notify lors de l’invocation. Cette option peut être utilisée plusieurs fois pour passer plusieurs descripteurs de fichier dans un seul message de notification.

    Pour se servir de cette fonctionnalité dans un interpréteur bash(1), utilisez une expression telle que la suivante :

        systemd-notify --fd=4 --fd=5 4</un/fichier 5</un/autre/fichier

    Ajouté dans la version 254.

--fdname=
    Définir un nom à affecter aux descripteurs de fichier passés à l’aide de l’option --fd= (voir ci-dessus). Cette option contrôle le champ « FDNAME= ». Ce réglage peut être spécifié une seule fois et s’applique à tous les descripteurs de fichier passés. Invoquez cet outil plusieurs fois dans le cas où plusieurs descripteurs de fichier ayant des noms différents doivent être passés.

    Ajouté dans la version 254.

--fork
    Au lieu d’envoyer un message de notification, fourcher une ligne de commande et attendre qu’un message « READY=1 » soit reçu d’elle. En d’autres termes : cela fait de systemd-notify le récepteur d’un message de notification à la place de l’émetteur, échangeant ainsi les rôles. Cela est utile pour fourcher rapidement un processus qui met en œuvre un protocole sd_notify() à partir d’un script d’interpréteur de commandes. La ligne de commande invoquée aura l’entrée standard et la sortie standard connectées à /dev/null, mais la sortie standard d’erreur sera héritée du processus invoqué. L’ID numérique de processus est écrit sur la sortie standard par systemd-notify (à moins que l’option --quiet ne soit spécifiée) et peut être utilisé pour terminer plus tard le processus fourché.

    Remarquez que les processus fourchés continueront probablement à s'exécuter après l’arrêt de systemd-notify, ce qui aboutira à ce qu’ils soient réapparentés au processus moissonneur le plus proche, c'est-à-dire généralement le gestionnaire de service propre à l’utilisateur ou du système.

    Remarquez que cette option ne doit pas être utilisée pour lancer des services complets ponctuellement ; utilisez plutôt systemd-run(1) dans ce cas.

    Remarquez aussi qu’invoqué avec cette option, systemd-notify termine avec succès sous deux conditions distinctes :

        1. systemd-notify a reçu une notification « READY=1 » d’un processus enfant qu’il vient de fourcher.

        2. Le processus enfant s’est terminé proprement (avec comme code de retour zéro) avant d’envoyer un « READY=1 ».

    Exemple d’utilisation :

        # PID=$(systemd-notify --fork -- ma_commande)
        ...
        kill "$PID"
        unset PID

    Ajouté dans la version 258.

--quiet, -q
    Ne pas indiquer l’ID numérique de processus quand l’option --fork est utilisée.

    Ajouté dans la version 258.

-h, --help
    Afficher un aide-mémoire succinct et quitter.

--version
    Afficher une information de version courte et quitter.

CODE DE RETOUR

En cas de succès, 0 est renvoyé, autrement, un code d'échec différent de zéro est renvoyé.

EXEMPLE

Exemple 1. Notification d’amorçage et mises à jour d’état

Simple démon d’interpréteur de commandes envoyant des notifications d’amorçage après avoir configurer son canal de communication. Pendant l’exécution, envoi de mises à jour d’état au système init :

    #!/bin/sh
    mkfifo /tmp/téléopérateur
    systemd-notify --ready --status="Attente de données..."
    while : ; do
            read -r a < /tmp/téléopérateur
            systemd-notify --status="Traitement de $a"
            # Faire quelque chose avec $a ...
            systemd-notify --status="Attente de données..."
    done

VOIR AUSSI

systemd(1), systemctl(1), systemd.unit(5), systemd.service(5), sd_notify(3), sd_booted(3)

TRADUCTION
La traduction française de cette page de manuel a été créée par Jean-Paul Guillonneau <guillonneau.jeanpaul@free.fr>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 (https://www.gnu.org/licenses/gpl-3.0.html) concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.