manual/LDP_man-pages/release/man7/netlink.7

   1 '\" t
   2 .\" Don't change the first line, it tells man that tbl is needed.
   3 .\" This man page is Copyright (c) 1998 by Andi Kleen. Subject to the GPL.
   4 .\" Based on the original comments from Alexey Kuznetsov
   5 .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $
   6 .\"
   7 .\" Japanese Version Copyright (c) 1999 NAKANO Takeo all rights reserved.
   8 .\" Translated 1999-12-06 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
   9 .\" Updated 2001-04-04 by Yuichi SATO <ysato@h4.dion.ne.jp>, catch up to LDP v1.35
  10 .\" Updated 2006-06-23 by Yuichi SATO <ysato444@yahoo.co.jp>, catch up to LDP v2.29
  11 .\"
  12 .\"WORD         payload         ペイロード
  13 .\"WORD         capability      権限
  14 .\"
  15 .TH NETLINK  7 2008-11-11 "Linux" "Linux Programmer's Manual"
  16 .SH 名前
  17 netlink \- カーネルとユーザー空間の通信 (AF_NETLINK)
  18 .SH 書式
  19 .nf
  20 .B #include <asm/types.h>
  21 .B #include <sys/socket.h>
  22 .B #include <linux/netlink.h>
  23
  24 .BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family );
  25 .fi
  26 .SH 説明
  27 netlink はカーネルモジュールとユーザー空間のプロセス間で
  28 情報をやりとりするために用いられる。
  29 netlink は、ユーザープロセスに対しては
  30 標準的なソケットベースのインターフェースを、
  31 カーネルモジュールにはカーネルの内部 API を提供する。
  32 カーネル内部のインターフェースについてはこの man ページでは記述しない。
  33 また、netlink キャラクタデバイスを用いた
  34 obsolete な netlink インターフェースもあるが、これもこの文書では解説しない。
  35 これは単に過去互換性のために用意されているものにすぎない。
  36
  37 netlink はデータグラム指向のサービスである。
  38 .I socket_type
  39 には
  40 .B SOCK_RAW
  41 と
  42 .B SOCK_DGRAM
  43 の両方とも指定可能である。
  44 しかし netlink プロトコルはデータグラムと raw ソケットの区別をしない。
  45
  46 .I netlink_family
  47 は、通信するカーネルモジュールや netlink グループの選択に用いる。
  48 現在割り当てられている netlink ファミリーは以下の通り。
  49 .TP
  50 .B NETLINK_ROUTE
  51 ルーティングとリンクの更新を受信する。
  52 (IPv4 と IPv6 両方の) ルーティングテーブル・
  53 IP アドレス・リンクパラメータ・近傍設定 (neighbor setup)・
  54 キューイングルール (queueing dicipline)・トラフィッククラス・
  55 パケットのクラス分類の修正に用いることができるだろう
  56 .RB ( rtnetlink (7)
  57 を見よ)。
  58 .TP
  59 .B NETLINK_W1
  60 単線 (1-wire) のサブシステムからのメッセージ。
  61 .TP
  62 .B NETLINK_USERSOCK
  63 ユーザーモードソケットプロトコルのために予約されている。
  64 .TP
  65 .B NETLINK_FIREWALL
  66 IPv4 パケットを netfilter からユーザー空間へ転送する。
  67 .I ip_queue
  68 カーネルモジュールで使用される。
  69 .TP
  70 .B NETLINK_INET_DIAG
  71 .\" FIXME More details on NETLINK_INET_DIAG needed.
  72 INET ソケットをモニタリングする。
  73 .TP
  74 .B NETLINK_NFLOG
  75 Netfilter/iptables ULOG.
  76 .TP
  77 .B NETLINK_XFRM
  78 .\" FIXME More details on NETLINK_XFRM needed.
  79 IPsec.
  80 .TP
  81 .B NETLINK_SELINUX
  82 SELinux のイベント通知。
  83 .TP
  84 .B NETLINK_ISCSI
  85 .\" FIXME More details on NETLINK_ISCSI needed.
  86 Open-iSCSI.
  87 .TP
  88 .B NETLINK_AUDIT
  89 .\" FIXME More details on NETLINK_AUDIT needed.
  90 監査 (audit) を行う。
  91 .TP
  92 .B NETLINK_FIB_LOOKUP
  93 .\" FIXME More details on NETLINK_FIB_LOOKUP needed.
  94 ユーザー空間から FIB ルックアップにアクセスする。
  95 .TP
  96 .B NETLINK_CONNECTOR
  97 カーネルコネクタ。
  98 より詳しい情報はカーネルソースの
  99 .I Documentation/connector/*
 100 を参照すること。
 101 .TP
 102 .B NETLINK_NETFILTER
 103 .\" FIXME More details on NETLINK_NETFILTER needed.
 104 netfilter サブシステム。
 105 .TP
 106 .B NETLINK_IP6_FW
 107 IPv6 パケットを netfilter からユーザー空間へ転送する。
 108 .I ip6_queue
 109 カーネルモジュールで使用される。
 110 .TP
 111 .B NETLINK_DNRTMSG
 112 DECnet ルーティングメッセージ。
 113 .TP
 114 .B NETLINK_KOBJECT_UEVENT
 115 .\" FIXME More details on NETLINK_KOBJECT_UEVENT needed.
 116 ユーザー空間へのカーネルメッセージ
 117 .TP
 118 .B NETLINK_GENERIC
 119 netlink を簡単に使用するための一般的な netlink ファミリー。
 120 .PP
 121 netlink メッセージはバイトストリームからなり、
 122 一つ以上の
 123 .I nlmsghdr
 124 ヘッダと、それに対応するペイロード (payload) が含まれる。
 125 バイトストリームには、標準の
 126 .B NLMSG_*
 127 マクロによってのみアクセスすべきである。
 128 より詳しい情報は
 129 .BR netlink (3)
 130 を見よ。
 131
 132 マルチパートメッセージ (一つ以上の
 133 .I nlmsghdr
 134 ヘッダと、それに対応するペイロードが
 135 一つバイトストリームに含まれる) においては、
 136 先頭のヘッダ・後続のヘッダには
 137 .B NLM_F_MULTI
 138 フラグがセットされる。ただし最後のヘッダだけは例外で、
 139 .B NLMSG_DONE
 140 タイプとなる。
 141
 142 それぞれの
 143 .B nlmsghdr
 144 の後にはペイロードが続く。
 145
 146 .in +4n
 147 .nf
 148 struct nlmsghdr {
 149     __u32 nlmsg_len;    /* ヘッダを含むメッセージの長さ */
 150     __u16 nlmsg_type;   /* メッセージの内容のタイプ */
 151     __u16 nlmsg_flags;  /* 追加フラグ */
 152     __u32 nlmsg_seq;    /* シーケンス番号 */
 153     __u32 nlmsg_pid;    /* 送信プロセスの PID */
 154 };
 155 .fi
 156 .in
 157
 158 .I nlmsg_type
 159 は標準のメッセージタイプのどれか一つである:
 160 .B NLMSG_NOOP
 161 メッセージは無視される。
 162 .B NLMSG_ERROR
 163 メッセージはエラーを示し、ペイロードには
 164 .I nlmsgerr
 165 構造体が入る。
 166 .B NLMSG_DONE
 167 メッセージはマルチパートメッセージの終了を伝える。
 168
 169 .in +4n
 170 .nf
 171 struct nlmsgerr {
 172     int error;        /* 負または 0 の errno は応答を表す */
 173     struct nlmsghdr msg;  /* エラーを起こしたメッセージのヘッダ */
 174 };
 175 .fi
 176 .in
 177
 178 ある netlink ファミリーで指定できるメッセージタイプは、
 179 通常もっと多い。これらに関しては適切な man ページを見てほしい。
 180 たとえば
 181 .B NETLINK_ROUTE
 182 に関しては
 183 .BR rtnetlink (7)
 184 に書いてある。
 185
 186 .I nlmsg_flags
 187 の標準フラグビット
 188 .br
 189 ---------------------------------
 190 .TS
 191 tab(:);
 192 lB l.
 193 NLM_F_REQUEST:要求メッセージ全てでセットされなければならない。
 194 NLM_F_MULTI:T{
 195 このメッセージはマルチパートメッセージの一部である。
 196 マルチパートメッセージは
 197 .B NLMSG_DONE
 198 で終端する。
 199 T}
 200 NLM_F_ACK:成功した場合の応答を要求する。
 201 NLM_F_ECHO:この要求をエコーする。
 202 .TE
 203
 204 GET 要求における追加フラグビット
 205 .br
 206 -------------------------------------
 207 .TS
 208 tab(:);
 209 lB l.
 210 .\" FIXME NLM_F_ATOMIC is not used any more?
 211 NLM_F_ROOT:単一のエントリではなくテーブル全体を返す。
 212 NLM_F_MATCH:T{
 213 メッセージの内容で渡された基準 (criteria) にマッチする
 214 全てのエントリを返す。
 215 まだ実装されていない。
 216 T}
 217 NLM_F_ATOMIC:テーブルのアトミックなスナップショットを返す。
 218 NLM_F_DUMP:便利なマクロ。(NLM_F_ROOT|NLM_F_MATCH) と同じ。
 219 .TE
 220
 221 .B NLM_F_ATOMIC
 222 を使う場合は、
 223 .B CAP_NET_ADMIN
 224 権限を持つか実効ユーザー ID が 0 でなければならない点に注意すること。
 225
 226 NEW 要求における追加フラグビット
 227 .br
 228 -------------------------------------
 229 .TS
 230 tab(:);
 231 lB l.
 232 NLM_F_REPLACE:現存のオブジェクトを置換する。
 233 NLM_F_EXCL:すでにオブジェクトがあったら置換しない。
 234 NLM_F_CREATE:まだオブジェクトがなければ作成する。
 235 NLM_F_APPEND:オブジェクトリストの最後に追加する。
 236 .TE
 237
 238 .I nlmsg_seq
 239 と
 240 .I nlmsg_pid
 241 はメッセージの追跡に使用される。
 242 .I nlmsg_pid
 243 はメッセージの送信元を表す。
 244 メッセージが netlink ソケットで送信されている場合、
 245 .I nlmsg_pid
 246 とプロセスの PID は 1:1 の関係ではない点に注意すること。
 247 より詳しい情報は、
 248 .RB 「 アドレスのフォーマット 」
 249 のセクションを参照すること。
 250
 251 .I nlmsg_seq
 252 と
 253 .I nlmsg_pid
 254 は netlink のコアには見えない (opaque)。
 255
 256 netlink は信頼性の高いプロトコルではない。
 257 netlink はメッセージを行き先に届けるために最善を尽くすが、
 258 メモリが足りなかったりエラーが起こったりすると
 259 メッセージを取りこぼすこともある。
 260 信頼性の高い転送を行いたいときは、
 261 送信者は受信者に応答を要求することもできる。
 262 これには
 263 .B NLM_F_ACK
 264 フラグをセットする。
 265 応答は
 266 .B NLMSG_ERROR
 267 パケットのエラーフィールドを 0 にしたものになる。
 268 アプリケーションは自分自身のメッセージを受けたときには、
 269 応答を生成しなければならない。
 270 カーネルは失敗したパケットに対して、
 271 .B NLMSG_ERROR
 272 メッセージを送ろうとする。
 273 ユーザープロセスはこの慣習にも従う必要がある。
 274
 275 しかし、どのような場合でもカーネルからユーザーへの
 276 信頼性の高い転送は不可能である。
 277 ソケットバッファが満杯の場合、カーネルは netlink メッセージを送信できない。
 278 メッセージは取りこぼされて、カーネルとユーザー空間プロセスは、
 279 カーネルの状態についての同じビューを持つことができなくなる。
 280 これが起こったこと
 281 .RB ( recvmsg (2)
 282 によって
 283 .B ENOBUFS
 284 エラーが返される) を検知して再び同期させるのは、
 285 アプリケーションの責任である。
 286 .SS アドレスのフォーマット
 287 .I sockaddr_nl
 288 構造体はユーザー空間やカーネル空間で netlink クライアントを記述する。
 289 .I sockaddr_nl
 290 はユニキャスト (単一の接続先にだけ送られる) にもできるし、
 291 netlink マルチキャストグループ
 292 .RI ( nl_groups
 293 が 0 でない場合) にも送ることができる。
 294
 295 .in +4n
 296 .nf
 297 struct sockaddr_nl {
 298     sa_family_t     nl_family;  /* AF_NETLINK */
 299     unsigned short  nl_pad;     /* 0 である */
 300     pid_t           nl_pid;     /* プロセス ID */
 301     __u32           nl_groups;  /* マルチキャストグループマスク */
 302 };
 303 .fi
 304 .in
 305
 306 .I nl_pid
 307 は netlink ソケットのユニキャストアドレスである。
 308 行き先がカーネルの場合は、常に 0 である。
 309 ユーザー空間プロセスの場合、通常は
 310 .I nl_pid
 311 は行き先のソケットを所有しているプロセスの PID である。
 312 ただし、
 313 .I nl_pid
 314 はプロセスではなく netlink ソケットを同定する。
 315 プロセスが複数の netlink ソケットを所有する場合、
 316 .I nl_pid
 317 は最大でも一つのソケットのプロセス ID としか等しくならない。
 318 .I nl_pid
 319 を netlink ソケットに割り当てる方法は 2 つある。
 320 アプリケーションが
 321 .BR bind (2)
 322 を呼ぶ前に
 323 .I nl_pid
 324 を設定する場合、
 325 .I nl_pid
 326 が一意であることを確認するのはアプリケーションの責任となる。
 327 アプリケーションが
 328 .I nl_pid
 329 を 0 に設定した場合、カーネルがこの値を割り当てる。
 330 カーネルはプロセスが最初にオープンした
 331 netlink ソケットに対してプロセス ID を割り当て、
 332 それ以降にプロセスが作成した全ての netlink ソケットにも一意な
 333 .I nl_pid
 334 を割り当てる。
 335
 336 .I nl_groups
 337 はビットマスクで、すべてのビットが netlink グループ番号を表す。
 338 それぞれの netlink ファミリーは 32 のマルチキャストグループのセットを持つ。
 339 それぞれの netlink ファミリーは 32 のマルチキャストグループの
 340 セットを持つ。
 341 .BR bind (2)
 342 がソケットに対して呼ばれると、
 343 .I sockaddr_nl
 344 の
 345 .I nl_groups
 346 フィールドには listen したいグループのビットマスクがセットされる。
 347 デフォルトの値は 0 で、マルチキャストを一切受信しない。
 348 .BR sendmsg (2)
 349 や
 350 .BR connect (2)
 351 によって、あるソケットからメッセージをマルチキャストしたいときは、
 352 .I nl_groups
 353 に送信したいグループのビットマスクをセットすればよい。
 354 実効ユーザー ID が 0 か、
 355 .B CAP_NET_ADMIN
 356 権限を持つユーザーのみが netlink マルチキャストグループに
 357 送信したり、これを listen したりすることができる。
 358 マルチキャストグループ向けメッセージを受信した場合、これ対する応答は
 359 送り主の PID とマルチキャストグループとに送り返すべきである。
 360 .SH バージョン
 361 netlink へのソケットインターフェースは Linux 2.2 の新機能である。
 362
 363 Linux 2.0 は、もっと原始的なデバイスベースの netlink インターフェースを
 364 サポートしていた (これも互換性のために今でも使用できる)。
 365 古いインターフェースに関してはここでは記述しない。
 366
 367 NETLINK_SELINUX は Linux 2.6.4 で登場した。
 368
 369 NETLINK_AUDIT は Linux 2.6.6 で登場した。
 370
 371 NETLINK_KOBJECT_UEVENT は Linux 2.6.10 で登場した。
 372
 373 NETLINK_W1, NETLINK_FIB_LOOKUP は Linux 2.6.13 で登場した。
 374
 375 NETLINK_INET_DIAG, NETLINK_CONNECTOR, NETLINK_NETFILTER は
 376 Linux 2.6.14 で登場した。
 377
 378 NETLINK_GENERIC, NETLINK_ISCSI は Linux 2.6.15 で登場した。
 379 .SH 注意
 380 低レベルのカーネルインターフェースより、
 381 .I libnetlink
 382 または
 383 .I libnl
 384 を通して netlink を利用するほうが良いことが多い。
 385 .SH バグ
 386 この man ページは完成していない。
 387 .SH 例
 388 以下の例では、
 389 .B RTMGRP_LINK
 390 (ネットワークインターフェースの create/delete/up/down イベント) と
 391 .B RTMGRP_IPV4_IFADDR
 392 (IPv4 アドレスの add/delete イベント) マルチキャストグループを listen する
 393 .B NETLINK_ROUTE
 394 netlink を作成している。
 395
 396 .in +4n
 397 .nf
 398 struct sockaddr_nl sa;
 399
 400 memset(&sa, 0, sizeof(sa));
 401 sa.nl_family = AF_NETLINK;
 402 sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
 403
 404 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
 405 bind(fd, (struct sockaddr *) &sa, sizeof(sa));
 406 .fi
 407 .in
 408
 409 次の例では、netlink メッセージをカーネル (pid 0) に送る方法を示している。
 410 応答を追跡する際の信頼性を高めるために、アプリケーションが
 411 メッセージのシーケンス番号を正しく処理しなければならない点に注意すること。
 412
 413 .in +4n
 414 .nf
 415 struct nlmsghdr *nh;    /* 送信する nlmsghdr とペイロード */
 416 struct sockaddr_nl sa;
 417 struct iovec iov = { (void *) nh, nh\->nlmsg_len };
 418 struct msghdr msg;
 419
 420 msg = { (void *)&sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
 421 memset(&sa, 0, sizeof(sa));
 422 sa.nl_family = AF_NETLINK;
 423 nh\->nlmsg_pid = 0;
 424 nh\->nlmsg_seq = ++sequence_number;
 425 /* NLM_F_ACK を設定することで、カーネルに応答を要求する */
 426 nh\->nlmsg_flags |= NLM_F_ACK;
 427
 428 sendmsg(fd, &msg, 0);
 429 .fi
 430 .in
 431
 432 最後は、netlink メッセージの読み込みの例である。
 433
 434 .in +4n
 435 .nf
 436 int len;
 437 char buf[4096];
 438 struct iovec iov = { buf, sizeof(buf) };
 439 struct sockaddr_nl sa;
 440 struct msghdr msg;
 441 struct nlmsghdr *nh;
 442
 443 msg = { (void *)&sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
 444 len = recvmsg(fd, &msg, 0);
 445
 446 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
 447      nh = NLMSG_NEXT (nh, len)) {
 448     /* マルチパートメッセージの終わり */
 449     if (nh\->nlmsg_type == NLMSG_DONE)
 450         return;
 451
 452     if (nh\->nlmsg_type == NLMSG_ERROR)
 453         /* 何らかのエラー処理を行う */
 454     ...
 455
 456     /* ペイロードの解析を続ける */
 457     ...
 458 }
 459 .fi
 460 .in
 461 .SH 関連項目
 462 .BR cmsg (3),
 463 .BR netlink (3),
 464 .BR capabilities (7),
 465 .BR rtnetlink (7)
 466 .PP
 467 libnetlink に関する情報は
 468 ftp://ftp.inr.ac.ru/ip-routing/iproute2*
 469
 470 libnl に関する情報は
 471 http://people.suug.ch/~tgr/libnl/
 472
 473 RFC 3549 "Linux Netlink as an IP Services Protocol"