draft/man3/libipq.3

   1 .\"O .TH LIBIPQ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   2 .TH LIBIPQ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   3 .\"
   4 .\" $Id: libipq.3,v 1.4 2001/10/16 16:58:25 jamesm Exp $
   5 .\"
   6 .\"     Copyright (c) 2000-2001 Netfilter Core Team
   7 .\"
   8 .\"     This program is free software; you can redistribute it and/or modify
   9 .\"     it under the terms of the GNU General Public License as published by
  10 .\"     the Free Software Foundation; either version 2 of the License, or
  11 .\"     (at your option) any later version.
  12 .\"
  13 .\"     This program is distributed in the hope that it will be useful,
  14 .\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\"     GNU General Public License for more details.
  17 .\"
  18 .\"     You should have received a copy of the GNU General Public License
  19 .\"     along with this program; if not, write to the Free Software
  20 .\"     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  21 .\"
  22 .\" Japanese Version Copyright (c) 2003 Susumu ISHIZUKA
  23 .\"         all rights reserved.
  24 .\" Translated Tue Jun  6 19:25:23 JST 2003
  25 .\"         by Susumu ISHIZUKA <szuka@isp.co.jp>
  26 .\"
  27 .\"WORD:        userspace       ユーザ空間
  28 .\"WORD:        verdict         判断
  29 .\"O .SH NAME
  30 .SH 名前
  31 libipq \- iptables userspace packet queuing library.
  32 .\"O .SH SYNOPSIS
  33 .SH 書式
  34 .B #include <linux/netfilter.h>
  35 .br
  36 .B #include <libipq.h>
  37 .\"O .SH DESCRIPTION
  38 .SH 説明
  39 .\"O libipq is a development library for iptables userspace packet queuing.
  40 libipq は iptables を 使って ユーザ空間でパケット操作を
  41 するためのライブラリである。
  42 .SS Userspace Packet Queuing
  43 .\"O Netfilter provides a mechanism for passing packets out of the stack for
  44 .\"O queueing to userspace, then receiving these packets back into the kernel
  45 .\"O with a verdict specifying what to do with the packets (such as ACCEPT
  46 .\"O or DROP).  These packets may also be modified in userspace prior to
  47 .\"O reinjection back into the kernel.
  48 Netfilter は、ユーザ空間でパケット操作をするための機構を
  49 提供している。 この機構はプロトコルスタックからパケットを
  50 ユーザ空間に渡してキューイング(queuing) し、ユーザ空間で
  51 (ACCEPT や DROP といった) パケット処理の判断を行った後に
  52 パケットをカーネルに戻している。 これらのパケットは、
  53 ユーザ空間で変更を加えられて、カーネルに返されることもある。
  54 .PP
  55 .\"O For each supported protocol, a kernel module called a
  56 .\"O .I queue handler
  57 .\"O may register with Netfilter to perform the mechanics of passing
  58 .\"O packets to and from userspace.
  59 ユーザ空間とのパケットのやり取りのために
  60 .I キューハンドラー (queue handler)
  61 と呼ばれるカーネルモジュールが
  62 Netfilter に登録されている。
  63 キューハンドラーは、各プロトコルごとに 用意される。
  64 .PP
  65 .\"O The standard queue handler for IPv4 is ip_queue.  It is provided as an
  66 .\"O experimental module with 2.4 kernels, and uses a Netlink socket for
  67 .\"O kernel/userspace communication.
  68 IPv4 での 標準のキューハンドラーは ip_queue である。
  69 2.4カーネルでは experimental モジュールとして提供され、
  70 Netlink ソケットを使って、カーネルとユーザ空間との通信を
  71 行っている。
  72 .PP
  73 .\"O Once ip_queue is loaded, IP packets may be selected with iptables
  74 .\"O and queued for userspace processing via the QUEUE target.  For example,
  75 .\"O running the following commands:
  76 ip_queue が、メモリ上にロードされると IP パケットは iptables で
  77 フィルタリングされ QUEUE ターゲットによって ユーザ空間の 処理のために
  78 キューイングされる。 例として 次の一連の コマンドが発行されると、
  79 .PP
  80         # modprobe iptable_filter
  81 .br
  82         # modprobe ip_queue
  83 .br
  84         # iptables -A OUTPUT -p icmp -j QUEUE
  85 .PP
  86 .\"O will cause any locally generated ICMP packets (e.g. ping output) to
  87 .\"O be sent to the ip_queue module, which will then attempt to deliver the
  88 .\"O packets to a userspace application.  If no userspace application is waiting,
  89 .\"O the packets will be dropped
  90 ローカルホストから送信されたICMPパケット（pingの送信など）が
  91 ip_queueモジュールに送られ、そこからパケットをユーザ空間の
  92 アプリケーションに渡そうとする。 パケットを受け取る
  93 アプリケーションがない場合は、パケットは破棄（drop）される。
  94 .PP
  95 .\"O An application may receive and process these packets via libipq.
  96 アプリケーションは、libipq を使うことでパケットを受信・
  97 変更できる。
  98 .PP
  99 .PP
 100 .SS Libipq Overview
 101 .\"O Libipq provides an API for communicating with ip_queue.  The following is
 102 .\"O an overview of API usage, refer to individual man pages for more details
 103 .\"O on each function.
 104 libipq は、ip_queue と通信するための API を提供する。
 105 以下は、API の簡単な説明である。 関数の詳細は各 manpage を
 106 参照すること。
 107 .\P
 108 .\"O .B Initialisation
 109 .B 初期化
 110 .br
 111 .\"O To initialise the library, call
 112 .\"O .BR ipq_create_handle (3).
 113 .\"O This will attempt to bind to the Netlink socket used by ip_queue and
 114 .\"O return an opaque context handle for subsequent library calls.
 115 初期化を行うには、
 116 .BR ipq_create_handle (3)
 117 を使用する。
 118 この関数は ip_queue が使用している Netlink ソケットを bind
 119 し、この後のライブラリ関数が使用するコンテキストハンドルを
 120 返す。
 121 .PP
 122 .\"O .B Setting the Queue Mode
 123 .B キューモード（queue mode）の設定
 124 .br
 125 .\"O .BR ipq_set_mode (3)
 126 .\"O allows the application to specify whether packet metadata, or packet
 127 .\"O payloads as well as metadata are copied to userspace.  It is also used to
 128 .\"O initially notify ip_queue that an application is ready to receive queue
 129 .\"O messages.
 130 .BR ipq_set_mode (3)
 131 は、ユーザ空間にパケットのメタデータだけを
 132 コピーするのか、パケットのメタデータとペイロードの両方を
 133 コピーするのか指定する。この関数はまた ip_queue に
 134 アプリケーションがキューメッセージ (queue message)を受け
 135 取る準備ができたことを通知する。
 136 .PP
 137 .\"O .B Receiving Packets from the Queue
 138 .B キューからパケットを受信する
 139 .br
 140 .\"O .BR ipq_read (3)
 141 .\"O waits for queue messages to arrive from ip_queue and copies
 142 .\"O them into a supplied buffer.
 143 .\"O Queue messages may be
 144 .\"O .I packet messages
 145 .\"O or
 146 .\"O .I error messages.
 147 .BR ipq_read (3)
 148 関数は ip_queue からのキューメッセージを
 149 待って、バッファにコピーする。 キューメッセージは
 150 .I パケット メッセージ
 151 または
 152 .I エラーメッセージ
 153 のどちらか である。
 154 .PP
 155 .\"O The type of packet may be determined with
 156 .\"O .BR ipq_message_type (3).
 157 パケットのタイプは
 158 .BR ipq_message_type (3)
 159 で取得する。
 160 .PP
 161 .\"O If it's a packet message, the metadata and optional payload may be retrieved with
 162 .\"O .BR ipq_get_packet (3).
 163 パケットメッセージの場合は、メタデータとペイロードを
 164 .BR ipq_get_packet (3)
 165 関数で取得できる。
 166 .PP
 167 .\"O To retrieve the value of an error message, use
 168 .\"O .BR ipq_get_msgerr (3).
 169 エラーメッセージの値を取得するには、
 170 .BR ipq_get_msgerr (3)
 171 を 使用する。
 172 .PP
 173 .\"O .B Issuing Verdicts on Packets
 174 .B パケットの処理内容の発行
 175 .br
 176 .\"O To issue a verdict on a packet, and optionally return a modified version
 177 .\"O of the packet to the kernel, call
 178 .\"O .BR ipq_set_verdict (3).
 179 パケットの処理を決定し、必要ならパケットに変更を加えて
 180 カーネルに返す時には、
 181 .BR ipq_set_verdict (3)
 182 を使用する。
 183 .PP
 184 .\"O .B Error Handling
 185 .B エラー処理
 186 .br
 187 .\"O An error string corresponding to the current value of the internal error
 188 .\"O variable
 189 .\"O .B ipq_errno
 190 .\"O may be obtained with
 191 .\"O .BR ipq_errstr (3).
 192 現在のエラー状態を格納している変数
 193 .B ipq_errno
 194 に対応する
 195 エラー文字列は
 196 .BR ipq_errstr (3).
 197 で取得できる。
 198 .PP
 199 .\"O For simple applications, calling
 200 .\"O .BR ipq_perror (3)
 201 .\"O will print the same message as
 202 .\"O .BR ipq_errstr (3),
 203 .\"O as well as the string corresponding to the global
 204 .\"O .B errno
 205 .\"O value (if set) to stderr.
 206 単純なアプリケーションに使える関数として、
 207 .BR ipq_perror (3)
 208 は、
 209 .BR ipq_errstr (3),
 210 で返されるのと同じ文字列を標準出力 (stderr) に
 211 出力する。 また、
 212 .B errno
 213 がセットされていれば
 214 それに対応するエラー文字列も出力する。
 215 .PP
 216 .\"O .B Cleaning Up
 217 .B 後始末
 218 .br
 219 .\"O To free up the Netlink socket and destroy resources associated with
 220 .\"O the context handle, call
 221 .\"O .BR ipq_destroy_handle (3).
 222 Netlink ソケットを解放し、コンテキストハンドルに関連付け
 223 られたリソースを削除するには、
 224 .BR ipq_destroy_handle (3)
 225 関数を使用する。
 226 .\"O .SH SUMMARY
 227 .SH まとめ
 228 .TP 4
 229 .BR ipq_create_handle (3)
 230 .\"O Initialise library, return context handle.
 231 は、ライブラリを初期化し、コンテキストハンドルを返す。
 232 .TP
 233 .BR ipq_set_mode (3)
 234 .\"O Set the queue mode, to copy either packet metadata, or payloads
 235 .\"O as well as metadata to userspace.
 236 は、パケットのメタデータだけをコピーするか、ペイロードも
 237 コピーするかの動作モードをセットする。
 238 .TP
 239 .BR ipq_read (3)
 240 .\"O Wait for a queue message to arrive from ip_queue and read it into
 241 .\"O a buffer.
 242 ip_queue からのメッセージを待ち、受信するとバッファに
 243 読み込む。
 244 .TP
 245 .BR ipq_message_type (3)
 246 .\"O Determine message type in the buffer.
 247 は、バッファされたメッセージのタイプを返す。
 248 .TP
 249 .BR ipq_get_packet (3)
 250 .\"O Retrieve a packet message from the buffer.
 251 は、バッファからメッセージを読む。
 252 .TP
 253 .BR ipq_get_msgerr (3)
 254 .\"O Retrieve an error message from the buffer.
 255 は、バッファからエラーメッセージを取得する。
 256 .TP
 257 .BR ipq_set_verdict (3)
 258 .\"O Set a verdict on a packet, optionally replacing its contents.
 259 は、パケットの判断を下す。内容を書き換えることもできる。
 260 .TP
 261 .BR ipq_errstr (3)
 262 .\"O Return an error message corresponding to the internal ipq_errno variable.
 263 は、内部変数 ipq_errno の値に応じたエラーメッセージを
 264 返す。
 265 .TP
 266 .BR ipq_perror (3)
 267 .\"O Helper function to print error messages to stderr.
 268 は、エラーメッセージを標準出力（stderr）に表示する
 269 ヘルパー関数である。
 270 .TP
 271 .BR ipq_destroy_handle (3)
 272 .\"O Destroy context handle and associated resources.
 273 は、コンテキストハンドルを破棄し、リソースを解放する。
 274 .\"O .SH EXAMPLE
 275 .SH 例
 276 .\"O The following is an example of a simple application which receives
 277 .\"O packets and issues NF_ACCEPT verdicts on each packet.
 278 次のコードは、パケットを受け取って NF_ACCEPT の判断を返す単純な
 279 アプリケーションの例である。
 280 .RS
 281 .nf
 282 /*
 283  * This code is GPL.
 284  */
 285 #include <linux/netfilter.h>
 286 #include <libipq.h>
 287 #include <stdio.h>
 288
 289 #define BUFSIZE 2048
 290
 291 static void die(struct ipq_handle *h)
 292 {
 293         ipq_perror("passer");
 294         ipq_destroy_handle(h);
 295         exit(1);
 296 }
 297
 298 int main(int argc, char **argv)
 299 {
 300         int status;
 301         unsigned char buf[BUFSIZE];
 302         struct ipq_handle *h;
 303
 304         h = ipq_create_handle(0);
 305         if (!h)
 306                 die(h);
 307
 308         status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE);
 309         if (status < 0)
 310                 die(h);
 311
 312         do{
 313                 status = ipq_read(h, buf, BUFSIZE, 0);
 314                 if (status < 0)
 315                         die(h);
 316
 317                 switch (ipq_message_type(buf)) {
 318                         case NLMSG_ERROR:
 319                                 fprintf(stderr, "Received error message %d\\n",
 320                                         ipq_get_msgerr(buf));
 321                                 break;
 322
 323                         case IPQM_PACKET: {
 324                                 ipq_packet_msg_t *m = ipq_get_packet(buf);
 325
 326                                 status = ipq_set_verdict(h, m->packet_id,
 327                                                          NF_ACCEPT, 0, NULL);
 328                                 if (status < 0)
 329                                         die(h);
 330                                 break;
 331                         }
 332
 333                         default:
 334                                 fprintf(stderr, "Unknown message type!\\n");
 335                                 break;
 336                 }
 337         } while (1);
 338
 339         ipq_destroy_handle(h);
 340         return 0;
 341 }
 342 .RE
 343 .fi
 344 .PP
 345 .\"O Pointers to more libipq application examples may be found in The
 346 .\"O Netfilter FAQ.
 347 libipq を使ったアプリケーションの例は
 348 Netfilter FAQ にもある。
 349 .\"O .SH DIAGNOSTICS
 350 .SH DIAGNOSTICS
 351 .\"O For information about monitoring and tuning ip_queue, refer to the
 352 .\"O Linux 2.4 Packet Filtering HOWTO.
 353 ip_queue の監視とチューニングに関しては Linux 2.4 Packet
 354 Filtering HOWTO を参照すること。
 355 .PP
 356 .\"O If an application modifies a packet, it needs to also update any
 357 .\"O checksums for the packet.  Typically, the kernel will silently discard
 358 .\"O modified packets with invalid checksums.
 359 アプリケーションがパケットに変更を加えた時には、関連する
 360 チェックサムも変更する必要がある。 変更されたパケットの
 361 チェックサムが異常なときにはカーネルは黙って破棄 (silently discard) する。
 362 .\"O .SH SECURITY
 363 .SH セキュリティー
 364 .\"O Processes require CAP_NET_ADMIN capabilty to access the kernel ip_queue
 365 .\"O module.  Such processes can potentially access and modify any IP packets
 366 .\"O received, generated or forwarded by the kernel.
 367 ip_queue カーネルモジュールにアクセスするプロセスは
 368 CAP_NET_ADMIN 権限が必要である。 そのようなプロセスは、
 369 潜在的にカーネルが受信 (送信、転送) する全ての IP パケットを
 370 取得し変更する可能性がある。
 371 .\"O .SH TODO
 372 .SH TODO
 373 .\"O Per-handle
 374 .\"O .B ipq_errno
 375 .\"O values.
 376 .B ipq_errno
 377 をハンドルごとに用意する。
 378 .\"O .SH BUGS
 379 .SH バグ
 380 .\"O Probably.
 381 あるかもしれない。
 382 .\"O .SH AUTHOR
 383 .SH 著者
 384 James Morris <jmorris@intercode.com.au>
 385 .\"O .SH COPYRIGHT
 386 .SH 著作権
 387 Copyright (c) 2000-2001 Netfilter Core Team.
 388 .PP
 389 Distributed under the GNU General Public License.
 390 .SH CREDITS
 391 .\"O Joost Remijn implemented the
 392 .\"O .B ipq_read
 393 .\"O timeout feature, which appeared in the 1.2.4 release of iptables.
 394 Joost Remijn は
 395 .B ipq_read
 396 のタイムアウトを実装した。 この機能は iptables の 1.2.4 から使用できる。
 397 .\"O .SH SEE ALSO
 398 .SH 関連項目
 399 .BR iptables (8),
 400 .BR ipq_create_handle (3),
 401 .BR ipq_destroy_handle (3),
 402 .BR ipq_errstr (3),
 403 .BR ipq_get_msgerr (3),
 404 .BR ipq_get_packet (3),
 405 .BR ipq_message_type (3),
 406 .BR ipq_perror (3),
 407 .BR ipq_read (3),
 408 .BR ipq_set_mode (3),
 409 .BR ipq_set_verdict (3).
 410 .PP
 411 .\"O The Netfilter home page at http://netfilter.samba.org/
 412 .\"O which has links to The Networking Concepts HOWTO, The Linux 2.4 Packet
 413 .\"O Filtering HOWTO, The Linux 2.4 NAT HOWTO, The Netfilter Hacking HOWTO,
 414 .\"O The Netfilter FAQ and many other useful resources.
 415 Netfilter のホームページは http://netfilter.samba.org/ にある。
 416 The Networking Concepts HOWTO, The Linux 2.4 Packet
 417 Filtering HOWTO, The Linux 2.4 NAT HOWTO, The Netfilter Hacking HOWTO,
 418 The Netfilter FAQ などの有益な 情報がある。