netlink

NOM

netlink – Communication entre noyau et espace utilisateur (AF_NETLINK)

SYNOPSIS

#include <asm/types.h>
#include <sys/socket.h>
#include <linux/netlink.h>

netlink_socket = socket(AF_NETLINK, type_socket, famille_netlink);

Netlink sert à transférer des informations entre les modules du noyau et les processus de l'espace utilisateur. Il consiste en une interface standard basée sur les sockets pour les processus en espace utilisateur et d'une API interne du noyau pour les modules du noyau. Cette interface du noyau n'est pas documentée dans cette page de manuel. Il existe aussi une interface netlink obsolète utilisant les périphériques caractère netlink, fournie uniquement pour rétrocompatibilité et non documentée ici.

Netlink est un service orienté datagramme. Les deux types SOCK_RAW et SOCK_DGRAM sont des valeurs possibles pour type_socket. Toutefois, le protocole netlink ne distingue pas les sockets raw et datagramme.

famille_netlink sélectionne le module du noyau ou le groupe netlink avec qui communiquer. Les familles netlink actuellement déterminées sont :

NETLINK_ROUTE: Réception des modifications de routage et de lien et utilisation possible pour mettre à jour les tables de routage (IPv4 et IPv6), les adresses IP, les paramètres de lien, les configurations de voisinage, les politiques d'ordonnancement, les classes de trafic et les classificateurs de paquets (consultez rtnetlink(7)).

NETLINK_W1 (Linux 2.6.13 to Linux 2.16.17): Messages du sous-système 1-Wire.

NETLINK_USERSOCK: Réservé pour les protocoles de socket dans l'espace utilisateur.

NETLINK_FIREWALL (jusqu’à Linux 3.4 inclus): Transport des paquets IPv4 de netfilter vers l’espace utilisateur. Utilisé par le module de noyau ip_queue. Après une longue période pendant laquelle il a été considéré comme obsolète (en faveur de la fonctionnalité plus moderne nfnetlink_queue), NETLINK_FIREWALL a été retiré dans Linux 3.5.

NETLINK_SOCK_DIAG (depuis Linux 3.3): Recherche d’informations sur les sockets de diverses familles de protocoles du noyau (consultez sock_diag(7)).

NETLINK_INET_DIAG (depuis Linux 2.6.14): Synonyme obsolète pour NETLINK_SOCK_DIAG.

NETLINK_NFLOG (jusqu’à Linux 3.16 inclus): Messages ULOG de netfilter/iptables.

NETLINK_XFRM: IPsec.

NETLINK_SELINUX (depuis Linux 2.6.4): Notifications d'événements SELinux.

NETLINK_ISCSI (depuis Linux 2.6.15): Open-iSCSI.

NETLINK_AUDIT (depuis Linux 2.6.6): Audit.

NETLINK_FIB_LOOKUP (depuis Linux 2.6.13): Accès à la recherche dans la FIB depuis l'espace utilisateur.

NETLINK_CONNECTOR (depuis Linux 2.6.14): Kernel connector. See Documentation/driver-api/connector.rst (or /Documentation/connector/connector.* in Linux 5.2 and earlier) in the Linux kernel source tree for further information.

NETLINK_NETFILTER (depuis Linux 2.6.14): Sous-système netfilter.

NETLINK_SCSITRANSPORT (depuis Linux 2.6.19): Transports SCSI.

NETLINK_RDMA (depuis Linux 3.0): RDMA Infiniband.

NETLINK_IP6_FW (jusqu’à Linux 3.4 inclus): Transport des paquets IPv6 de netfilter vers l'espace utilisateur. Utilisé par le module noyau ip6_queue.

NETLINK_DNRTMSG: Messages de routage DECnet.

NETLINK_KOBJECT_UEVENT (depuis Linux 2.6.10): Messages du noyau vers l'espace utilisateur.

NETLINK_GENERIC (depuis Linux 2.6.15): Famille netlink générique pour une utilisation simplifiée de netlink.

NETLINK_CRYPTO (depuis Linux 3.2): Interface netlink pour obtenir des informations à propos des chiffrements enregistrés avec l’API de chiffrement du noyau et pour permettre la configuration de l’API Crypto du noyau.

Les messages netlink consistent en un flux d'octets avec un ou plusieurs en-têtes nlmsghdr et les contenus associés. Le flux d'octets ne doit être accédé qu'à travers les macros standards NLMSG_*. Consultez netlink(3) pour plus d'informations.

Pour les messages multiparties, (plusieurs en‐têtes nlmsghdr avec contenus associés dans un même flux d'octets), tous les en-têtes ont l'attribut NLM_F_MULTI actif, sauf le dernier en-tête qui a le type NLMSG_DONE.

Le contenu suit chaque nlmsghdr.

struct nlmsghdr {
    __u32 nlmsg_len;    /* Longueur du message en-tête compris. */
    __u16 nlmsg_type;   /* Type de contenu du message. */
    __u16 nlmsg_flags;  /* Attributs supplémentaires. */
    __u32 nlmsg_seq;    /* Numéro de séquence. */
    __u32 nlmsg_pid;    /* Identifiant du port émetteur. */
};

nlmsg_type can be one of the standard message types: NLMSG_NOOP message is to be ignored, NLMSG_ERROR message signals an error and the payload contains an nlmsgerr structure, NLMSG_DONE message terminates a multipart message. Error messages get the original request appended, unless the user requests to cap the error message, and get extra error data if requested.

struct nlmsgerr {
    int error;        /* Negative errno or 0 for acknowledgements */
    struct nlmsghdr msg;  /* Message header that caused the error */
    /*
     * followed by the message contents
     * unless NETLINK_CAP_ACK was set
     * or the ACK indicates success (error == 0).
     * For example Generic Netlink message with attributes.
     * message length is aligned with NLMSG_ALIGN()
     */
    /*
     * followed by TLVs defined in enum nlmsgerr_attrs
     * if NETLINK_EXT_ACK was set
     */
};

Une famille netlink contient généralement plus de types de message, consultez les pages de manuel appropriées, par exemple rtnetlink(7) pour NETLINK_ROUTE.

Bits d’attribut standard dans nlmsg_flags

NLM_F_REQUEST	À positionner pour tous les messages de requête.
NLM_F_MULTI	Le message est une partie d’un message multipartie terminé par NLMSG_DONE.
NLM_F_ACK	Requête d’un acquittement en cas de réussite.
NLM_F_ECHO	Répéter cette requête.

Bits d’attribut supplémentaires pour les requêtes GET

NLM_F_ROOT	Renvoyer toute la table plutôt qu'une seule entrée.
NLM_F_MATCH	Renvoyer toutes les entrées correspondant au critère passé dans le contenu du message. Pas encore implémenté.
NLM_F_ATOMIC	Renvoyer un instantané atomique de la table.
NLM_F_DUMP	Macro pratique ; équivalente à (NLM_F_ROOT\|NLM_F_MATCH).

Notez que NLM_F_ATOMIC nécessite la capacité CAP_NET_ADMIN ou un UID effectif de zéro.

Bits d’attribut supplémentaires pour requêtes NEW

NLM_F_REPLACE	Remplacer l'objet existant correspondant.
NLM_F_EXCL	Ne pas remplacer l'objet s'il existe déjà.
NLM_F_CREATE	Créer un objet s'il n'existe pas déjà.
NLM_F_APPEND	Ajouter à la fin de la liste d'objets.

nlmsg_seq et nlmsg_pid sont utilisés pour suivre les messages. nlmsg_pid montre l'origine du message. Remarquez qu'il n'y a pas de relation d'équivalence entre nlmsg_pid et le PID du processus si le message vient d'un socket netlink. Consultez la section FORMAT D'ADRESSE pour plus d'informations.

nlmsg_seq et nlmsg_pid sont opaques pour le noyau de netlink.

Netlink n'est pas un protocole fiable. Il fait de son mieux pour conduire les messages à destination mais peut abandonner des messages s'il n'a pas assez de mémoire ou si une erreur se produit. Pour un transfert fiable, l'émetteur peut demander un acquittement au récepteur en activant l'attribut NLM_F_ACK. Un acquittement est un paquet NLMSG_ERROR avec le champ erreur à zéro. L'application doit envoyer des acquittements pour les messages elle-même. Le noyau essaie d'envoyer un message NLMSG_ERROR pour chaque paquet défectueux. Le processus utilisateur doit aussi suivre cette convention.

Cependant, garantir des transmissions fiables entre le noyau et l'espace utilisateur est impossible. Le noyau ne peut pas envoyer de message netlink si le tampon du socket est plein : le message sera abandonné et le noyau et le processus utilisateur n'auront pas la même information sur l'état du noyau. C'est à l'application de détecter cette condition (via l'erreur ENOBUFS renvoyée par recvmsg(2)) et de resynchroniser.

Formats d'adresse

La structure sockaddr_nl décrit un client netlink dans l'espace utilisateur ou dans le noyau. Une sockaddr_nl peut être soit unicast (un seul destinataire) soit envoyée à des groupes multicast netlink ( nl_groups différent de 0).

struct sockaddr_nl {
    sa_family_t     nl_family;  /* AF_NETLINK */
    unsigned short  nl_pad;     /* Zéro */
    pid_t           nl_pid;     /* ID de port */
    __u32           nl_groups;  /* Masque de groupes multicast */
};

nl_pid est l'adresse unicast du socket netlink. Elle vaut toujours zéro si la destination est dans le noyau. Pour un processus utilisateur, nl_pid est généralement le PID du processus auquel appartient le socket de destination. Cependant, nl_pid identifie un socket netlink, pas un processus. Si un processus a plusieurs sockets netlink, nl_pid ne peut être égal au PID de ce processus que pour un socket au plus. Il y a deux façons d'assigner nl_pid à un socket netlink. Si l'application définit nl_pid avant d'appeler bind(2), c'est à l'application de s'assurer que nl_pid est unique. Si l'application le définit à zéro, le noyau se charge de lui donner une valeur. Le noyau donne le PID au premier socket netlink ouvert par le processus et donne une valeur de nl_pid unique à chaque socket netlink créé par la suite.

nl_groups est un masque de bits représentant un ensemble de groupes netlink. Chaque famille netlink a un ensemble de 32 groupes multicast. Quand on appelle bind(2) sur le socket, le champ nl_groups de la structure sockaddr_nl doit contenir un masque de bits des groupes que l'on désire écouter. La valeur par défaut pour ce champ est zéro, ce qui signifie qu'aucun groupe multicast ne sera reçu. Un socket peut envoyer un message sur n'importe quel groupe multicast en remplissant le champ nl_groups avec un masque de bits des groupes visés, lors de l'appel sendmsg(2) ou lors du connect(2). Seuls les processus avec un UID effectif de zéro ou ayant la capacité CAP_NET_ADMIN peuvent envoyer ou recevoir sur un groupe multicast netlink. Depuis Linux 2.6.13, les messages ne peuvent être envoyés en broadcast vers plusieurs groupes. Toute réponse pour un message reçu sur un groupe multicast doit être renvoyée au PID émetteur et au groupe multicast. Certains sous-systèmes du noyau Linux peuvent en plus autoriser d'autres utilisateurs à envoyer des messages. Dans Linux 3.0, les groupes NETLINK_KOBJECT_UEVENT, NETLINK_GENERIC, NETLINK_ROUTE et NETLINK_SELINUX autorisent d'autres utilisateurs à recevoir des messages. Aucun groupe ne permet à d'autres utilisateurs d'envoyer des messages.

Options de socket

Pour définir ou obtenir une option du socket netlink, appeler getsockopt(2) pour lire ou setsockopt(2) pour écrire l’argument d’option de niveau défini à SOL_NETLINK. À moins d’être noté autre part, optval est un pointeur vers un int.

NETLINK_PKTINFO (depuis Linux 2.6.14): Activer les messages de contrôle nl_pktinfo pour recevoir des paquets pour obtenir le numéro de groupe de destination étendu.

NETLINK_ADD_MEMBERSHIP, NETLINK_DROP_MEMBERSHIP (depuis Linux 2.6.14): Joindre ou quitter un groupe spécifié par optval.

NETLINK_LIST_MEMBERSHIPS (depuis Linux 4.2): Retrouver tous les groupes desquels un socket est membre. optval est un pointeur vers __u32 et optlen est la taille du tableau. Le tableau est rempli avec l’ensemble complet d’appartenances du socket et la taille de tableau nécessaire est renvoyée dans optlen.

NETLINK_BROADCAST_ERROR (depuis Linux 2.6.30): S'il n'est pas défini, netlink_broadcast() rapporte seulement les erreurs ESRCH et ignore silencieusement les erreurs ENOBUFS.

NETLINK_NO_ENOBUFS (depuis Linux 2.6.30): Cet indicateur peut être utilisé par les modules d’écoute (listener) unicast et broadcast pour éviter de recevoir des erreurs ENOBUFS.

NETLINK_LISTEN_ALL_NSID (depuis Linux 4.2): S'il est défini, ce socket recevra des notifications netlink de tous les espaces de noms réseau qui ont un nsid assigné dans l’espace de noms réseau où le socket a été ouvert. Le nsid est envoyé vers l’espace utilisateur à l’aide de données auxiliaires.

NETLINK_CAP_ACK (depuis Linux 4.3): Le noyau peut échouer à allouer la place nécessaire pour le message d’acquittement dans l’espace utilisateur. Cette option tronque le contenu du message netlink originel. L’en-tête du message netlink est toujours inclus, aussi l’utilisateur peut estimer à partir du numéro de séquence quel message a déclenché l’acquittement.

VERSIONS

L'interface socket pour netlink est une nouveauté dans Linux 2.2.

Linux 2.0 avait une interface netlink plus primitive, basée sur un périphérique caractère (toujours disponible sous forme d’option de compatibilité). Cette interface obsolète n'est pas décrite ici.

NOTES

Il est souvent plus facile d'utiliser netlink à travers la bibliothèque libnetlink ou libnl qu’à l’aide de l'interface bas niveau du noyau.

BOGUES

Cette page de manuel n'est pas complète.

EXEMPLES

L'exemple suivant crée un socket netlink NETLINK_ROUTE qui écoute les groupes multicast RTMGRP_LINK (événements de création/suppression/configuration/déconfiguration d'interface réseau) et RTMGRP_IPV4_IFADDR (évènements d'ajout/suppression d'adresses IPv4).

struct sockaddr_nl sa;

memset(&sa, 0, sizeof(sa));
sa.nl_family = AF_NETLINK;
sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;

fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
bind(fd, (struct sockaddr *) &sa, sizeof(sa));

L'exemple suivant montre comment envoyer un message netlink au noyau (PID 0). Notez que l'application doit gérer les numéros de séquence des messages pour correctement prendre en compte les acquittements.

struct nlmsghdr *nh;    /* Le nlmsghdr avec le contenu à envoyer */
struct sockaddr_nl sa;
struct iovec iov = { nh, nh->nlmsg_len };
struct msghdr msg;

msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
memset(&sa, 0, sizeof(sa));
sa.nl_family = AF_NETLINK;
nh->nlmsg_pid = 0;
nh->nlmsg_seq = ++sequence_number;
/* Requête d’un acquittement par le noyau en définissant NLM_F_ACK */
nh->nlmsg_flags |= NLM_F_ACK;

sendmsg(fd, &msg, 0);

Le dernier exemple montre comment lire un message netlink.

int len;
/* 8192 pour éviter la troncature sur les plateformes avec
   une taille de page > 4096 */
struct nlmsghdr buf[8192/sizeof(struct nlmsghdr)];
struct iovec iov = { buf, sizeof(buf) };
struct sockaddr_nl sa;
struct msghdr msg;
struct nlmsghdr *nh;

msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
len = recvmsg(fd, &msg, 0);

for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
     nh = NLMSG_NEXT (nh, len)) {
    /* La fin d’un message multipartie */
    if (nh->nlmsg_type == NLMSG_DONE)
        return;

    if (nh->nlmsg_type == NLMSG_ERROR)
        /* Réaliser une certaine gestion d’erreur */
    ...

    /* Continuer par l’analyse du contenu */
    ...
}

VOIR AUSSI

cmsg(3), netlink(3), capabilities(7), rtnetlink(7), sock_diag(7) Informations sur libnetlink information about libnl

RFC 3549 « Linux Netlink as an IP Services Protocol »

TRADUCTION

La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <[email protected]>, Thierry Vignaud <[email protected]>, François Micaux, Alain Portal <[email protected]>, Jean-Philippe Guérard <[email protected]>, Jean-Luc Coulon (f5ibh) <[email protected]>, Julien Cristau <[email protected]>, Thomas Huriaux <[email protected]>, Nicolas François <[email protected]>, Florentin Duneau <[email protected]>, Simon Paillard <[email protected]>, Denis Barbier <[email protected]>, David Prévot <[email protected]> et Jean-Paul Guillonneau <[email protected]>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 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 à [email protected]

5 février 2023

Pages du manuel de Linux 6.03