Copyright (c) 2000-2001 Netfilter Core Team
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
For each supported protocol, a kernel module called a queue handler may register with Netfilter to perform the mechanics of passing packets to and from userspace.
The standard queue handler for IPv4 is ip_queue. It is provided as an experimental module with 2.4 kernels, and uses a Netlink socket for kernel/userspace communication.
Once ip_queue is loaded, IP packets may be selected with iptables and queued for userspace processing via the QUEUE target. For example, running the following commands:
# modprobe iptable_filter # modprobe ip_queue # iptables -A OUTPUT -p icmp -j QUEUE
will cause any locally generated ICMP packets (e.g. ping output) to be sent to the ip_queue module, which will then attempt to deliver the packets to a userspace application. If no userspace application is waiting, the packets will be dropped
An application may receive and process these packets via libipq.
Initialisation To initialise the library, call ipq_create_handle (3). This will attempt to bind to the Netlink socket used by ip_queue and return an opaque context handle for subsequent library calls.
Setting the Queue Mode ipq_set_mode (3) allows the application to specify whether packet metadata, or packet payloads as well as metadata are copied to userspace. It is also used to initially notify ip_queue that an application is ready to receive queue messages.
Receiving Packets from the Queue ipq_read (3) waits for queue messages to arrive from ip_queue and copies them into a supplied buffer. Queue messages may be packet messages or error messages.
The type of packet may be determined with ipq_message_type (3).
If it's a packet message, the metadata and optional payload may be retrieved with ipq_get_packet (3).
To retrieve the value of an error message, use ipq_get_msgerr (3).
Issuing Verdicts on Packets To issue a verdict on a packet, and optionally return a modified version of the packet to the kernel, call ipq_set_verdict (3).
Error Handling An error string corresponding to the current value of the internal error variable ipq_errno may be obtained with ipq_errstr (3).
For simple applications, calling ipq_perror (3) will print the same message as ipq_errstr (3), as well as the string corresponding to the global errno value (if set) to stderr.
Cleaning Up To free up the Netlink socket and destroy resources associated with the context handle, call ipq_destroy_handle (3).
4 ipq_create_handle (3) Initialise library, return context handle.
ipq_set_mode (3) Set the queue mode, to copy either packet metadata, or payloads as well as metadata to userspace.
ipq_read (3) Wait for a queue message to arrive from ip_queue and read it into a buffer.
ipq_message_type (3) Determine message type in the buffer.
ipq_get_packet (3) Retrieve a packet message from the buffer.
ipq_get_msgerr (3) Retrieve an error message from the buffer.
ipq_set_verdict (3) Set a verdict on a packet, optionally replacing its contents.
ipq_errstr (3) Return an error message corresponding to the internal ipq_errno variable.
ipq_perror (3) Helper function to print error messages to stderr.
ipq_destroy_handle (3) Destroy context handle and associated resources.
/* * This code is GPL. */ #include <linux/netfilter.h> #include <libipq.h> #include <stdio.h> #define BUFSIZE 2048 static void die(struct ipq_handle *h) { ipq_perror("passer"); ipq_destroy_handle(h); exit(1); } int main(int argc, char **argv) { int status; unsigned char buf[BUFSIZE]; struct ipq_handle *h; h = ipq_create_handle(0, NFPROTO_IPV4); if (!h) die(h); status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE); if (status < 0) die(h); do{ status = ipq_read(h, buf, BUFSIZE, 0); if (status < 0) die(h); switch (ipq_message_type(buf)) { case NLMSG_ERROR: fprintf(stderr, "Received error message %d\\n", ipq_get_msgerr(buf)); break; case IPQM_PACKET: { ipq_packet_msg_t *m = ipq_get_packet(buf); status = ipq_set_verdict(h, m->packet_id, NF_ACCEPT, 0, NULL); if (status < 0) die(h); break; } default: fprintf(stderr, "Unknown message type!\\n"); break; } } while (1); ipq_destroy_handle(h); return 0; }
Pointers to more libipq application examples may be found in The Netfilter FAQ.
If an application modifies a packet, it needs to also update any checksums for the packet. Typically, the kernel will silently discard modified packets with invalid checksums.
Distributed under the GNU General Public License.
Fernando Anton added support for IPv6.
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.
