Loading

NOM

       netlink - Communication entre noyau et utilisateur (AF_NETLINK)

SYNOPSIS

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

       netlink_socket = socket(AF_NETLINK, socket_type, netlink_family);

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

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

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

       NETLINK_ROUTE
              Reçoit les modifications de routage et  de  lien  et  peut  être
              utilisé pour mettre à jour les tables de routage (IPv4 et IPv6),
              les adresses IP, les paramètres de lien, les  configurations  de
              voisins,  les politiques d’ordonnancement, les classes de trafic
              et les classificateurs de paquets (voir rtnetlink(7)).

       NETLINK_W1
              Messages du sous-système 1 fil (1‐wire).

       NETLINK_USERSOCK
              Réservé pour les futurs protocoles dans l’espace utilisateur.

       NETLINK_FIREWALL
              Transporte les paquets IPv4 de netfilter à l’espace utilisateur.
              Utilisé par le module noyau ip_queue.

       NETLINK_INET_DIAG
              Surveillance de sockets INET.

       NETLINK_NFLOG
              Messages ULOG de netfilter/iptables.

       NETLINK_XFRM
              IPsec.

       NETLINK_SELINUX
              Notifications d’événements SELinux.

       NETLINK_ISCSI
              Open-iSCSI.

       NETLINK_AUDIT
              Audit.

       NETLINK_FIB_LOOKUP
              Accès à la recherche FIB depuis l’espace utilisateur.

       NETLINK_CONNECTOR
              « Connector »   du   noyau.   Pour   plus  d’informations,  voir
              Documentation/connector/* dans les sources du noyau.

       NETLINK_NETFILTER
              Sous-système netfilter.

       NETLINK_IP6_FW
              Transporte les paquets IPv6 de netfilter à l’espace utilisateur.
              Utilisé par le module noyau ip6_queue.

       NETLINK_DNRTMSG
              Messages de routage DECnet.

       NETLINK_KOBJECT_UEVENT
              Messages du noyau à l’espace utilisateur.

       NETLINK_GENERIC
              Famille  netlink  générique  pour  une utilisation simplifiée de
              netlink.

       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_*.  Voir
       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 y compris en-tête. */
               __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;    /* PID du processus émetteur. */
           };

       nlmsg_type peut être l’un des types standards de  message :  NLMSG_NOOP
       message  à  ignorer,  NLMSG_ERROR  message  indiquant  une  erreur, son
       contenu est une  structure  nlmsgerr,  NLMSG_DONE  message  final  d’un
       ensemble multiparties.

           struct nlmsgerr {
               int error;            /* errno négatif ou 0 pour acquit */
               struct nlmsghdr msg;  /* en‐tête du message causant l’erreur */
           };

       Une famille netlink contient des types supplémentaires de message, voir
       la  page  de  manuel  appropriée,   par   exemple   rtnetlink(7)   pour
       NETLINK_ROUTE.

       Attribut standards dans nlmsg_flags
       -----------------------------------

       NLM_F_REQUEST   Doit être positionné pour toutes les requêtes.
       NLM_F_MULTI     Le  message  contient  plusieurs  parties,  et
                       terminé par NLMSG_DONE.
       NLM_F_ACK       Envoyer un acquittement de réussite.
       NLM_F_ECHO      Renvoyer cette requête.

       Attributs supplémentaires pour 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 une image instantanée de la table.
       NLM_F_DUMP     Macro équivalente à (NLM_F_ROOT|NLM_F_MATCH).

       Notez que NLM_F_ATOMIC nécessite la capacité CAP_NET_ADMIN  ou  un  UID
       effectif nul.

       Attributs supplémentaires pour requêtes NEW
       -------------------------------------------

       NLM_F_REPLACE   Écraser l’objet existant.
       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.
       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’une socket netlink. Voir la  section  FORMAT  DADRESSE
       pour plus d’informations.

       nlmsg_seq et nlmsg_pid sont opaques pour 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 du 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 essaye d’envoyer un
       message NLMSG_ERROR pour chaque paquet échoué. Le processus utilisateur
       devrait suivre aussi 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 de la 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 dadresse
       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;     /* PID. */
               __u32           nl_groups;  /* Masque groupes multicast. */
           };

       nl_pid est l’adresse unicast de la socket netlink. Elle vaut toujours 0
       si  la  destination  est  dans le noyau. Pour un processus utilisateur,
       nl_pid est généralement le PID du processus auquel appartient la socket
       de  destination. Cependant, nl_pid identifie une 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 une socket au plus. Il y a
       deux façons d’assigner nl_pid à une socket  netlink.  Si  l’application
       fixe nl_pid avant d’appeler bind(2), c’est à l’application de s’assurer
       que nl_pid est unique. Si l’application le fixe à 0, le noyau se charge
       de  lui  donner  une valeur. Le noyau donne le PID à la première socket
       netlink ouverte par le processus, et donne une valeur de nl_pid  unique
       à chaque socket netlink créée 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  la  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.  Une  socket  peut
       envoyer  un  message sur n’importe quel groupe multicast en remplissant
       le champ nl_groups avec un masque de bit des  groupes  visés,  lors  de
       l’appel  sendmsg(2)  ou lors du connect(2). Seuls les processus avec un
       UID effectif nul ou ayant la capacité CAP_NET_ADMIN peuvent envoyer  ou
       recevoir sur un groupe multicast netlink. Toute réponse pour un message
       reçu sur un groupe multicast doit être renvoyée au PID émetteur  et  au
       groupe multicast.

VERSIONS

       L’interface par socket de 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  valable  pour  compatibilité).  Cette
       interface obsolète n’est pas décrite ici.

       NETLINK_SELINUX est apparu dans Linux 2.6.4.

       NETLINK_AUDIT est apparu dans Linux 2.6.6.

       NETLINK_KOBJECT_UEVENT est apparu dans Linux 2.6.10.

       NETLINK_W1 et NETLINK_FIB_LOOKUP sont apparus dans Linux 2.6.13.

       NETLINK_INET_DIAG,  NETLINK_CONNECTOR et NETLINK_NETFILTER sont apparus
       dans Linux 2.6.14.

       NETLINK_GENERIC et NETLINK_ISCSI sont apparus dans Linux 2.6.15.

NOTES

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

BOGUES

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

EXEMPLE

       L’exemple  suivant crée une 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 prendre en compte correctement les acquits.

           struct nlmsghdr *nh;    /* L’en‐tête nlmsghdr avec contenu à envoyer. */
           struct sockaddr_nl sa;
           struct iovec iov = { (void *) nh, nh->nlmsg_len };
           struct msghdr msg;

           msg = { (void *)&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;
           /* Demander un acquit au noyau en fixant NLM_F_ACK. */
           nh->nlmsg_flags |= NLM_F_ACK;

           sendmsg(fd, &msg, 0);

       Le dernier exemple montre comment lire un message netlink.

           int len;
           char buf[4096];
           struct iovec iov = { buf, sizeof(buf) };
           struct sockaddr_nl sa;
           struct msghdr msg;
           struct nlmsghdr *nh;

           msg = { (void *)&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)) {
               /* Fin d’un message multiparties. */
               if (nh->nlmsg_type == NLMSG_DONE)
                   return;

               if (nh->nlmsg_type == NLMSG_ERROR)
                   /* Gestion d’erreurs. */
               ...

               /* Analyser le contenu. */
               ...
           }

VOIR AUSSI

       cmsg(3), netlink(3), capabilities(7), rtnetlink(7)

       ftp://ftp.inr.ac.ru/ip-routing/iproute2*   pour  des  informations  sur
       libnetlink.

       http://people.suug.ch/~tgr/libnl/ pour des informations sur libnl.

       RFC 3549 « Linux Netlink as an IP Services Protocol »

COLOPHON

       Cette page fait partie de  la  publication  3.23  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      être       trouvées       à       l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette  page  de  manuel  a  été  traduite et mise à jour par Christophe
       Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis  par
       Alain  Portal  <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement gérées par Julien Cristau <jcristau@debian.org> et l’équipe
       francophone de traduction de Debian.

       Veuillez  signaler  toute  erreur   de   traduction   en   écrivant   à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous pouvez toujours avoir accès à la version anglaise de  ce  document
       en utilisant la commande « man -L C <section> <page_de_man> ».