Libipq--iptables user space Packet Queuing library

LIBIPQ (3)

NAME
Libipq--iptables user space Packet Queuing library

Synopsis

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

DESCRIPTION
LIBIPQ is a iptables user space packet queuing development library.

User space Packet Queuing
NetFilter provides a mechanism for sending packets to the external user space of the stack and then sending the packets back to the kernel with a decision on how to handle the packet (such as accept or drop). These packets may also be modified in user space before being sent back to the kernel.

For each supported protocol, the kernel module invokes a NetFilter registered queue handler to mechanically send the packet out to the user space or back from the user space.

The standard queue handler for IPV4 is Ip_queue. It is provided as an experimental module for the 2.4 kernel and uses a NetLink socket to exchange data in the kernel/user space.

Once the Ip_queue is loaded, the IP packets can be picked up by the queue target to queue up to user space processing. For example, run the following command:

# modprobe Iptable_filter
# modprobe Ip_queue
# iptables-a Output-p icmp-j QUEUE

Will cause any locally generated ICMP packet (for example, the output of the ping) to be sent to the Ip_queue module, which will attempt to deliver these packets to the application of user space. If there are no user-space apps to process them, they will be discarded.

An app can receive and process these packets through LIBIPQ.

LIBIPQ Overview
LIBIPQ provides a set of APIs to interact with Ip_queue. Here is an overview of the API usage, which is detailed in the manual page of each function.

Initialization
In order to initialize this library, call Ipq_create_handle (3). This will attempt to bundle with the netlink socket used by Ip_queue and return a context-independent handle for the next library call.

Setting the queuing mode
Ipq_set_mode (3) allows the application to specify the data to be copied to the user space, whether it is only the metadata of the packet or the packet payload and packet metadata. This is also used to tell Ip_queue that an app is ready to receive queued messages.

Receiving packets from the queue
Ipq_read (3) waits for Ip_queue queue messages and copies them to the specified buffer. A queue message can be a packet message or an error message.

The packet type can be determined by Ipq_message_type (3).

If a packet message is received, the metadata and optional payload can be obtained through Ipq_get_packet (3).

Gets the value of an error message by Ipq_get_msgerr (3).

The decision on the packet is issued
To make a decision on how to handle the packet, optionally return a modified packet to the kernel, which can call Ipq_set_verdict (3).

Error handling
An error string corresponding to the internal error variable Ipq_errno can be obtained through IPQ_ERRSTR (3).

For a simple application, calling Ipq_perror (3) can print the same message as IPQ_ERRSTR (3), along with the printing of the global variable errno (if set) to stderr.

Clean
Call Ipq_destroy_handle (3) to release the NetLink socket and destroy the resource associated with the context handle.

SUMMARY
Ipq_create_handle (3)
Initializes the library, returning the context handle.

Ipq_set_mode (3)
Sets the queueing mode to copy only the packet metadata, or the load and metadata to the user space.

Ipq_read (3)
Wait for the queued message sent by Ip_queue and read it to the buffer.

Ipq_message_type (3)
Determines the type of message inside the buffer.

Ipq_get_packet (3)
Gets a packet message from the buffer.

Ipq_get_msgerr (3)
Gets an error message from the buffer.

Ipq_set_verdict (3)
A decision is placed on a packet, optionally, to replace its contents.

IPQ_ERRSTR (3)
Returns an error message associated with an internal ipq_errno variable.

Ipq_perror (3)
Print the error message to StdErr's helper function.

Ipq_destroy_handle (3)
Destroys the context handle and associated resources.

EXAMPLE
Here is an example of a simple application that takes a packet and releases a nf_accept judgment on each packet.

View Code

More examples of LIBIPQ applications can be found in the NetFilter FAQ.

Diagnostics
For information on the detection and regulation of ip_queue, see the howto of the Linux 2.4 Packet filtering.

If an app modifies a packet, it also needs to update the checksum for this packet. Typically, the kernel discards those checksum-invalid packets.

SECURITY
The process requires Cap_net_admin permissions to access the kernel Ip_queue module. Such a process can access and modify any IP packets that are received, generated, forwarded by the kernel.

Todo
Per-handle Ipq_errno values.

BUGS
Probably.

AUTHOR
James Morris <[email protected]>

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

Distributed under the GNU general public License.

CREDITS
The Joost Remijn implements the Ipq_read timeout feature, which appears in the 1.2.4 release version of Iptables.

Fernando Anton added support for 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 have 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.

Libipq--iptables user space Packet Queuing library