From 949810c35a0871d9173764e2ac3b4d814f982b9e Mon Sep 17 00:00:00 2001 From: James Morris Date: Mon, 20 Nov 2000 14:13:31 +0000 Subject: Initial commit of libipq man pages. --- libipq/libipq.3 | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 libipq/libipq.3 (limited to 'libipq/libipq.3') diff --git a/libipq/libipq.3 b/libipq/libipq.3 new file mode 100644 index 00000000..e7ccc697 --- /dev/null +++ b/libipq/libipq.3 @@ -0,0 +1,275 @@ +.TH LIBIPQ 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual" +.\" +.\" $Id: $ +.\" +.\" Copyright (c) 2000 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. +.\" +.\" +.SH NAME +libipq \- iptables userspace packet queuing library. +.SH SYNOPSIS +.B #include +.br +.B #include +.SH DESCRIPTION +libipq is a development library for iptables userspace packet queuing. +.SS Userspace Packet Queuing +Netfilter provides a mechanism for passing packets out of the stack for +queueing to userspace, then receiving these packets back into the kernel +with a verdict specifying what to do with the packets (such as ACCEPT +or DROP). These packets may also be modified in userspace prior to +reinjection back into the kernel. +.PP +For each supported protocol, a kernel module called a +.I queue handler +may register with Netfilter to perform the mechanics of passing +packets to and from userspace. +.PP +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. +.PP +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: +.PP + # modprobe iptable_filter +.br + # modprobe ip_queue +.br + # iptables -A OUTPUT -p icmp -j QUEUE +.PP +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 +.PP +An application may receive and process these packets via libipq. +.PP +.PP +.SS Libipq Overview +Libipq provides an API for communicating with ip_queue. The following is +an overview of API usage, refer to individual man pages for more details +on each function. +.PP +.B Initialisation +.br +To initialise the library, call +.BR 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. +.PP +.B Setting the Queue Mode +.br +.BR 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. +.PP +.B Receiving Packets from the Queue +.br +.BR ipq_read (3) +waits for queue messages to arrive from ip_queue and copies +them into a supplied buffer. +Queue messages may be +.I packet messages +or +.I error messages. +.PP +The type of packet may be determined with +.BR ipq_message_type (3). +.PP +If it's a packet message, the metadata and optional payload may be retrieved with +.BR ipq_get_packet (3). +.PP +To retrieve the value of an error message, use +.BR ipq_get_msgerr (3). +.PP +.B Issuing Verdicts on Packets +.br +To issue a verdict on a packet, and optionally return a modified version +of the packet to the kernel, call +.BR ipq_set_verdict (3). +.PP +.B Error Handling +.br +An error string corresponding to the current value of the internal error +variable +.B ipq_errno +may be obtained with +.BR ipq_errstr (3). +.PP +For simple applications, calling +.BR ipq_perror (3) +will print the same message as +.BR ipq_errstr (3), +as well as the string corresponding to the global +.B errno +value (if set) to stderr. +.PP +.B Cleaning Up +.br +To free up the Netlink socket and destroy resources associated with +the context handle, call +.BR ipq_destroy_handle (3). +.SH SUMMARY +.TP 4 +.BR ipq_create_handle (3) +Initialise library, return context handle. +.TP +.BR ipq_set_mode (3) +Set the queue mode, to copy either packet metadata, or payloads +as well as metadata to userspace. +.TP +.BR ipq_read (3) +Wait for a queue message to arrive from ip_queue and read it into +a buffer. +.TP +.BR ipq_message_type (3) +Determine message type in the buffer. +.TP +.BR ipq_get_packet (3) +Retrieve a packet message from the buffer. +.TP +.BR ipq_get_msgerr (3) +Retrieve an error message from the buffer. +.TP +.BR ipq_set_verdict (3) +Set a verdict on a packet, optionally replacing its contents. +.TP +.BR ipq_errstr (3) +Return an error message corresponding to the internal ipq_errno variable. +.TP +.BR ipq_perror (3) +Helper function to print error messages to stderr. +.TP +.BR ipq_destroy_handle (3) +Destroy context handle and associated resources. +.SH EXAMPLE +The following is an example of a simple application which receives +packets and issues NF_ACCEPT verdicts on each packet. +.RS +.nf +/* + * This code is GPL. + */ +#include +#include +#include + +#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); + 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; +} +.RE +.fi +.PP +Pointers to more libipq application examples may be found in The +Netfilter FAQ. +.SH DIAGNOSTICS +For information about monitoring and tuning ip_queue, refer to the +Linux 2.4 Packet Filtering HOWTO. +.PP +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. +.SH SECURITY +Processes require CAP_NET_ADMIN capabilty to access the kernel ip_queue +module. Such processes can potentially access and modify any IP packets +received, generated or forwarded by the kernel. +.SH TODO +Implement a non-blocking interface. +.br +Per-handle +.B ipq_errno +values. +.SH BUGS +Probably. +.SH AUTHOR +James Morris +.SH COPYRIGHT +Copyright (c) 2000 Netfilter Core Team. +.PP +Distributed under the GNU General Public License. +.SH SEE ALSO +.BR iptables (8), +.BR ipq_create_handle (3), +.BR ipq_destroy_handle (3), +.BR ipq_errstr (3), +.BR ipq_get_msgerr (3), +.BR ipq_get_packet (3), +.BR ipq_message_type (3), +.BR ipq_perror (3), +.BR ipq_read (3), +.BR ipq_set_mode (3), +.BR ipq_set_verdict (3). +.PP +The Netfilter home page at http://netfilter.kernelnotes.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. + -- cgit v1.2.3