Scroll to navigation

netlink(7) Miscellaneous Information Manual netlink(7)

ИМЯ

netlink - обмен информацией между ядром и пользовательским пространством (AF_NETLINK)

СИНТАКСИС

#include <asm/types.h>
#include <sys/socket.h>
#include <linux/netlink.h>
netlink_socket = socket(AF_NETLINK, socket_type, netlink_family);

ОПИСАНИЕ

Протокол netlink используется для передачи информации между ядром и процессами в пользовательском пространстве. Он состоит из стандартного, основанного на сокетах, интерфейса для процессов пользователя и внутреннего API ядра, предназначенного для модулей ядра. Внутренний интерфейс ядра в этой странице не описан. Кроме того, существует устаревший интерфейс netlink, работающий через символьные устройства netlink. Этот интерфейс здесь также не описан; он предназначен только для обратной совместимости.

Netlink обеспечивает для приложений сервис передачи датаграмм. В качестве socket_type могут использоваться типы сокетов как SOCK_RAW, так и SOCK_DGRAM. Несмотря на это, протокол netlink не различает датаграмные и неструктурированные (raw) сокеты.

По значению netlink_family выбирается модуль ядра или группа netlink для связи. В данный момент определены следующие семейства netlink:

Receives routing and link updates and may be used to modify the routing tables (both IPv4 and IPv6), IP addresses, link parameters, neighbor setups, queueing disciplines, traffic classes, and packet classifiers (see rtnetlink(7)).
Сообщения из однопроводной подсистемы.
Зарезервировано для будущих протоколов сокетов пространства пользователя.
Переправляет пакеты IPv4 из netfilter в пространство пользователя. Используется модулем ядра ip_queue. После долгого времени объявления устаревшим (предлагается использовать улучшенное свойство nfnetlink_queue), NETLINK_FIREWALL был удалён к Linux 3.5.
Запрашивает информации о сокетах различных семейств протоколов из ядра (смотрите sock_diag(7)).
An obsolete synonym for NETLINK_SOCK_DIAG.
Netfilter/iptables ULOG.
IPsec.
Уведомляет о событиях SELinux.
Open-iSCSI.
Ведёт контроль за системой.
Доступ к таблице FIB из пользовательского пространства.
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.
Подсистема netfilter.
Транспорты SCSI.
Infiniband RDMA.
Переправляет пакеты IPv6 из netfilter в пространство пользователя. Используется модулем ядра ip6_queue.
Сообщения маршрутизации DECnet.
Сообщения ядра в пользовательском пространстве.
Обобщённое семейство netlink для использования netlink.
Интерфейс netlink для запроса информации о зарегистрированных алгоритмах шифрования с помощью программного интерфейса ядра шифрования, а также настройки программного интерфейса ядра шифрования.

Сообщения netlink состоят из потока байтов с одним или несколькими заголовками nlmsghdr и присоединённой полезной нагрузкой. Доступ к потоку байтов нужно осуществлять только с помощью стандартных макросов NLMSG_*. Подробности смотрите в netlink(3).

В первом и всех последующих заголовках сообщений, состоящих из нескольких частей (несколько заголовков nlmsghdr с полезной нагрузкой в одном потоке байт), установлен флаг NLM_F_MULTI. Последний заголовок имеет тип NLMSG_DONE и этот флаг не устанавливается.

После каждого nlmsghdr следует полезная нагрузка:


struct nlmsghdr {


    __u32 nlmsg_len;    /* длина сообщения, включая заголовок */


    __u16 nlmsg_type;   /* тип содержимого сообщения */


    __u16 nlmsg_flags;  /* дополнительные флаги */


    __u32 nlmsg_seq;    /* номер в последовательности */


    __u32 nlmsg_pid;    /* ID порта отправителя */
};

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


     */
};

Семейство netlink обычно определяет и другие типы сообщений (см. соответствующие справочные страницы, например, rtnetlink(7) о NETLINK_ROUTE).

Стандартные биты флагов в nlmsg_flags
NLM_F_REQUEST Должен быть установлен у всех сообщений с запросами.
NLM_F_MULTI Сообщение является одной из частей длинного сообщения, которое заканчивается NLMSG_DONE.
NLM_F_ACK Request for an acknowledgement on success.
NLM_F_ECHO Послать эхо этого запроса.
Дополнительные биты флагов для запросов GET
NLM_F_ROOT Вернуть полную таблицу вместо одной записи.
NLM_F_MATCH Вернуть все записи, подходящие под критерий, переданный в содержимом сообщения. Пока не реализовано.
NLM_F_ATOMIC Вернуть атомарный образ (snapshot) таблицы.
NLM_F_DUMP Convenience macro; equivalent to (NLM_F_ROOT|NLM_F_MATCH).

Заметим, что NLM_F_ATOMIC требует мандата CAP_NET_ADMIN или эффективного UID 0.

Дополнительные биты флагов для запросов NEW
NLM_F_REPLACE Переписать существующий подходящий объект.
NLM_F_EXCL Не перезаписывать, если объект уже существует.
NLM_F_CREATE Создать объект, если он ещё не существует.
NLM_F_APPEND Добавить в конец списка объектов.

Поля nlmsg_seq и nlmsg_pid используются для отслеживания передачи сообщений. В nlmsg_pid указывается источник сообщения. Заметим, что нет связи 1:1 между nlmsg_pid и PID процесса, если сообщение возникло из сокета netlink. Дополнительную информацию ищите в разделе ФОРМАТЫ АДРЕСА.

Тип поля nlmsg_seq и nlmsg_pid скрыт в ядре netlink.

Netlink is not a reliable protocol. It tries its best to deliver a message to its destination(s), but may drop messages when an out-of-memory condition or other error occurs. For reliable transfer the sender can request an acknowledgement from the receiver by setting the NLM_F_ACK flag. An acknowledgement is an NLMSG_ERROR packet with the error field set to 0. The application must generate acknowledgements for received messages itself. The kernel tries to send an NLMSG_ERROR message for every failed packet. A user process should follow this convention too.

Однако, надёжная передача от ядра пользователю в любом случае невозможна. Ядро не может послать сообщение netlink, если заполнен буфер сокета: сообщение будет отброшено и ядро и пользовательский процесс будут иметь разное понятие о состоянии ядра. В обязанность приложения входит обнаружение такой ситуации (посредством ошибки ENOBUFS, возвращаемой recvmsg(2)) и выполнение восстановления синхронизации.

Форматы адресов

Структура sockaddr_nl описывает клиент netlink в пространстве пользователя или в ядре. Она может быть как одноадресной (передача информации только на один адрес), так и посылаться многоадресной группе netlink (значение nl_groups не равно нулю).


struct sockaddr_nl {


    sa_family_t     nl_family;  /* AF_NETLINK */


    unsigned short  nl_pad;     /* ноль */


    pid_t           nl_pid;     /* ID порта */


    __u32           nl_groups;  /* маска многоадресных групп */
};

nl_pid — одиночный адрес сокета netlink. Он всегда равен 0, если местом назначения является ядро. Для процесса пользовательского пространства значение nl_pid, обычно, равно PID процесса, которому принадлежит сокет назначения. Однако, значением nl_pid определяется сокет netlink, а не процесс. Если процессу принадлежит несколько сокетов netlink, то значение nl_pid может быть равно ID процесса только у одного сокета. Есть два способа назначить nl_pid сокету netlink. Если приложение задаёт nl_pid до вызова bind(2), то приложение само должно убедиться, что значение nl_pid уникально. Если приложение устанавливает его равным 0, то присвоение уникального значения выполняется ядром. Первому сокету netlink ядро назначает ID процесса, который его открыл, а всем последующим создаваемым процессом сокетам netlink, будет назначено уникальное значение nl_pid.

Значение nl_groups — это битовая маска, где каждый бит представляет номер группы netlink. Каждое семейство netlink имеет набор из 32-х многоадресных групп. Когда для сокета вызывается bind(2), то поле nl_groups структуры sockaddr_nl должно содержать битовую маску групп, которые оно хочет прослушивать. По умолчанию значение этого поля равно нулю, что означает, что многоадресные передачи не будут приниматься. Сокет может передавать многоадресные сообщения любой из многоадресных групп, присвоив nl_groups битовую маску групп, которым он желает передавать данные вызовом sendmsg(2) или при выполнении connect(2). Принимать или посылать сообщения многоадресной группы netlink могут только процессы с эффективным UID, равным 0, или имеющие мандат CAP_NET_ADMIN. Начиная с Linux 2.6.13, сообщения не могут вещаться в многоадресные группы. Любые ответы на сообщение, полученное многоадресной группой, должны быть отправлены посылающему процессу с PID и многоадресной группе. Некоторые подсистемы ядра Linux могут разрешать отправку и/или приём сообщений другим пользователям. Начиная с Linux 3.0, в группах NETLINK_KOBJECT_UEVENT, NETLINK_GENERIC, NETLINK_ROUTE и NETLINK_SELINUX разрешено принимать сообщения от других пользователей. Отправлять сообщения другим пользователям запрещено.

Параметры сокета

Для получения и задания параметров сокета netlink используйте вызовы getsockopt(2) и setsockopt(2), соответственно. Значение аргумента уровня параметров должно быть равно SOL_NETLINK. Если не указано обратного, значение optval является указателем на int.

Включить управляющие сообщения nl_pktinfo для приёма пакетов, чтобы получать расширенный номер группы назначения.
Присоединиться/покинуть группу, заданную в optval.
Получить все группы, в которых сокет является членом В аргументе optval передаётся указатель на __u32, а в optlen — размер массива. Массив заполняется полным набором членства сокета, а требуемый размер массива возвращается в optlen.
When not set, netlink_broadcast() only reports ESRCH errors and silently ignore ENOBUFS errors.
Данный флаг могут использовать слушающие одноадресные и широковещательные передачи, чтобы избежать ошибок ENOBUFS.
Если установлен, то этот сокет будет принимать уведомления netlink из всех сетевых пространств имён, имеющих назначенный nsid сетевого пространства имён, в котором был открыт сокет. Значение nsid посылается в пользовательское пространство во вспомогательных данных.
The kernel may fail to allocate the necessary room for the acknowledgement message back to user space. This option trims off the payload of the original netlink message. The netlink message header is still included, so the user can guess from the sequence number which message triggered the acknowledgement.

ВЕРСИИ

Сокетный интерфейс для netlink впервые появился в Linux 2.2.

Linux 2.0 поддерживал более примитивный интерфейс на основе устройств (который всё ещё доступен для совместимости). Этот устаревший интерфейс здесь не описывается.

ПРИМЕЧАНИЯ

В большинстве случаев лучше использовать netlink с помощью функций библиотек libnetlink или libnl, а не через низкоуровневый интерфейс ядра.

ОШИБКИ

Эта справочной странице не содержится всей необходимой информации.

ПРИМЕРЫ

В следующем примере создаётся сокет netlink семейства NETLINK_ROUTE, который будет прослушивать многоадресные группы RTMGRP_LINK (события о создании/удалении/включении/выключении сетевых интерфейсов) и RTMGRP_IPV4_IFADDR (события о добавлении/удалении адресов 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));

В следующем примере показано как отправить сообщение netlink ядру (pid 0). Заметим, что приложение должно управлять нумерацией сообщений, чтобы отслеживать подтверждения о доставке.


struct nlmsghdr *nh; /* отправляется nlmsghdr с полезной нагрузкой */
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));
sanl_family = AF_NETLINK;
nh->nlmsg_pid = 0;
nh->nlmsg_seq = ++sequence_number;
/* для запроса подтверждения от ядра, устанавливаем NLM_F_ACK */
nh->nlmsg_flags |= NLM_F_ACK;
sendmsg(fd, &msg, 0);

И последний пример о том, как выполнять чтение сообщения 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)) {


    /* конец сообщения из нескольких частей */


    if (nh->nlmsg_type == NLMSG_DONE)


        return;


    if (nh->nlmsg_type == NLMSG_ERROR)


        /* выполняем обработку ошибок */


    …


    /* разбираем полезную нагрузку */


    …
}

СМОТРИТЕ ТАКЖЕ

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

Информация о libnetlink

information about libnl

RFC 3549 «Linux Netlink as an IP Services Protocol»

ПЕРЕВОД

Русский перевод этой страницы руководства разработал(и) Alex Nik <rage.iz.me@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков.

5 февраля 2023 г. Справочные страницы Linux 6.03