release/man7/netlink.7

   1 .\" t
   2 .\" This man page is Copyright (c) 1998 by Andi Kleen.
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" Subject to the GPL.
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" Based on the original comments from Alexey Kuznetsov
   9 .\" Modified 2005-12-27 by Hasso Tepper <hasso@estpak.ee>
  10 .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $
  11 .\"*******************************************************************
  12 .\"
  13 .\" This file was generated with po4a. Translate the source file.
  14 .\"
  15 .\"*******************************************************************
  16 .TH NETLINK 7 2013\-03\-15 Linux "Linux Programmer's Manual"
  17 .SH 名前
  18 netlink \- カーネルとユーザー空間の通信 (AF_NETLINK)
  19 .SH 書式
  20 .nf
  21 \fB#include <asm/types.h>\fP
  22 \fB#include <sys/socket.h>\fP
  23 \fB#include <linux/netlink.h>\fP
  24
  25 \fBnetlink_socket = socket(AF_NETLINK, \fP\fIsocket_type\fP\fB, \fP\fInetlink_family\fP\fB);\fP
  26 .fi
  27 .SH 説明
  28 netlink はカーネルモジュールとユーザー空間のプロセス間で 情報をやりとりするために用いられる。 netlink は、ユーザープロセスに対しては
  29 標準的なソケットベースのインターフェースを、 カーネルモジュールにはカーネルの内部 API を提供する。 カーネル内部のインターフェースについてはこの
  30 man ページでは記述しない。 また、netlink キャラクタデバイスを用いた obsolete な netlink
  31 インターフェースもあるが、これもこの文書では解説しない。 これは単に過去互換性のために用意されているものにすぎない。
  32
  33 netlink はデータグラム指向のサービスである。 \fIsocket_type\fP には \fBSOCK_RAW\fP と \fBSOCK_DGRAM\fP
  34 の両方とも指定可能である。 しかし netlink プロトコルはデータグラムと raw ソケットの区別をしない。
  35
  36 \fInetlink_family\fP は、通信するカーネルモジュールや netlink グループの選択に用いる。 現在割り当てられている netlink
  37 ファミリーは以下の通り。
  38 .TP
  39 \fBNETLINK_ROUTE\fP
  40 ルーティングとリンクの更新を受信する。 (IPv4 と IPv6 両方の) ルーティングテーブル・ IP アドレス・リンクパラメータ・近傍設定
  41 (neighbor setup)・ キューイングルール (queueing dicipline)・トラフィッククラス・
  42 パケットのクラス分類の修正に用いることができるだろう (\fBrtnetlink\fP(7)  を見よ)。
  43 .TP
  44 \fBNETLINK_W1\fP
  45 単線 (1\-wire) のサブシステムからのメッセージ。
  46 .TP
  47 \fBNETLINK_USERSOCK\fP
  48 ユーザーモードソケットプロトコルのために予約されている。
  49 .TP
  50 \fBNETLINK_FIREWALL\fP
  51 IPv4 パケットを netfilter からユーザー空間へ転送する。 \fIip_queue\fP カーネルモジュールで使用される。
  52 .TP
  53 \fBNETLINK_INET_DIAG\fP
  54 .\" FIXME More details on NETLINK_INET_DIAG needed.
  55 INET ソケットをモニタリングする。
  56 .TP
  57 \fBNETLINK_NFLOG\fP
  58 Netfilter/iptables ULOG.
  59 .TP
  60 \fBNETLINK_XFRM\fP
  61 .\" FIXME More details on NETLINK_XFRM needed.
  62 IPsec.
  63 .TP
  64 \fBNETLINK_SELINUX\fP
  65 SELinux のイベント通知。
  66 .TP
  67 \fBNETLINK_ISCSI\fP
  68 .\" FIXME More details on NETLINK_ISCSI needed.
  69 Open\-iSCSI.
  70 .TP
  71 \fBNETLINK_AUDIT\fP
  72 .\" FIXME More details on NETLINK_AUDIT needed.
  73 監査 (audit) を行う。
  74 .TP
  75 \fBNETLINK_FIB_LOOKUP\fP
  76 .\" FIXME More details on NETLINK_FIB_LOOKUP needed.
  77 ユーザー空間から FIB ルックアップにアクセスする。
  78 .TP
  79 \fBNETLINK_CONNECTOR\fP
  80 カーネルコネクタ。より詳しい情報は Linux カーネルソースの \fIDocumentation/connector/*\fP を参照すること。
  81 .TP
  82 \fBNETLINK_NETFILTER\fP
  83 .\" FIXME More details on NETLINK_NETFILTER needed.
  84 netfilter サブシステム。
  85 .TP
  86 \fBNETLINK_IP6_FW\fP
  87 IPv6 パケットを netfilter からユーザー空間へ転送する。 \fIip6_queue\fP カーネルモジュールで使用される。
  88 .TP
  89 \fBNETLINK_DNRTMSG\fP
  90 DECnet ルーティングメッセージ。
  91 .TP
  92 \fBNETLINK_KOBJECT_UEVENT\fP
  93 .\" FIXME More details on NETLINK_KOBJECT_UEVENT needed.
  94 ユーザー空間へのカーネルメッセージ
  95 .TP
  96 \fBNETLINK_GENERIC\fP
  97 netlink を簡単に使用するための一般的な netlink ファミリー。
  98 .PP
  99 netlink メッセージはバイトストリームからなり、 一つ以上の \fInlmsghdr\fP ヘッダと、それに対応するペイロード (payload)
 100 が含まれる。 バイトストリームには、標準の \fBNLMSG_*\fP マクロによってのみアクセスすべきである。 より詳しい情報は \fBnetlink\fP(3)
 101 を見よ。
 102
 103 マルチパートメッセージ (一つ以上の \fInlmsghdr\fP ヘッダと、それに対応するペイロードが 一つバイトストリームに含まれる) においては、
 104 先頭のヘッダ・後続のヘッダには \fBNLM_F_MULTI\fP フラグがセットされる。ただし最後のヘッダだけは例外で、 \fBNLMSG_DONE\fP
 105 タイプとなる。
 106
 107 それぞれの \fBnlmsghdr\fP の後にはペイロードが続く。
 108
 109 .in +4n
 110 .nf
 111 struct nlmsghdr {
 112     __u32 nlmsg_len;    /* ヘッダを含むメッセージの長さ */
 113     __u16 nlmsg_type;   /* メッセージの内容のタイプ */
 114     __u16 nlmsg_flags;  /* 追加フラグ */
 115     __u32 nlmsg_seq;    /* シーケンス番号 */
 116     __u32 nlmsg_pid;    /* 送信者のポート ID */
 117 };
 118 .fi
 119 .in
 120
 121 \fInlmsg_type\fP は標準のメッセージタイプのどれか一つである: \fBNLMSG_NOOP\fP メッセージは無視される。
 122 \fBNLMSG_ERROR\fP メッセージはエラーを示し、ペイロードには \fInlmsgerr\fP 構造体が入る。 \fBNLMSG_DONE\fP
 123 メッセージはマルチパートメッセージの終了を伝える。
 124
 125 .in +4n
 126 .nf
 127 struct nlmsgerr {
 128     int error;        /* 負または 0 の errno は応答を表す */
 129     struct nlmsghdr msg;  /* エラーを起こしたメッセージのヘッダ */
 130 };
 131 .fi
 132 .in
 133
 134 ある netlink ファミリーで指定できるメッセージタイプは、 通常もっと多い。これらに関しては適切な man ページを見てほしい。 たとえば
 135 \fBNETLINK_ROUTE\fP に関しては \fBrtnetlink\fP(7)  に書いてある。
 136 .TS
 137 tab(:);
 138 l s
 139 lB l.
 140 \fInlmsg_flags\fP の標準フラグビット
 141 _
 142 NLM_F_REQUEST:要求メッセージ全てでセットされなければならない。
 143 NLM_F_MULTI:T{
 144 このメッセージはマルチパートメッセージの一部である。
 145 マルチパートメッセージは \fBNLMSG_DONE\fP で終端する。
 146 T}
 147 NLM_F_ACK:成功した場合の応答を要求する。
 148 NLM_F_ECHO:この要求をエコーする。
 149 .TE
 150 .ad
 151 .sp 1
 152 .\" No right adjustment for text blocks in tables
 153 .na
 154 .TS
 155 tab(:);
 156 l s
 157 lB l.
 158 GET 要求における追加フラグビット
 159 _
 160 NLM_F_ROOT:単一のエントリではなくテーブル全体を返す。
 161 NLM_F_MATCH:T{
 162 メッセージの内容で渡された基準 (criteria) にマッチする全てのエントリを返す。
 163 まだ実装されていない。
 164 T}
 165 .\" FIXME NLM_F_ATOMIC is not used any more?
 166 NLM_F_ATOMIC:テーブルのアトミックなスナップショットを返す。
 167 NLM_F_DUMP:T{
 168 便利なマクロ。(NLM_F_ROOT|NLM_F_MATCH) と同じ。
 169 T}
 170 .TE
 171 .ad
 172 .sp 1
 173 \fBNLM_F_ATOMIC\fP を使う場合は、 \fBCAP_NET_ADMIN\fP 権限を持つか実効ユーザー ID が 0
 174 でなければならない点に注意すること。
 175 .na
 176 .TS
 177 tab(:);
 178 l s
 179 lB l.
 180 Additional flag bits for NEW requests
 181 _
 182 NLM_F_REPLACE:現存のオブジェクトを置換する。
 183 NLM_F_EXCL:すでにオブジェクトがあったら置換しない。
 184 NLM_F_CREATE:まだオブジェクトがなければ作成する。
 185 NLM_F_APPEND:オブジェクトリストの最後に追加する。
 186 .TE
 187 .ad
 188 .sp 1
 189 \fInlmsg_seq\fP と \fInlmsg_pid\fP はメッセージの追跡に使用される。 \fInlmsg_pid\fP はメッセージの送信元を表す。
 190 メッセージが netlink ソケットで送信されている場合、 \fInlmsg_pid\fP とプロセスの PID は 1:1
 191 の関係ではない点に注意すること。 より詳しい情報は、 「\fBアドレスのフォーマット\fP」 のセクションを参照すること。
 192
 193 .\" FIXME Explain more about nlmsg_seq and nlmsg_pid.
 194 \fInlmsg_seq\fP と \fInlmsg_pid\fP は netlink のコアには見えない (opaque)。
 195
 196 netlink は信頼性の高いプロトコルではない。 netlink はメッセージを行き先に届けるために最善を尽くすが、
 197 メモリが足りなかったりエラーが起こったりすると メッセージを取りこぼすこともある。 信頼性の高い転送を行いたいときは、
 198 送信者は受信者に応答を要求することもできる。 これには \fBNLM_F_ACK\fP フラグをセットする。 応答は \fBNLMSG_ERROR\fP
 199 パケットのエラーフィールドを 0 にしたものになる。 アプリケーションは自分自身のメッセージを受けたときには、 応答を生成しなければならない。
 200 カーネルは失敗したパケットに対して、 \fBNLMSG_ERROR\fP メッセージを送ろうとする。 ユーザープロセスはこの慣習にも従う必要がある。
 201
 202 However, reliable transmissions from kernel to user are impossible in any
 203 case.  The kernel can't send a netlink message if the socket buffer is full:
 204 the message will be dropped and the kernel and the user\-space process will
 205 no longer have the same view of kernel state.  It is up to the application
 206 to detect when this happens (via the \fBENOBUFS\fP error returned by
 207 \fBrecvmsg\fP(2))  and resynchronize.
 208 .SS "Address formats"
 209 \fIsockaddr_nl\fP 構造体はユーザー空間やカーネル空間で netlink クライアントを記述する。 \fIsockaddr_nl\fP
 210 はユニキャスト (単一の接続先にだけ送られる) にもできるし、 netlink マルチキャストグループ (\fInl_groups\fP が 0 でない場合)
 211 にも送ることができる。
 212
 213 .in +4n
 214 .nf
 215 struct sockaddr_nl {
 216     sa_family_t     nl_family;  /* AF_NETLINK */
 217     unsigned short  nl_pad;     /* Zero. */
 218     pid_t           nl_pid;     /* Port ID. */
 219     __u32           nl_groups;  /* Multicast groups mask. */
 220 };
 221 .fi
 222 .in
 223
 224 \fInl_pid\fP is the unicast address of netlink socket.  It's always 0 if the
 225 destination is in the kernel.  For a user\-space process, \fInl_pid\fP is
 226 usually the PID of the process owning the destination socket.  However,
 227 \fInl_pid\fP identifies a netlink socket, not a process.  If a process owns
 228 several netlink sockets, then \fInl_pid\fP can only be equal to the process ID
 229 for at most one socket.  There are two ways to assign \fInl_pid\fP to a netlink
 230 socket.  If the application sets \fInl_pid\fP before calling \fBbind\fP(2), then
 231 it is up to the application to make sure that \fInl_pid\fP is unique.  If the
 232 application sets it to 0, the kernel takes care of assigning it.  The kernel
 233 assigns the process ID to the first netlink socket the process opens and
 234 assigns a unique \fInl_pid\fP to every netlink socket that the process
 235 subsequently creates.
 236
 237 .\" commit d629b836d151d43332492651dd841d32e57ebe3b
 238 \fInl_groups\fP is a bit mask with every bit representing a netlink group
 239 number.  Each netlink family has a set of 32 multicast groups.  When
 240 \fBbind\fP(2)  is called on the socket, the \fInl_groups\fP field in the
 241 \fIsockaddr_nl\fP should be set to a bit mask of the groups which it wishes to
 242 listen to.  The default value for this field is zero which means that no
 243 multicasts will be received.  A socket may multicast messages to any of the
 244 multicast groups by setting \fInl_groups\fP to a bit mask of the groups it
 245 wishes to send to when it calls \fBsendmsg\fP(2)  or does a \fBconnect\fP(2).
 246 Only processes with an effective UID of 0 or the \fBCAP_NET_ADMIN\fP capability
 247 may send or listen to a netlink multicast group.  Since Linux 2.6.13,
 248 messages can't be broadcast to multiple groups.  Any replies to a message
 249 received for a multicast group should be sent back to the sending PID and
 250 the multicast group.  Some Linux kernel subsystems may additionally allow
 251 other users to send and/or receive messages.  As at Linux 3.0, the
 252 \fBNETLINK_KOBJECT_UEVENT\fP, \fBNETLINK_GENERIC\fP, \fBNETLINK_ROUTE\fP, and
 253 \fBNETLINK_SELINUX\fP groups allow other users to receive messages.  No groups
 254 allow other users to send messages.
 255 .SH バージョン
 256 netlink へのソケットインターフェースは Linux 2.2 の新機能である。
 257
 258 Linux 2.0 は、もっと原始的なデバイスベースの netlink インターフェースを サポートしていた (これも互換性のために今でも使用できる)。
 259 古いインターフェースに関してはここでは記述しない。
 260
 261 NETLINK_SELINUX は Linux 2.6.4 で登場した。
 262
 263 NETLINK_AUDIT は Linux 2.6.6 で登場した。
 264
 265 NETLINK_KOBJECT_UEVENT は Linux 2.6.10 で登場した。
 266
 267 NETLINK_W1, NETLINK_FIB_LOOKUP は Linux 2.6.13 で登場した。
 268
 269 NETLINK_INET_DIAG, NETLINK_CONNECTOR, NETLINK_NETFILTER は Linux 2.6.14
 270 で登場した。
 271
 272 NETLINK_GENERIC, NETLINK_ISCSI は Linux 2.6.15 で登場した。
 273 .SH 注意
 274 低レベルのカーネルインターフェースより、 \fIlibnetlink\fP または \fIlibnl\fP を通して netlink
 275 を利用するほうが良いことが多い。
 276 .SH バグ
 277 この man ページは完成していない。
 278 .SH 例
 279 以下の例では、 \fBRTMGRP_LINK\fP (ネットワークインターフェースの create/delete/up/down イベント) と
 280 \fBRTMGRP_IPV4_IFADDR\fP (IPv4 アドレスの add/delete イベント) マルチキャストグループを listen する
 281 \fBNETLINK_ROUTE\fP netlink を作成している。
 282
 283 .in +4n
 284 .nf
 285 struct sockaddr_nl sa;
 286
 287 memset(&sa, 0, sizeof(sa));
 288 sa.nl_family = AF_NETLINK;
 289 sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
 290
 291 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
 292 bind(fd, (struct sockaddr *) &sa, sizeof(sa));
 293 .fi
 294 .in
 295
 296 次の例では、netlink メッセージをカーネル (pid 0) に送る方法を示している。 応答を追跡する際の信頼性を高めるために、アプリケーションが
 297 メッセージのシーケンス番号を正しく処理しなければならない点に注意すること。
 298
 299 .in +4n
 300 .nf
 301 struct nlmsghdr *nh;    /* The nlmsghdr with payload to send. */
 302 struct sockaddr_nl sa;
 303 struct iovec iov = { nh, nh\->nlmsg_len };
 304 struct msghdr msg;
 305
 306 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
 307 memset(&sa, 0, sizeof(sa));
 308 sa.nl_family = AF_NETLINK;
 309 nh\->nlmsg_pid = 0;
 310 nh\->nlmsg_seq = ++sequence_number;
 311 /* Request an ack from kernel by setting NLM_F_ACK. */
 312 nh\->nlmsg_flags |= NLM_F_ACK;
 313
 314 sendmsg(fd, &msg, 0);
 315 .fi
 316 .in
 317
 318 最後は、netlink メッセージの読み込みの例である。
 319
 320 .in +4n
 321 .nf
 322 int len;
 323 char buf[4096];
 324 struct iovec iov = { buf, sizeof(buf) };
 325 struct sockaddr_nl sa;
 326 struct msghdr msg;
 327 struct nlmsghdr *nh;
 328
 329 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
 330 len = recvmsg(fd, &msg, 0);
 331
 332 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
 333      nh = NLMSG_NEXT (nh, len)) {
 334     /* マルチパートメッセージの終わり */
 335     if (nh\->nlmsg_type == NLMSG_DONE)
 336         return;
 337
 338     if (nh\->nlmsg_type == NLMSG_ERROR)
 339         /* 何らかのエラー処理を行う */
 340     ...
 341
 342     /* ペイロードの解析を続ける */
 343     ...
 344 }
 345 .fi
 346 .in
 347 .SH 関連項目
 348 \fBcmsg\fP(3), \fBnetlink\fP(3), \fBcapabilities\fP(7), \fBrtnetlink\fP(7)
 349
 350 .UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2*
 351 information about
 352 libnetlink
 353 .UE
 354
 355 .UR http://people.suug.ch\:/~tgr\:/libnl/
 356 information about libnl
 357 .UE
 358
 359 RFC 3549 "Linux Netlink as an IP Services Protocol"
 360 .SH この文書について
 361 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部
 362 である。プロジェクトの説明とバグ報告に関する情報は
 363 http://www.kernel.org/doc/man\-pages/ に書かれている。