draft/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 NEW 要求における追加フラグビット
 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 しかし、どのような場合でもカーネルからユーザーへの 信頼性の高い転送は不可能である。 ソケットバッファが満杯の場合、カーネルは netlink
 203 メッセージを送信できない。 メッセージは取りこぼされて、カーネルとユーザー空間プロセスは、 カーネルの状態についての同じビューを持つことができなくなる。
 204 これが起こったこと (\fBrecvmsg\fP(2)  によって \fBENOBUFS\fP エラーが返される) を検知して再び同期させるのは、
 205 アプリケーションの責任である。
 206 .SS アドレスのフォーマット
 207 \fIsockaddr_nl\fP 構造体はユーザー空間やカーネル空間で netlink クライアントを記述する。 \fIsockaddr_nl\fP
 208 はユニキャスト (単一の接続先にだけ送られる) にもできるし、 netlink マルチキャストグループ (\fInl_groups\fP が 0 でない場合)
 209 にも送ることができる。
 210
 211 .in +4n
 212 .nf
 213 struct sockaddr_nl {
 214     sa_family_t     nl_family;  /* AF_NETLINK */
 215     unsigned short  nl_pad;     /* 0 である */
 216     pid_t           nl_pid;     /* ポート ID */
 217     __u32           nl_groups;  /* マルチキャストグループマスク */
 218 };
 219 .fi
 220 .in
 221
 222 \fInl_pid\fP は netlink ソケットのユニキャストアドレスである。 行き先がカーネルの場合は、常に 0 である。
 223 ユーザー空間プロセスの場合、通常は \fInl_pid\fP は行き先のソケットを所有しているプロセスの PID である。 ただし、 \fInl_pid\fP
 224 はプロセスではなく netlink ソケットを同定する。 プロセスが複数の netlink ソケットを所有する場合、 \fInl_pid\fP
 225 は最大でも一つのソケットのプロセス ID としか等しくならない。 \fInl_pid\fP を netlink ソケットに割り当てる方法は 2 つある。
 226 アプリケーションが \fBbind\fP(2)  を呼ぶ前に \fInl_pid\fP を設定する場合、 \fInl_pid\fP
 227 が一意であることを確認するのはアプリケーションの責任となる。 アプリケーションが \fInl_pid\fP を 0
 228 に設定した場合、カーネルがこの値を割り当てる。 カーネルはプロセスが最初にオープンした netlink ソケットに対してプロセス ID を割り当て、
 229 それ以降にプロセスが作成した全ての netlink ソケットにも一意な \fInl_pid\fP を割り当てる。
 230
 231 .\" commit d629b836d151d43332492651dd841d32e57ebe3b
 232 \fInl_groups\fP is a bit mask with every bit representing a netlink group
 233 number.  Each netlink family has a set of 32 multicast groups.  When
 234 \fBbind\fP(2)  is called on the socket, the \fInl_groups\fP field in the
 235 \fIsockaddr_nl\fP should be set to a bit mask of the groups which it wishes to
 236 listen to.  The default value for this field is zero which means that no
 237 multicasts will be received.  A socket may multicast messages to any of the
 238 multicast groups by setting \fInl_groups\fP to a bit mask of the groups it
 239 wishes to send to when it calls \fBsendmsg\fP(2)  or does a \fBconnect\fP(2).
 240 Only processes with an effective UID of 0 or the \fBCAP_NET_ADMIN\fP capability
 241 may send or listen to a netlink multicast group.  Since Linux 2.6.13,
 242 messages can't be broadcast to multiple groups.  Any replies to a message
 243 received for a multicast group should be sent back to the sending PID and
 244 the multicast group.  Some Linux kernel subsystems may additionally allow
 245 other users to send and/or receive messages.  As at Linux 3.0, the
 246 \fBNETLINK_KOBJECT_UEVENT\fP, \fBNETLINK_GENERIC\fP, \fBNETLINK_ROUTE\fP, and
 247 \fBNETLINK_SELINUX\fP groups allow other users to receive messages.  No groups
 248 allow other users to send messages.
 249 .SH バージョン
 250 netlink へのソケットインターフェースは Linux 2.2 の新機能である。
 251
 252 Linux 2.0 は、もっと原始的なデバイスベースの netlink インターフェースを サポートしていた (これも互換性のために今でも使用できる)。
 253 古いインターフェースに関してはここでは記述しない。
 254
 255 NETLINK_SELINUX は Linux 2.6.4 で登場した。
 256
 257 NETLINK_AUDIT は Linux 2.6.6 で登場した。
 258
 259 NETLINK_KOBJECT_UEVENT は Linux 2.6.10 で登場した。
 260
 261 NETLINK_W1, NETLINK_FIB_LOOKUP は Linux 2.6.13 で登場した。
 262
 263 NETLINK_INET_DIAG, NETLINK_CONNECTOR, NETLINK_NETFILTER は Linux 2.6.14
 264 で登場した。
 265
 266 NETLINK_GENERIC, NETLINK_ISCSI は Linux 2.6.15 で登場した。
 267 .SH 注意
 268 低レベルのカーネルインターフェースより、 \fIlibnetlink\fP または \fIlibnl\fP を通して netlink
 269 を利用するほうが良いことが多い。
 270 .SH バグ
 271 この man ページは完成していない。
 272 .SH 例
 273 以下の例では、 \fBRTMGRP_LINK\fP (ネットワークインターフェースの create/delete/up/down イベント) と
 274 \fBRTMGRP_IPV4_IFADDR\fP (IPv4 アドレスの add/delete イベント) マルチキャストグループを listen する
 275 \fBNETLINK_ROUTE\fP netlink を作成している。
 276
 277 .in +4n
 278 .nf
 279 struct sockaddr_nl sa;
 280
 281 memset(&sa, 0, sizeof(sa));
 282 sa.nl_family = AF_NETLINK;
 283 sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
 284
 285 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
 286 bind(fd, (struct sockaddr *) &sa, sizeof(sa));
 287 .fi
 288 .in
 289
 290 次の例では、netlink メッセージをカーネル (pid 0) に送る方法を示している。 応答を追跡する際の信頼性を高めるために、アプリケーションが
 291 メッセージのシーケンス番号を正しく処理しなければならない点に注意すること。
 292
 293 .in +4n
 294 .nf
 295 struct nlmsghdr *nh;    /* 送信する nlmsghdr とペイロード */
 296 struct sockaddr_nl sa;
 297 struct iovec iov = { nh, nh\->nlmsg_len };
 298 struct msghdr msg;
 299
 300 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
 301 memset(&sa, 0, sizeof(sa));
 302 sa.nl_family = AF_NETLINK;
 303 nh\->nlmsg_pid = 0;
 304 nh\->nlmsg_seq = ++sequence_number;
 305 /* NLM_F_ACK を設定することで、カーネルに応答を要求する */
 306 nh\->nlmsg_flags |= NLM_F_ACK;
 307
 308 sendmsg(fd, &msg, 0);
 309 .fi
 310 .in
 311
 312 最後は、netlink メッセージの読み込みの例である。
 313
 314 .in +4n
 315 .nf
 316 int len;
 317 char buf[4096];
 318 struct iovec iov = { buf, sizeof(buf) };
 319 struct sockaddr_nl sa;
 320 struct msghdr msg;
 321 struct nlmsghdr *nh;
 322
 323 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
 324 len = recvmsg(fd, &msg, 0);
 325
 326 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
 327      nh = NLMSG_NEXT (nh, len)) {
 328     /* マルチパートメッセージの終わり */
 329     if (nh\->nlmsg_type == NLMSG_DONE)
 330         return;
 331
 332     if (nh\->nlmsg_type == NLMSG_ERROR)
 333         /* 何らかのエラー処理を行う */
 334     ...
 335
 336     /* ペイロードの解析を続ける */
 337     ...
 338 }
 339 .fi
 340 .in
 341 .SH 関連項目
 342 \fBcmsg\fP(3), \fBnetlink\fP(3), \fBcapabilities\fP(7), \fBrtnetlink\fP(7)
 343
 344 .UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2*
 345 information about
 346 libnetlink
 347 .UE
 348
 349 .UR http://people.suug.ch\:/~tgr\:/libnl/
 350 information about libnl
 351 .UE
 352
 353 RFC 3549 "Linux Netlink as an IP Services Protocol"
 354 .SH この文書について
 355 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.51 の一部
 356 である。プロジェクトの説明とバグ報告に関する情報は
 357 http://www.kernel.org/doc/man\-pages/ に書かれている。