libipq —— iptables用户空间数据包排队库

LIBIPQ(3)

NAME
libipq —— iptables用户空间数据包排队库

SYNOPSIS

#include <linux/netfilter.h>
#include <libipq.h>

DESCRIPTION
libipq是一个iptables用户空间数据包排队开发库。

用户空间数据包排队
Netfilter提供一个机制，将数据包送到栈外在用户空间排队，然后这些数据包送回内核并附带上一个如何处理这个数据包的决定（比如ACCEPT或DROP）。这些数据包在送回内核之前还可能在用户空间被修改。

对于每个支持的协议，内核模块调用一个Netfilter注册的队列handler以机械地将数据包送出到用户空间或从用户空间接回。

IPv4的标准的队列handler是ip_queue。其被作为一个2.4内核的实验模块提供，使用一个Netlink套接字在内核/用户空间交换数据。

一旦载入ip_queue，可以通过QUEUE目标将IP数据包挑选出来排队到用户空间处理。例如，运行下面的命令：

# modprobe iptable_filter
# modprobe ip_queue
# iptables -A OUTPUT -p icmp -j QUEUE

将导致任意本地产生的ICMP数据包（比如，ping的输出）被发送到ip_queue模块，此模块将尝试将这些数据包递送到用户空间的应用。如果没有用户空间的应用来处理它们，它们将被丢弃。

一个应用可以通过libipq接收和处理这些数据包。

Libipq概述
Libipq提供一组API以于ip_queue交互。下面是API用法的一个概述，细节参看各函数的手册页。

初始化
为了初始化此库，调用ipq_create_handle(3)。这将尝试与ip_queue使用的Netlink套接字捆绑并返回一个上下文无关的句柄，此句柄用于接下来的库调用。

设置排队模式
ipq_set_mode(3)允许应用指定拷贝到用户空间的数据，是仅数据包的元数据还是数据包负载和数据包元数据。这也用于告诉ip_queue一个应用已经准备好接收排队消息。

从队列中接收数据包
ipq_read(3)等待ip_queue的队列消息，并将它们拷贝到指定的缓冲。队列消息可以是数据包消息或错误消息。

可以通过ipq_message_type(3)确定数据包类型。

如果收到一个数据包消息，元数据和可选的负载可以通过ipq_get_packet(3)获取。

通过ipq_get_msgerr(3)获取一个错误消息的值。

对数据包下发判决
做出如何处理数据包的决定，可选的返回一个修改过的数据包给内核，可以调用ipq_set_verdict(3)。

错误处理
对应于内部错误变量ipq_errno的一个错误字符串可以通过ipq_errstr(3)获取。

对于简单的应用，调用ipq_perror(3)可以打印与ipq_errstr(3)相同的消息，还附带打印全局变量errno（如果设置了的话）的信息到stderr。

清理
调用ipq_destroy_handle(3)以释放Netlink套接字并销毁上下文句柄相关的资源。

SUMMARY
ipq_create_handle(3)
初始化库，返回上下文句柄。

ipq_set_mode(3)
设置排队模式，是仅拷贝数据包元数据，还是负载和元数据一起拷贝到用户空间。

ipq_read(3)
等待ip_queue送过来的排队消息，并将它读取到缓冲区。

ipq_message_type(3)
确定缓冲区里面的消息类型。

ipq_get_packet(3)
从缓冲区中获取一个数据包消息。

ipq_get_msgerr(3)
从缓冲区中获取一个错误消息。

ipq_set_verdict(3)
对一个数据包下达判决，可选的，替代它的内容。

ipq_errstr(3)
返回一个与内部ipq_errno变量相关的错误消息。

ipq_perror(3)
打印错误消息到stderr的助手函数。

ipq_destroy_handle(3)
销毁上下文句柄和关联的资源。

EXAMPLE
下面是一个简单应用的例子，它获取数据包并对每个数据包下达NF_ACCEPT判决。

更多libipq应用的例子可以在Netfilter的FAQ找到。

DIAGNOSTICS
有关ip_queue的检测和调节的信息，参见Linux 2.4 Packet Filtering的HOWTO。

如果一个应用修改一个数据包，它还需要更新此数据包的校验和。典型的，内核将丢弃那些校验和无效的数据包。

SECURITY
进程要求CAP_NET_ADMIN权限以访问内核ip_queue模块。这样的进程可以访问和修改任意由内核收到，生成，转发的IP数据包。

TODO
Per-handle ipq_errno values.

BUGS
Probably.

AUTHOR
James Morris <jmorris@intercode.com.au>

COPYRIGHT
Copyright (c) 2000-2001 Netfilter Core Team.

Distributed under the GNU General Public License.

CREDITS
Joost Remijn实现了ipq_read的超时特性，此特性出现在iptables的1.2.4释出版本。

Fernando Anton添加了IPv6的支持。

SEE ALSO
iptables(8), ipq_create_handle(3), ipq_destroy_handle(3),
ipq_errstr(3), ipq_get_msgerr(3), ipq_get_packet(3), ipq_mes‐
sage_type(3), ipq_perror(3), ipq_read(3), ipq_set_mode(3), ipq_set_ver‐
dict(3).

The Netfilter home page at http://netfilter.samba.org/ which has links
to The Networking Concepts HOWTO, The Linux 2.4 Packet Filtering HOWTO,
The Linux 2.4 NAT HOWTO, The Netfilter Hacking HOWTO, The Netfilter FAQ
and many other useful resources.