NETLINK(7)

NOM
netlink, PF_NETLINK - Communication entre noyau et utilisateur

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

netlink_socket = socket(PF_NETLINK, socket_type, netlink_family);

DESCRIPTION
Netlink sert à transférer des informations entre le 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 liens et peut être utilisé pour mettre à jour les tables de routage (IPv4 et IPv6), les adresses IP, les paramètres de liens, les configurations voisines, les disciplines de mise en file d'attente, les classes de trafic, et les classificateurs de paquets (voir rtnetlink(7)).

NETLINK_W1
    Messages de sous-systèmes 1-fil.

NETLINK_ARPD
    Pour gérer la table Arp dans l'espace utilisateur.

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

NETLINK_FIREWALL
    Transport de paquets IPv4 de netfilter vers l'espace utilisateur. Utilisé par le module noyau ip_queue.

NETLINK_INET_DIAG
    Surveillance de socket.

NETLINK_NFLOG
    Netfilter/iptables ULOG.

NETLINK_XFRM
    IPsec.

NETLINK_SELINUX
    Notifications d'événements SELinux.

NETLINK_AUDIT
    Audit.

NETLINK_FIB_LOOKUP
    Accès à la consultation FIB de l'espace utilisateur.

NETLINK_CONNECTOR
    Connecteur noyau. Voir Documentation/connector/* dans les sources du noyau pour plus d'informations.

NETLINK_NETFILTER
    Sous-système Netfilter.

NETLINK_IP6_FW
    Transports des paquets IPv6 de netfilter vers l'espace utilisateur. Utilisé par le module noyau ip6_queue.

NETLINK_DNRTMSG
    Routage DECnet des messages.

NETLINK_KOBJECT_UEVENT
    Messages noyau vers espace utilisateur.

NETLINK_GENERIC
    Famille générique netlink pour simplifier l'utilisation 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. Dans les messages multi-parties (en-têtes nlmsghdr multiples avec données utiles associées dans un flux d'octets) le premier et tous les en-têtes suivants ont l'attribut NLM_F_MULTI actif, sauf le dernier en-tête qui a le type NLMSG_DONE. Après chaque nlmsghdr, les données utiles suivent.
struct nlmsghdr {
    __u32 nlmsg_len;    /* Longueur y compris en-tête */
    __u16 nlmsg_type;   /* Contenu message            */
    __u16 nlmsg_flags;  /* Attributs supplémentaires  */
    __u32 nlmsg_seq;    /* Numéro de séquence         */
    __u32 nlmsg_pid;    /* PID du créateur socket     */
};
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 acquittement */
    struct nlmsghdr msg;  /* en-tête 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. Attributs standards dans nlmsg_flags
---------------------------------
NLM_F_REQUEST | Doit être positionné pour toutes les requêtes.
NLM_F_MULTI | Le message est multi-parties, terminée par
NLM_F_ACK | Demande d'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 aux critères passés dans le contenu du message. Pas encore implémenté. NLM_F_ATOMIC:Renvoyer une image instantanée de la table. NLM_F_DUMP:Macro pratique ; équivalente à (NLM_F_ROOT|NLM_F_MATCH).
Notez que nécessite la capacité CAP_NET_ADMIN ou un UID effectif égal à 0. 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 tracer les messages nlmsg_pid montre l'origine du message Notez qu'il n'y a pas de relation 1:1 entre nlmsg_pid et le PID du processus si le message est originaire d'une socket netlink. Voir la section FORMAT D'ADRESSE pour plus d'information. nlmsg_seq et nlmsg_pid sont opaques pour le coeur 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 eux-mêmes. Le noyau essaye d'envoyer un message NLMSG_ERROR pour chaque paquet échoué. Le processus utilisateur devrait suivre aussi cette convention. Toutefois, des transmissions fiables du noyau vers l'utilisateur sont impossibles dans tous les cas. Le noyau ne peut pas envoyer de message netlink si le tampon de la socket est plein : le message sera rejeté et le noyau et le processus utilisateur n'auront plus la même vue de l'état du noyau. C'est à l'application de détecter lorsque cela arrive (via l'erreur ENOBUFS renvoyée par recvmsg(2)) et resynchroniser.

  Format 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) ou décrire un groupe 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 zéro si la destination est dans le noyau. Pour un processus espace utilisateur, nl_pid est généralement le PID du processus propriétaire de la socket. Toutefois, nl_pid une socket netlink, pas un processus. Si un processus possède plusieurs sockets netlink, nl_pid ne peut être égal au PID pour au plus une socket. Il y a deux manières d'affecter nl_pid à une socket netlink. Si l'application fixe 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 prend soin de l'affecter. le noyau affecte le PID à la première socket netlink que le processus ouvre et affecte un nl_pid unique à chaque socket netlink que le processus crée par la suite. nl_groups est un masque de bits représentant les 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). Seul 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 supporte une interface 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 and NETLINK_FIB_LOOKUP est apparu 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 écoutera les groupes multicast RTMGRP_LINK (événements création/suppression/up/down d'interfaces réseau) et RTMGRP_IPV4_IFADDR (événements ajout/suppression d'adresses IPv4).
struct sockaddr_nl sa;
memset(&sa, 0, sizeof(sa));
snl.nl_family = AF_NETLINK;
snl.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 prendre soin des numéros de séquence des messages pour tracer correctement les acquittements.
struct nlmsghdr *nh;    /* The nlmsghdr with payload to send. */
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;
/* Request an ack from kernel by setting NLM_F_ACK. */
nh->nlmsg_flags |= NLM_F_ACK;
sendmsg(fd, &msg, 0);
Et le dernier exemple est relatif à la lecture d'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)) {
    /* 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),

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"

TRADUCTION

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 25 juillet 2003 et révisée le 17 décembre 2007.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 7 netlink ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.