netlink(7) Miscellaneous Information Manual netlink(7) NOM netlink - Communication entre noyau et espace utilisateur (AF_NETLINK) SYNOPSIS #include #include #include netlink_socket = socket(AF_NETLINK, type_socket, famille_netlink); DESCRIPTION Netlink sert a transferer des informations entre les modules du noyau et les processus de l'espace utilisateur. Il consiste en une interface standard basee 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 documentee dans cette page de manuel. Il existe aussi une interface netlink obsolete utilisant les peripheriques caractere netlink, fournie uniquement pour retrocompatibilite et non documentee ici. Netlink est un service oriente 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 selectionne le module du noyau ou le groupe netlink avec qui communiquer. Les familles netlink actuellement determinees sont : NETLINK_ROUTE Reception des modifications de routage et de lien et utilisation possible pour mettre a jour les tables de routage (IPv4 et IPv6), les adresses IP, les parametres 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-systeme 1-Wire. NETLINK_USERSOCK Reserve pour les protocoles de socket dans l'espace utilisateur. NETLINK_FIREWALL (jusqu'a Linux 3.4 inclus) Transport des paquets IPv4 de netfilter vers l'espace utilisateur. Utilise par le module de noyau ip_queue. Apres une longue periode pendant laquelle il a ete considere comme obsolete (en faveur de la fonctionnalite plus moderne nfnetlink_queue), NETLINK_FIREWALL a ete retire 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 obsolete pour NETLINK_SOCK_DIAG. NETLINK_NFLOG (jusqu'a Linux 3.16 inclus) Messages ULOG de netfilter/iptables. NETLINK_XFRM IPsec. NETLINK_SELINUX (depuis Linux 2.6.4) Notifications d'evenements 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) Acces a 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-systeme netfilter. NETLINK_SCSITRANSPORT (depuis Linux 2.6.19) Transports SCSI. NETLINK_RDMA (depuis Linux 3.0) RDMA Infiniband. NETLINK_IP6_FW (jusqu'a Linux 3.4 inclus) Transport des paquets IPv6 de netfilter vers l'espace utilisateur. Utilise 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 generique pour une utilisation simplifiee de netlink. NETLINK_CRYPTO (depuis Linux 3.2) Interface netlink pour obtenir des informations a propos des chiffrements enregistres 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-tetes nlmsghdr et les contenus associes. Le flux d'octets ne doit etre accede qu'a travers les macros standards NLMSG_*. Consultez netlink(3) pour plus d'informations. Pour les messages multiparties, (plusieurs en-tetes nlmsghdr avec contenus associes dans un meme flux d'octets), tous les en-tetes ont l'attribut NLM_F_MULTI actif, sauf le dernier en-tete qui a le type NLMSG_DONE. Le contenu suit chaque nlmsghdr. struct nlmsghdr { __u32 nlmsg_len; /* Longueur du message en-tete compris. */ __u16 nlmsg_type; /* Type de contenu du message. */ __u16 nlmsg_flags; /* Attributs supplementaires. */ __u32 nlmsg_seq; /* Numero de sequence. */ __u32 nlmsg_pid; /* Identifiant du port emetteur. */ }; 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 generalement plus de types de message, consultez les pages de manuel appropriees, par exemple rtnetlink(7) pour NETLINK_ROUTE. Bits d'attribut standard dans nlmsg_flags ------------------------------------------------------------------------ NLM_F_REQUEST A positionner pour tous les messages de requete. NLM_F_MULTI Le message est une partie d'un message multipartie termine par NLMSG_DONE. NLM_F_ACK Requete d'un acquittement en cas de reussite. NLM_F_ECHO Repeter cette requete. Bits d'attribut supplementaires pour les requetes GET ------------------------------------------------------------------------ NLM_F_ROOT Renvoyer toute la table plutot qu'une seule entree. NLM_F_MATCH Renvoyer toutes les entrees correspondant au critere passe dans le contenu du message. Pas encore implemente. NLM_F_ATOMIC Renvoyer un instantane atomique de la table. NLM_F_DUMP Macro pratique ; equivalente a (NLM_F_ROOT|NLM_F_MATCH). Notez que NLM_F_ATOMIC necessite la capacite CAP_NET_ADMIN ou un UID effectif de zero. Bits d'attribut supplementaires pour requetes NEW ------------------------------------------------------------------------ NLM_F_REPLACE Remplacer l'objet existant correspondant. NLM_F_EXCL Ne pas remplacer l'objet s'il existe deja. NLM_F_CREATE Creer un objet s'il n'existe pas deja. NLM_F_APPEND Ajouter a la fin de la liste d'objets. nlmsg_seq et nlmsg_pid sont utilises pour suivre les messages. nlmsg_pid montre l'origine du message. Remarquez qu'il n'y a pas de relation d'equivalence 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 a destination mais peut abandonner des messages s'il n'a pas assez de memoire ou si une erreur se produit. Pour un transfert fiable, l'emetteur peut demander un acquittement au recepteur en activant l'attribut NLM_F_ACK. Un acquittement est un paquet NLMSG_ERROR avec le champ erreur a zero. L'application doit envoyer des acquittements pour les messages elle-meme. Le noyau essaie d'envoyer un message NLMSG_ERROR pour chaque paquet defectueux. 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 abandonne et le noyau et le processus utilisateur n'auront pas la meme information sur l'etat du noyau. C'est a l'application de detecter cette condition (via l'erreur ENOBUFS renvoyee par recvmsg(2)) et de resynchroniser. Formats d'adresse La structure sockaddr_nl decrit un client netlink dans l'espace utilisateur ou dans le noyau. Une sockaddr_nl peut etre soit unicast (un seul destinataire) soit envoyee a des groupes multicast netlink (nl_groups different de 0). struct sockaddr_nl { sa_family_t nl_family; /* AF_NETLINK */ unsigned short nl_pad; /* Zero */ 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 zero si la destination est dans le noyau. Pour un processus utilisateur, nl_pid est generalement 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 etre egal au PID de ce processus que pour un socket au plus. Il y a deux facons d'assigner nl_pid a un socket netlink. Si l'application definit nl_pid avant d'appeler bind(2), c'est a l'application de s'assurer que nl_pid est unique. Si l'application le definit a zero, 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 a chaque socket netlink cree par la suite. nl_groups est un masque de bits representant 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 desire ecouter. La valeur par defaut pour ce champ est zero, ce qui signifie qu'aucun groupe multicast ne sera recu. 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 vises, lors de l'appel sendmsg(2) ou lors du connect(2). Seuls les processus avec un UID effectif de zero ou ayant la capacite CAP_NET_ADMIN peuvent envoyer ou recevoir sur un groupe multicast netlink. Depuis Linux 2.6.13, les messages ne peuvent etre envoyes en broadcast vers plusieurs groupes. Toute reponse pour un message recu sur un groupe multicast doit etre renvoyee au PID emetteur et au groupe multicast. Certains sous-systemes du noyau Linux peuvent en plus autoriser d'autres utilisateurs a envoyer des messages. Dans Linux 3.0, les groupes NETLINK_KOBJECT_UEVENT, NETLINK_GENERIC, NETLINK_ROUTE et NETLINK_SELINUX autorisent d'autres utilisateurs a recevoir des messages. Aucun groupe ne permet a d'autres utilisateurs d'envoyer des messages. Options de socket Pour definir ou obtenir une option du socket netlink, appeler getsockopt(2) pour lire ou setsockopt(2) pour ecrire l'argument d'option de niveau defini a SOL_NETLINK. A moins d'etre note autre part, optval est un pointeur vers un int. NETLINK_PKTINFO (depuis Linux 2.6.14) Activer les messages de controle nl_pktinfo pour recevoir des paquets pour obtenir le numero de groupe de destination etendu. NETLINK_ADD_MEMBERSHIP NETLINK_DROP_MEMBERSHIP (since Linux 2.6.14) Joindre ou quitter un groupe specifie 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 necessaire est renvoyee dans optlen. NETLINK_BROADCAST_ERROR (depuis Linux 2.6.30) S'il n'est pas defini, netlink_broadcast() rapporte seulement les erreurs ESRCH et ignore silencieusement les erreurs ENOBUFS. NETLINK_NO_ENOBUFS (depuis Linux 2.6.30) Cet indicateur peut etre utilise par les modules d'ecoute (listener) unicast et broadcast pour eviter de recevoir des erreurs ENOBUFS. NETLINK_LISTEN_ALL_NSID (depuis Linux 4.2) S'il est defini, ce socket recevra des notifications netlink de tous les espaces de noms reseau qui ont un nsid assigne dans l'espace de noms reseau ou le socket a ete ouvert. Le nsid est envoye vers l'espace utilisateur a l'aide de donnees auxiliaires. NETLINK_CAP_ACK (depuis Linux 4.3) Le noyau peut echouer a allouer la place necessaire pour le message d'acquittement dans l'espace utilisateur. Cette option tronque le contenu du message netlink originel. L'en-tete du message netlink est toujours inclus, aussi l'utilisateur peut estimer a partir du numero de sequence quel message a declenche l'acquittement. VERSIONS L'interface socket pour netlink est une nouveaute dans Linux 2.2. Linux 2.0 avait une interface netlink plus primitive, basee sur un peripherique caractere (toujours disponible sous forme d'option de compatibilite). Cette interface obsolete n'est pas decrite ici. NOTES Il est souvent plus facile d'utiliser netlink a travers la bibliotheque libnetlink ou libnl qu'a l'aide de l'interface bas niveau du noyau. BOGUES Cette page de manuel n'est pas complete. EXEMPLES L'exemple suivant cree un socket netlink NETLINK_ROUTE qui ecoute les groupes multicast RTMGRP_LINK (evenements de creation/suppression/configuration/deconfiguration d'interface reseau) et RTMGRP_IPV4_IFADDR (evenements 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 gerer les numeros de sequence des messages pour correctement prendre en compte les acquittements. struct nlmsghdr *nh; /* The nlmsghdr with payload to send */ 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; /* Request an ack from kernel by setting 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 to avoid message truncation on platforms with page size > 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)) { /* The end of multipart message */ if (nh->nlmsg_type == NLMSG_DONE) return; if (nh->nlmsg_type == NLMSG_ERROR) /* Do some error handling */ ... /* Continue with parsing payload */ ... } 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 francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Paul Guillonneau Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 netlink(7)