.\" This man page is Copyright (c) 1998 by Andi Kleen.
.\"
.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
.\" Subject to the GPL.
.\" %%%LICENSE_END
.\"
.\" Based on the original comments from Alexey Kuznetsov
.\" Modified 2005-12-27 by Hasso Tepper <hasso@estpak.ee>
.\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 1999 NAKANO Takeo all rights reserved.
.\" Translated 1999-12-06 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
.\" Updated 2001-04-04 by Yuichi SATO <ysato@h4.dion.ne.jp>, catch up to LDP v1.35
.\" Updated 2006-06-23 by Yuichi SATO <ysato444@yahoo.co.jp>, catch up to LDP v2.29
.\"
.TH NETLINK 7 2020\-06\-09 Linux "Linux Programmer's Manual"
.SH 名前
netlink \- カーネルとユーザー空間の通信 (AF_NETLINK)
.SH 書式
.nf
\fB#include <asm/types.h>\fP
\fB#include <sys/socket.h>\fP
\fB#include <linux/netlink.h>\fP
.PP
\fBnetlink_socket = socket(AF_NETLINK, \fP\fIsocket_type\fP\fB, \fP\fInetlink_family\fP\fB);\fP
.fi
.SH 説明
netlink はカーネルモジュールとユーザー空間のプロセス間で 情報をやりとりするために用いられる。 netlink は、ユーザープロセスに対しては
標準的なソケットベースのインターフェースを、 カーネルモジュールにはカーネルの内部 API を提供する。 カーネル内部のインターフェースについてはこの
man ページでは記述しない。 また、netlink キャラクターデバイスを用いた obsolete な netlink
インターフェースもあるが、これもこの文書では解説しない。 これは過去互換性のためだけに用意されている。
.PP
netlink はデータグラム指向のサービスである。 \fIsocket_type\fP には \fBSOCK_RAW\fP と \fBSOCK_DGRAM\fP
の両方とも指定可能である。 しかし netlink プロトコルはデータグラムと raw ソケットの区別をしない。
.PP
\fInetlink_family\fP は、通信するカーネルモジュールや netlink グループの選択に用いる。 現在割り当てられている netlink
ファミリーは以下の通り。
.TP 
\fBNETLINK_ROUTE\fP
ルーティングとリンクの更新を受信する。 (IPv4 と IPv6 両方の) ルーティングテーブル・ IP アドレス・リンクパラメーター・近傍設定
(neighbor setup)・ キューイングルール (queueing dicipline)・トラフィッククラス・
パケットのクラス分類の修正に用いることができるだろう (\fBrtnetlink\fP(7)  を見よ)。
.TP 
\fBNETLINK_W1\fP (Linux 2.6.13 から 2.16.17 まで)
単線 (1\-wire) のサブシステムからのメッセージ。
.TP 
\fBNETLINK_USERSOCK\fP
ユーザーモードソケットプロトコルのために予約されている。
.TP 
\fBNETLINK_FIREWALL\fP (Linux 3.4 以前)
.\" removed by commit d16cf20e2f2f13411eece7f7fb72c17d141c4a84
Transport IPv4 packets from netfilter to user space.  Used by \fIip_queue\fP
kernel module.  After a long period of being declared obsolete (in favor of
the more advanced \fInfnetlink_queue\fP feature), \fBNETLINK_FIREWALL\fP was
removed in Linux 3.5.
.TP 
\fBNETLINK_SOCK_DIAG\fP (Linux 3.3 以降)
.\" commit 7f1fb60c4fc9fb29fbb406ac8c4cfb4e59e168d6
Query information about sockets of various protocol families from the kernel
(see \fBsock_diag\fP(7)).
.TP 
\fBNETLINK_INET_DIAG\fP (Linux 2.6.14 以降)
An obsolete synonym for \fBNETLINK_SOCK_DIAG\fP.
.TP 
\fBNETLINK_NFLOG\fP (Linux 3.16 以前)
Netfilter/iptables ULOG.
.TP 
\fBNETLINK_XFRM\fP
.\" FIXME More details on NETLINK_XFRM needed.
IPsec.
.TP 
\fBNETLINK_SELINUX\fP (Linux 2.6.4 以降)
SELinux のイベント通知。
.TP 
\fBNETLINK_ISCSI\fP (Linux 2.6.15 以降)
.\" FIXME More details on NETLINK_ISCSI needed.
Open\-iSCSI.
.TP 
\fBNETLINK_AUDIT\fP (Linux 2.6.6 以降)
.\" FIXME More details on NETLINK_AUDIT needed.
監査 (audit) を行う。
.TP 
\fBNETLINK_FIB_LOOKUP\fP (Linux 2.6.13 以降)
.\" FIXME More details on NETLINK_FIB_LOOKUP needed.
ユーザー空間から FIB ルックアップにアクセスする。
.TP 
\fBNETLINK_CONNECTOR\fP (Linux 2.6.14 以降)
.\" commit baa293e9544bea71361950d071579f0e4d5713ed
カーネルコネクタ。より詳しい情報は Linux カーネルソースの \fIDocumentation/driver\-api/connector.rst\fP
(カーネル 5.2 以前では \fI/Documentation/connector/connector.*\fP) を参照すること。
.TP 
\fBNETLINK_NETFILTER\fP (Linux 2.6.14 以降)
.\" FIXME More details on NETLINK_NETFILTER needed.
netfilter サブシステム。
.TP 
\fBNETLINK_SCSITRANSPORT\fP (Linux 2.6.19 以降)
.\" commit 84314fd4740ad73550c76dee4a9578979d84af48
.\" FIXME More details on NETLINK_SCSITRANSPORT needed.
SCSI Transports.
.TP 
\fBNETLINK_RDMA\fP (Linux 3.0 以降)
.\" commit b2cbae2c248776d81cc265ff7d48405b6a4cc463
.\" FIXME More details on NETLINK_RDMA needed.
Infiniband RDMA.
.TP 
\fBNETLINK_IP6_FW\fP (Linux 3.4 以前)
IPv6 パケットを netfilter からユーザー空間へ転送する。 \fIip6_queue\fP カーネルモジュールで使用される。
.TP 
\fBNETLINK_DNRTMSG\fP
DECnet ルーティングメッセージ。
.TP 
\fBNETLINK_KOBJECT_UEVENT\fP (Linux 2.6.10 以降)
.\" FIXME More details on NETLINK_KOBJECT_UEVENT needed.
ユーザー空間へのカーネルメッセージ
.TP 
\fBNETLINK_GENERIC\fP (Linux 2.6.15 以降)
netlink を簡単に使用するための一般的な netlink ファミリー。
.TP 
\fBNETLINK_CRYPTO\fP (Linux 3.2 以降)
.\" commit a38f7907b926e4c6c7d389ad96cc38cec2e5a9e9
.\" Author: Steffen Klassert <steffen.klassert@secunet.com>
カーネル暗号 API で登録された暗号に関する情報を要求したり、 カーネル暗号 API の設定を行ったりするための netlink インターフェース。
.PP
netlink メッセージはバイトストリームからなり、 一つ以上の \fInlmsghdr\fP ヘッダーと、それに対応するペイロード (payload)
が含まれる。 バイトストリームには、標準の \fBNLMSG_*\fP マクロによってのみアクセスすべきである。 より詳しい情報は \fBnetlink\fP(3)
を見よ。
.PP
マルチパートメッセージ (一つ以上の \fInlmsghdr\fP ヘッダーと、それに対応するペイロードが 一つバイトストリームに含まれる) においては、
先頭のヘッダー・後続のヘッダーには \fBNLM_F_MULTI\fP フラグがセットされる。ただし最後のヘッダーだけは例外で、 \fBNLMSG_DONE\fP
タイプとなる。
.PP
それぞれの \fBnlmsghdr\fP の後にはペイロードが続く。
.PP
.in +4n
.EX
struct nlmsghdr {
    __u32 nlmsg_len;    /* ヘッダーを含むメッセージの長さ */
    __u16 nlmsg_type;   /* メッセージの内容のタイプ */
    __u16 nlmsg_flags;  /* 追加フラグ */
    __u32 nlmsg_seq;    /* シーケンス番号 */
    __u32 nlmsg_pid;    /* 送信者のポート ID */
};
.EE
.in
.PP
\fInlmsg_type\fP は標準のメッセージタイプのどれか一つである: \fBNLMSG_NOOP\fP メッセージは無視される。
\fBNLMSG_ERROR\fP メッセージはエラーを示し、ペイロードには \fInlmsgerr\fP 構造体が入る。 \fBNLMSG_DONE\fP
メッセージはマルチパートメッセージの終了を伝える。
.PP
.in +4n
.EX
struct nlmsgerr {
    int error;        /* 負または 0 の errno は応答を表す */
    struct nlmsghdr msg;  /* エラーを起こしたメッセージのヘッダー */
};
.EE
.in
.PP
ある netlink ファミリーで指定できるメッセージタイプは、 通常もっと多い。これらに関しては適切な man ページを見てほしい。 たとえば
\fBNETLINK_ROUTE\fP に関しては \fBrtnetlink\fP(7)  に書いてある。
.TS
tab(:);
l s
lB l.
\fInlmsg_flags\fP の標準フラグビット
_
NLM_F_REQUEST:要求メッセージ全てでセットされなければならない。
NLM_F_MULTI:T{
このメッセージはマルチパートメッセージの一部である。
マルチパートメッセージは \fBNLMSG_DONE\fP で終端する。
T}
NLM_F_ACK:成功した場合の応答を要求する。
NLM_F_ECHO:この要求をエコーする。
.TE
.\" No right adjustment for text blocks in tables
.TS
tab(:);
l s
lB l.
GET 要求における追加フラグビット
_
NLM_F_ROOT:単一のエントリーではなくテーブル全体を返す。
NLM_F_MATCH:T{
メッセージの内容で渡された基準 (criteria) にマッチする全てのエントリーを返す。
まだ実装されていない。
T}
NLM_F_ATOMIC:テーブルのアトミックなスナップショットを返す。
NLM_F_DUMP:T{
便利なマクロ。
.br
(NLM_F_ROOT|NLM_F_MATCH) と等価.
T}
.TE
.\" FIXME NLM_F_ATOMIC is not used anymore?
.PP
\fBNLM_F_ATOMIC\fP を使う場合は、 \fBCAP_NET_ADMIN\fP 権限を持つか実効ユーザー ID が 0
でなければならない点に注意すること。
.TS
tab(:);
l s
lB l.
NEW 要求における追加フラグビット
_
NLM_F_REPLACE:現存のオブジェクトを置換する。
NLM_F_EXCL:すでにオブジェクトがあったら置換しない。
NLM_F_CREATE:まだオブジェクトがなければ作成する。
NLM_F_APPEND:オブジェクトリストの最後に追加する。
.TE
.PP
\fInlmsg_seq\fP と \fInlmsg_pid\fP はメッセージの追跡に使用される。 \fInlmsg_pid\fP はメッセージの送信元を表す。
メッセージが netlink ソケットで送信されている場合、 \fInlmsg_pid\fP とプロセスの PID は 1:1
の関係ではない点に注意すること。 より詳しい情報は、 「\fBアドレスのフォーマット\fP」 のセクションを参照すること。
.PP
.\" FIXME Explain more about nlmsg_seq and nlmsg_pid.
\fInlmsg_seq\fP と \fInlmsg_pid\fP は netlink のコアには見えない (opaque)。
.PP
netlink は信頼性の高いプロトコルではない。 netlink はメッセージを行き先に届けるために最善を尽くすが、
メモリーが足りなかったりエラーが起こったりすると メッセージを取りこぼすこともある。 信頼性の高い転送を行いたいときは、
送信者は受信者に応答を要求することもできる。 これには \fBNLM_F_ACK\fP フラグをセットする。 応答は \fBNLMSG_ERROR\fP
パケットのエラーフィールドを 0 にしたものになる。 アプリケーションは自分自身のメッセージを受けたときには、 応答を生成しなければならない。
カーネルは失敗したパケットに対して、 \fBNLMSG_ERROR\fP メッセージを送ろうとする。 ユーザープロセスはこの慣習にも従う必要がある。
.PP
しかし、どのような場合でもカーネルからユーザーへの 信頼性の高い転送は不可能である。 ソケットバッファーが満杯の場合、カーネルは netlink
メッセージを送信できない。 メッセージは取りこぼされて、カーネルとユーザー空間プロセスは、 カーネルの状態についての同じビューを持つことができなくなる。
これが起こったこと (\fBrecvmsg\fP(2)  によって \fBENOBUFS\fP エラーが返される) を検知して再び同期させるのは、
アプリケーションの責任である。
.SS アドレスのフォーマット
\fIsockaddr_nl\fP 構造体はユーザー空間やカーネル空間で netlink クライアントを記述する。 \fIsockaddr_nl\fP
はユニキャスト (単一の接続先にだけ送られる) にもできるし、 netlink マルチキャストグループ (\fInl_groups\fP が 0 でない場合)
にも送ることができる。
.PP
.in +4n
.EX
struct sockaddr_nl {
    sa_family_t     nl_family;  /* AF_NETLINK */
    unsigned short  nl_pad;     /* 0 である */
    pid_t           nl_pid;     /* ポート ID */
    __u32           nl_groups;  /* マルチキャストグループマスク */
};
.EE
.in
.PP
\fInl_pid\fP は netlink ソケットのユニキャストアドレスである。 行き先がカーネルの場合は、常に 0 である。
ユーザー空間プロセスの場合、通常は \fInl_pid\fP は行き先のソケットを所有しているプロセスの PID である。 ただし、 \fInl_pid\fP
はプロセスではなく netlink ソケットを同定する。 プロセスが複数の netlink ソケットを所有する場合、 \fInl_pid\fP
は最大でも一つのソケットのプロセス ID としか等しくならない。 \fInl_pid\fP を netlink ソケットに割り当てる方法は 2 つある。
アプリケーションが \fBbind\fP(2)  を呼ぶ前に \fInl_pid\fP を設定する場合、 \fInl_pid\fP
が一意であることを確認するのはアプリケーションの責任となる。 アプリケーションが \fInl_pid\fP を 0
に設定した場合、カーネルがこの値を割り当てる。 カーネルはプロセスが最初にオープンした netlink ソケットに対してプロセス ID を割り当て、
それ以降にプロセスが作成した全ての netlink ソケットにも一意な \fInl_pid\fP を割り当てる。
.PP
.\" commit d629b836d151d43332492651dd841d32e57ebe3b
\fInl_groups\fP はビットマスクで、すべてのビットが netlink グループ番号を表す。
それぞれの netlink ファミリーは 32 のマルチキャストグループのセットを持つ。
それぞれの netlink ファミリーは 32 のマルチキャストグループの セットを持つ。
\fBbind\fP(2) がソケットに対して呼ばれると、 \fIsockaddr_nl\fP の \fInl_groups\fP
フィールドには listen したいグループのビットマスクがセットされる。
デフォルトの値は 0 で、マルチキャストを一切受信しない。
\fBsendmsg\fP(2) や \fBconnect\fP(2) によって、あるソケットからメッセージを
マルチキャストしたいときは、 \fInl_groups\fP に送信したいグループのビットマスク
をセットすればよい。
netlink マルチキャストグループに送信したり、これを listen したりできるのは、
実効ユーザー ID が 0 のプロセスか、 \fBCAP_NET_ADMIN\fP 権限を持つプロセスのみである。
Linux 2.6.13 以降では、メッセージを複数のグループへのブロードキャストすることはできない。
マルチキャストグループ向けメッセージを受信した場合、これ対する応答は
送り主の PID とマルチキャストグループとに送り返すべきである。
さらに、Linux のカーネルサブシステムによっては、
他のユーザーもメッセージの送受信ができる場合がある。
Linux 3.0 の時点では、
\fBNETLINK_KOBJECT_UEVENT\fP, \fBNETLINK_GENERIC\fP, \fBNETLINK_ROUTE\fP,
\fBNETLINK_SELINUX\fP グループでは他のユーザーがメッセージを受信することができる。
他のユーザーがメッセージを送信できるグループは存在しない。
.PP
.SS ソケットオプション
To set or get a netlink socket option, call \fBgetsockopt\fP(2)  to read or
\fBsetsockopt\fP(2)  to write the option with the option level argument set to
\fBSOL_NETLINK\fP.  Unless otherwise noted, \fIoptval\fP is a pointer to an
\fIint\fP.
.TP 
\fBNETLINK_PKTINFO\fP (Linux 2.6.14 以降)
.\"	commit 9a4595bc7e67962f13232ee55a64e063062c3a99
.\"	Author: Patrick McHardy <kaber@trash.net>
Enable \fBnl_pktinfo\fP control messages for received packets to get the
extended destination group number.
.TP 
\fBNETLINK_ADD_MEMBERSHIP\fP,\ \fBNETLINK_DROP_MEMBERSHIP\fP (Linux 2.6.14 以降)
.\"	commit 9a4595bc7e67962f13232ee55a64e063062c3a99
.\"	Author: Patrick McHardy <kaber@trash.net>
Join/leave a group specified by \fIoptval\fP.
.TP 
\fBNETLINK_LIST_MEMBERSHIPS\fP (Linux 4.2 以降)
.\"	commit b42be38b2778eda2237fc759e55e3b698b05b315
.\"	Author: David Herrmann <dh.herrmann@gmail.com>
Retrieve all groups a socket is a member of.  \fIoptval\fP is a pointer to
\fB__u32\fP and \fIoptlen\fP is the size of the array.  The array is filled with
the full membership set of the socket, and the required array size is
returned in \fIoptlen\fP.
.TP 
\fBNETLINK_BROADCAST_ERROR\fP (Linux 2.6.30 以降)
.\"	commit be0c22a46cfb79ab2342bb28fde99afa94ef868e
.\"	Author: Pablo Neira Ayuso <pablo@netfilter.org>
When not set, \fBnetlink_broadcast()\fP only reports \fBESRCH\fP errors and
silently ignore \fBENOBUFS\fP errors.
.TP 
\fBNETLINK_NO_ENOBUFS\fP (Linux 2.6.30 以降)
.\"	commit 38938bfe3489394e2eed5e40c9bb8f66a2ce1405
.\"	Author: Pablo Neira Ayuso <pablo@netfilter.org>
This flag can be used by unicast and broadcast listeners to avoid receiving
\fBENOBUFS\fP errors.
.TP 
\fBNETLINK_LISTEN_ALL_NSID\fP (Linux 4.2 以降)
.\"	commit 59324cf35aba5336b611074028777838a963d03b
.\"	Author: Nicolas Dichtel <nicolas.dichtel@6wind.com>
When set, this socket will receive netlink notifications from all network
namespaces that have an \fInsid\fP assigned into the network namespace where
the socket has been opened.  The \fInsid\fP is sent to user space via an
ancillary data.
.TP 
\fBNETLINK_CAP_ACK\fP (Linux 4.2 以降)
.\"	commit 0a6a3a23ea6efde079a5b77688541a98bf202721
.\"	Author: Christophe Ricard <christophe.ricard@gmail.com>
The kernel may fail to allocate the necessary room for the acknowledgment
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
acknowledgment.
.SH バージョン
netlink へのソケットインターフェースは Linux 2.2 で初めて登場した。
.PP
Linux 2.0 は、もっと原始的なデバイスベースの netlink インターフェースを サポートしていた (これも互換性のために今でも使用できる)。
古いインターフェースに関してはここでは記述しない。
.SH 注意
低レベルのカーネルインターフェースより、 \fIlibnetlink\fP または \fIlibnl\fP を通して netlink
を利用するほうが良いことが多い。
.SH バグ
この man ページは完成していない。
.SH 例
以下の例では、 \fBRTMGRP_LINK\fP (ネットワークインターフェースの create/delete/up/down イベント) と
\fBRTMGRP_IPV4_IFADDR\fP (IPv4 アドレスの add/delete イベント) マルチキャストグループを listen する
\fBNETLINK_ROUTE\fP netlink を作成している。
.PP
.in +4n
.EX
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));
.EE
.in
.PP
次の例では、netlink メッセージをカーネル (pid 0) に送る方法を示している。 応答を追跡する際の信頼性を高めるために、アプリケーションが
メッセージのシーケンス番号を正しく処理しなければならない点に注意すること。
.PP
.in +4n
.EX
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));
sa.nl_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);
.EE
.in
.PP
最後は、netlink メッセージの読み込みの例である。
.PP
.in +4n
.EX
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)
        /* 何らかのエラー処理を行う */
    ...

    /* ペイロードの解析を続ける */
    ...
}
.EE
.in
.SH 関連項目
\fBcmsg\fP(3), \fBnetlink\fP(3), \fBcapabilities\fP(7), \fBrtnetlink\fP(7),
\fBsock_diag\fP(7)
.PP
.UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2*
libnetlink に関する情報
.UE
.PP
.UR http://www.infradead.org\:/\(titgr\:/libnl/
libnl に関する情報
.UE
.PP
RFC 3549 "Linux Netlink as an IP Services Protocol"
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
\%https://www.kernel.org/doc/man\-pages/ に書かれている。