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 はビットマスクで、すべてのビットが netlink グループ番号を表す。
 233 それぞれの netlink ファミリーは 32 のマルチキャストグループのセットを持つ。
 234 それぞれの netlink ファミリーは 32 のマルチキャストグループの セットを持つ。
 235 \fBbind\fP(2) がソケットに対して呼ばれると、 \fIsockaddr_nl\fP の \fInl_groups\fP
 236 フィールドには listen したいグループのビットマスクがセットされる。
 237 デフォルトの値は 0 で、マルチキャストを一切受信しない。
 238 \fBsendmsg\fP(2) や \fBconnect\fP(2) によって、あるソケットからメッセージを
 239 マルチキャストしたいときは、 \fInl_groups\fP に送信したいグループのビットマスク
 240 をセットすればよい。
 241 netlink マルチキャストグループに送信したり、これを listen したりできるのは、
 242 実効ユーザー ID が 0 のプロセスか、 \fBCAP_NET_ADMIN\fP 権限を持つプロセスのみである。
 243 Linux 2.6.13 以降では、メッセージを複数のグループへのブロードキャストすることはできない。
 244 マルチキャストグループ向けメッセージを受信した場合、これ対する応答は
 245 送り主の PID とマルチキャストグループとに送り返すべきである。
 246 さらに、Linux のカーネルサブシステムによっては、
 247 他のユーザもメッセージの送受信ができる場合がある。
 248 Linux 3.0 の時点では、
 249 \fBNETLINK_KOBJECT_UEVENT\fP, \fBNETLINK_GENERIC\fP, \fBNETLINK_ROUTE\fP,
 250 \fBNETLINK_SELINUX\fP グループでは他のユーザがメッセージを受信することができる。
 251 他のユーザがメッセージを送信できるグループは存在しない。
 252 .SH バージョン
 253 netlink へのソケットインターフェースは Linux 2.2 の新機能である。
 254
 255 Linux 2.0 は、もっと原始的なデバイスベースの netlink インターフェースを サポートしていた (これも互換性のために今でも使用できる)。
 256 古いインターフェースに関してはここでは記述しない。
 257
 258 NETLINK_SELINUX は Linux 2.6.4 で登場した。
 259
 260 NETLINK_AUDIT は Linux 2.6.6 で登場した。
 261
 262 NETLINK_KOBJECT_UEVENT は Linux 2.6.10 で登場した。
 263
 264 NETLINK_W1, NETLINK_FIB_LOOKUP は Linux 2.6.13 で登場した。
 265
 266 NETLINK_INET_DIAG, NETLINK_CONNECTOR, NETLINK_NETFILTER は Linux 2.6.14
 267 で登場した。
 268
 269 NETLINK_GENERIC, NETLINK_ISCSI は Linux 2.6.15 で登場した。
 270 .SH 注意
 271 低レベルのカーネルインターフェースより、 \fIlibnetlink\fP または \fIlibnl\fP を通して netlink
 272 を利用するほうが良いことが多い。
 273 .SH バグ
 274 この man ページは完成していない。
 275 .SH 例
 276 以下の例では、 \fBRTMGRP_LINK\fP (ネットワークインターフェースの create/delete/up/down イベント) と
 277 \fBRTMGRP_IPV4_IFADDR\fP (IPv4 アドレスの add/delete イベント) マルチキャストグループを listen する
 278 \fBNETLINK_ROUTE\fP netlink を作成している。
 279
 280 .in +4n
 281 .nf
 282 struct sockaddr_nl sa;
 283
 284 memset(&sa, 0, sizeof(sa));
 285 sa.nl_family = AF_NETLINK;
 286 sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
 287
 288 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
 289 bind(fd, (struct sockaddr *) &sa, sizeof(sa));
 290 .fi
 291 .in
 292
 293 次の例では、netlink メッセージをカーネル (pid 0) に送る方法を示している。 応答を追跡する際の信頼性を高めるために、アプリケーションが
 294 メッセージのシーケンス番号を正しく処理しなければならない点に注意すること。
 295
 296 .in +4n
 297 .nf
 298 struct nlmsghdr *nh;    /* 送信する nlmsghdr とペイロード */
 299 struct sockaddr_nl sa;
 300 struct iovec iov = { nh, nh\->nlmsg_len };
 301 struct msghdr msg;
 302
 303 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
 304 memset(&sa, 0, sizeof(sa));
 305 sa.nl_family = AF_NETLINK;
 306 nh\->nlmsg_pid = 0;
 307 nh\->nlmsg_seq = ++sequence_number;
 308 /* NLM_F_ACK を設定することで、カーネルに応答を要求する */
 309 nh\->nlmsg_flags |= NLM_F_ACK;
 310
 311 sendmsg(fd, &msg, 0);
 312 .fi
 313 .in
 314
 315 最後は、netlink メッセージの読み込みの例である。
 316
 317 .in +4n
 318 .nf
 319 int len;
 320 char buf[4096];
 321 struct iovec iov = { buf, sizeof(buf) };
 322 struct sockaddr_nl sa;
 323 struct msghdr msg;
 324 struct nlmsghdr *nh;
 325
 326 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
 327 len = recvmsg(fd, &msg, 0);
 328
 329 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
 330      nh = NLMSG_NEXT (nh, len)) {
 331     /* マルチパートメッセージの終わり */
 332     if (nh\->nlmsg_type == NLMSG_DONE)
 333         return;
 334
 335     if (nh\->nlmsg_type == NLMSG_ERROR)
 336         /* 何らかのエラー処理を行う */
 337     ...
 338
 339     /* ペイロードの解析を続ける */
 340     ...
 341 }
 342 .fi
 343 .in
 344 .SH 関連項目
 345 \fBcmsg\fP(3), \fBnetlink\fP(3), \fBcapabilities\fP(7), \fBrtnetlink\fP(7)
 346
 347 .UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2*
 348 libnetlink に関する情報
 349 .UE
 350
 351 .UR http://people.suug.ch\:/~tgr\:/libnl/
 352 libnl に関する情報
 353 .UE
 354
 355 RFC 3549 "Linux Netlink as an IP Services Protocol"
 356 .SH この文書について
 357 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.51 の一部
 358 である。プロジェクトの説明とバグ報告に関する情報は
 359 http://www.kernel.org/doc/man\-pages/ に書かれている。