summaryrefslogtreecommitdiffstats
path: root/libipq
diff options
context:
space:
mode:
Diffstat (limited to 'libipq')
-rw-r--r--libipq/ipq_create_handle.378
-rw-r--r--libipq/ipq_destroy_handle.31
-rw-r--r--libipq/ipq_errstr.366
-rw-r--r--libipq/ipq_get_msgerr.31
-rw-r--r--libipq/ipq_get_packet.31
-rw-r--r--libipq/ipq_message_type.3136
-rw-r--r--libipq/ipq_perror.31
-rw-r--r--libipq/ipq_read.395
-rw-r--r--libipq/ipq_set_mode.3107
-rw-r--r--libipq/ipq_set_verdict.395
-rw-r--r--libipq/libipq.3275
11 files changed, 856 insertions, 0 deletions
diff --git a/libipq/ipq_create_handle.3 b/libipq/ipq_create_handle.3
new file mode 100644
index 00000000..5c981371
--- /dev/null
+++ b/libipq/ipq_create_handle.3
@@ -0,0 +1,78 @@
+.TH IPQ_CREATE_HANDLE 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
+ipq_create_handle, ipq_destroy_handle - create and destroy libipq handles.
+.SH SYNOPSIS
+.B #include <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.sp
+.BI "struct ipq_handle *ipq_create_handle(u_int32_t " flags );
+.br
+.BI "int ipq_destroy_handle(struct ipq_handle *" h );
+.SH DESCRIPTION
+The
+.B ipq_create_handle
+function initialises libipq for an application, attempts to bind to the
+Netlink socket used by ip_queue, and returns an opaque context handle. It
+should be the first libipq function to be called by an application. The
+handle returned should be used in all subsequent library calls which
+require a handle parameter.
+.PP
+The
+.I flags
+parameter is not currently used and should be set to zero by the application
+for forward compatibility.
+.PP
+The
+.B ipq_destroy_handle
+function frees up resources allocated by
+.BR ipq_create_handle ,
+and should be used when the handle is no longer required by the application.
+.SH RETURN VALUES
+On success,
+.B ipq_create_handle
+returns a pointer to a context handle.
+.br
+On failure, NULL is returned.
+.PP
+On success,
+.B ipq_destroy_handle
+returns zero.
+.br
+On failure, -1 is returned.
+.SH ERRORS
+On failure, a descriptive error message will be available
+via the
+.B ipq_errstr
+function.
+.SH BUGS
+None known.
+.SH AUTHOR
+James Morris <jmorris@intercode.com.au>
+.SH COPYRIGHT
+Copyright (c) 2000 Netfilter Core Team.
+.PP
+Distributed under the GNU General Public License.
+.SH SEE ALSO
+.BR iptables (8),
+.BR libipq (3).
diff --git a/libipq/ipq_destroy_handle.3 b/libipq/ipq_destroy_handle.3
new file mode 100644
index 00000000..29dcd985
--- /dev/null
+++ b/libipq/ipq_destroy_handle.3
@@ -0,0 +1 @@
+.so man3/ipq_create_handle.3
diff --git a/libipq/ipq_errstr.3 b/libipq/ipq_errstr.3
new file mode 100644
index 00000000..ec43ff6b
--- /dev/null
+++ b/libipq/ipq_errstr.3
@@ -0,0 +1,66 @@
+.TH IPQ_ERRSTR 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
+ipq_errstr, ipq_perror - libipq error handling routines
+.SH SYNOPSIS
+.B #include <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.sp
+.BI "char *ipq_errstr(" void );
+.br
+.BI "void ipq_perror(const char *" s );
+.SH DESCRIPTION
+The
+.B ipq_errstr
+function returns a descriptive error message based on the current
+value of the internal
+.B ipq_errno
+variable. All libipq API functions set this internal variable
+upon failure.
+.PP
+The
+.B ipq_perror
+function prints an error message to stderr corresponding to the
+current value of the internal
+.B ipq_error
+variable, and the global
+.B errno
+variable (if set). The error message is prefixed with the string
+.I s
+as supplied by the application. If
+.I s
+is NULL, the error message is prefixed with the string "ERROR".
+.SH RETURN VALUE
+.B ipq_errstr
+returns an error message as outlined above.
+.SH BUGS
+None known.
+.SH AUTHOR
+James Morris <jmorris@intercode.com.au>
+.SH COPYRIGHT
+Copyright (c) 2000 Netfilter Core Team.
+.PP
+Distributed under the GNU General Public License.
+.SH SEE ALSO
+.BR iptables (8),
+.BR libipq (3).
diff --git a/libipq/ipq_get_msgerr.3 b/libipq/ipq_get_msgerr.3
new file mode 100644
index 00000000..8a28be3d
--- /dev/null
+++ b/libipq/ipq_get_msgerr.3
@@ -0,0 +1 @@
+.so man3/ipq_message_type.3
diff --git a/libipq/ipq_get_packet.3 b/libipq/ipq_get_packet.3
new file mode 100644
index 00000000..8a28be3d
--- /dev/null
+++ b/libipq/ipq_get_packet.3
@@ -0,0 +1 @@
+.so man3/ipq_message_type.3
diff --git a/libipq/ipq_message_type.3 b/libipq/ipq_message_type.3
new file mode 100644
index 00000000..4a2de1dc
--- /dev/null
+++ b/libipq/ipq_message_type.3
@@ -0,0 +1,136 @@
+.TH IPQ_MESSAGE_TYPE 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
+ipq_message_type, ipq_get_packet, ipq_getmsgerr - query queue messages
+.SH SYNOPSIS
+.B #include <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.sp
+.BI "int ipq_message_type(const unsigned char *" buf ");"
+.br
+.BI "ipq_packet_msg_t *ipq_get_packet(const unsigned char *" buf ");"
+.br
+.BI "int ipq_get_msgerr(const unsigned char *" buf ");"
+.SH DESCRIPTION
+The
+.B ipq_message_type
+function returns the type of queue message returned to userspace
+via
+.BR ipq_read .
+.PP
+.B ipq_message_type
+should always be called following a successful call to
+.B ipq_read
+to determine whether the message is a packet message or an
+error message. The
+.I buf
+parameter should be the same data obtained from
+the previous call to
+.BR ipq_read .
+.PP
+.B ipq_message_type
+will return one of the following values:
+.TP
+.B NLMSG_ERROR
+An error message generated by the Netlink transport.
+.PP
+.TP
+.B IPQM_PACKET
+A packet message containing packet metadata and optional packet payload data.
+.PP
+The
+.B ipq_get_packet
+function should be called if
+.B ipq_message_type
+returns
+.BR IPQM_PACKET .
+The
+.I buf
+parameter should point to the same data used for the call to
+.BR ipq_message_type .
+The pointer returned by
+.B ipq_get_packet
+points to a packet message, which is declared as follows:
+.PP
+.RS
+.nf
+typedef struct ipq_packet_msg {
+ unsigned long packet_id; /* ID of queued packet */
+ unsigned long mark; /* Netfilter mark value */
+ long timestamp_sec; /* Packet arrival time (seconds) */
+ long timestamp_usec; /* Packet arrvial time (+useconds) */
+ unsigned int hook; /* Netfilter hook we rode in on */
+ char indev_name[IFNAMSIZ]; /* Name of incoming interface */
+ char outdev_name[IFNAMSIZ]; /* Name of outgoing interface */
+ unsigned short hw_protocol; /* Hardware protocol (network order) */
+ unsigned short hw_type; /* Hardware type */
+ unsigned char hw_addrlen; /* Hardware address length */
+ unsigned char hw_addr[8]; /* Hardware address */
+ size_t data_len; /* Length of packet data */
+ unsigned char payload[0]; /* Optional packet data */
+} ipq_packet_msg_t;
+.fi
+.RE
+.PP
+Each of these fields may be read by the application. If the queue mode
+is
+.B IPQ_COPY_PACKET
+and the
+.I data_len
+value is greater than zero, the packet payload contents may be accessed
+in the memory following the
+.B ipq_packet_msg_t
+structure to a range of
+.I data_len.
+.PP
+The
+.I packet_id
+field contains a packet identifier to be used when calling
+.BR ipq_set_verdict .
+.PP
+The
+.B ipq_get_msgerr
+function should be called if
+.B ipq_message_type
+returns
+.BR NLMSG_ERROR.
+The
+.I buf
+parameter should point to the same data used for the call to
+.BR ipq_message_type .
+The value returned by
+.B ipq_get_msgerr
+is set by higher level kernel code and corresponds to standard
+.B errno
+values.
+.SH BUGS
+None known.
+.SH AUTHOR
+James Morris <jmorris@intercode.com.au>
+.SH COPYRIGHT
+Copyright (c) 2000 Netfilter Core Team.
+.PP
+Distributed under the GNU General Public License.
+.SH SEE ALSO
+.BR iptables (8),
+.BR libipq (3).
diff --git a/libipq/ipq_perror.3 b/libipq/ipq_perror.3
new file mode 100644
index 00000000..6efd53d5
--- /dev/null
+++ b/libipq/ipq_perror.3
@@ -0,0 +1 @@
+.so man3/ipq_errstr.3
diff --git a/libipq/ipq_read.3 b/libipq/ipq_read.3
new file mode 100644
index 00000000..62763ca4
--- /dev/null
+++ b/libipq/ipq_read.3
@@ -0,0 +1,95 @@
+.TH IPQ_READ 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
+ipq_read - wait for queue messages from ip_queue and read into supplied buffer
+.SH SYNOPSIS
+.B #include <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.sp
+.BI "ssize_t ipq_read(const struct ipq_handle *" h ", unsigned char *" buf ", size_t " len ", int " timeout ");"
+.SH DESCRIPTION
+The
+.B ipq_read
+function waits for a queue message to arrive from the kernel and copies it to
+the memory pointed to by
+.I buf
+to a maximum length of
+. I len .
+.PP
+The
+.I h
+parameter is a context handle which must previously have been returned
+successfully from a call to
+.B ipq_create_handle .
+.PP
+The caller is responsible for ensuring that the memory pointed to by
+.I buf
+is large enough to contain
+.I len
+bytes.
+.PP
+The
+.I timeout
+parameter is not currently implemented.
+.PP
+Data returned via
+.I buf
+should not be accessed directly. Use the
+.BR ipq_message_type ,
+.BR ipq_get_packet ", and"
+.BR ipq_get_msgerr
+functions to access the queue message in the buffer.
+.SH RETURN VALUE
+On failure, -1 is returned.
+.br
+On success, a non-zero positive value is returned.
+.SH ERRORS
+On error, a descriptive error message will be available
+via the
+.B ipq_errstr
+function.
+.SH DIAGNOSTICS
+While the
+.B ipq_read
+function may return successfully, the queue message copied to the buffer
+may itself be an error message from a higher level kernel component. Use
+.B ipq_message_type
+to determine if it is an error message, and
+.B ipq_get_msgerr
+to access the value of the message.
+.SH TODO
+Implement
+.I timeout
+as part of a non-blocking interface.
+.SH BUGS
+None known.
+.SH AUTHOR
+James Morris <jmorris@intercode.com.au>
+.SH COPYRIGHT
+Copyright (c) 2000 Netfilter Core Team.
+.PP
+Distributed under the GNU General Public License.
+.SH SEE ALSO
+.BR iptables (8),
+.BR libipq (3).
+
diff --git a/libipq/ipq_set_mode.3 b/libipq/ipq_set_mode.3
new file mode 100644
index 00000000..ad1d0e95
--- /dev/null
+++ b/libipq/ipq_set_mode.3
@@ -0,0 +1,107 @@
+.TH IPQ_SET_MODE 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
+ipq_set_mode - set the ip_queue queuing mode
+.SH SYNOPSIS
+.B #include <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.sp
+.BI "int ipq_set_mode(const struct ipq_handle *" h ", u_int8_t " mode ", size_t " range );
+.SH DESCRIPTION
+The
+.B ipq_set_mode
+function sends a message to the kernel ip_queue module, specifying whether
+packet metadata only, or packet payloads as well as metadata should be copied to
+userspace.
+.PP
+The
+.I h
+parameter is a context handle which must previously have been returned
+successfully from a call to
+.BR ipq_create_handle .
+.PP
+The
+.I mode
+parameter must be one of:
+.TP
+.B IPQ_COPY_META
+Copy only packet metadata to userspace.
+.TP
+.B IPQ_COPY_PACKET
+Copy packet metadata and packet payloads to userspace.
+.PP
+The
+.I range
+parameter is used to specify how many bytes of the payload to copy
+to userspace. It is only valid for
+.B IPQ_COPY_PACKET
+mode and is otherwise ignored. The maximum useful value for
+.I range
+is 65535 (greater values will be clamped to this by ip_queue).
+.PP
+.B ipq_set_mode
+is usually used immediately following
+.B ipq_create_handle
+to enable the flow of packets to userspace.
+.PP
+Note that as the underlying Netlink messaging transport is connectionless,
+the ip_queue module does not know that a userspace application is ready to
+communicate until it receives a message such as this.
+.SH RETURN VALUE
+On failure, -1 is returned.
+.br
+On success, a non-zero positive value is returned.
+.SH ERRORS
+On failure, a descriptive error message will be available
+via the
+.B ipq_errstr
+function.
+.SH DIAGNOSTICS
+A relatively common failure may occur if the ip_queue module is not loaded.
+In this case, the following code excerpt:
+.PP
+.RS
+.nf
+status = ipq_set_mode(h, IPQ_COPY_META, 0);
+if (status < 0) {
+ ipq_perror("myapp");
+ ipq_destroy_handle(h);
+ exit(1);
+}
+.RE
+.fi
+.PP
+would generate the following output:
+.PP
+.I myapp: Failed to send netlink message: Connection refused
+.SH BUGS
+None known.
+.SH AUTHOR
+James Morris <jmorris@intercode.com.au>
+.SH COPYRIGHT
+Copyright (c) 2000 Netfilter Core Team.
+.PP
+Distributed under the GNU General Public License.
+.SH SEE ALSO
+.BR libipq (3),
+.BR iptables (8).
diff --git a/libipq/ipq_set_verdict.3 b/libipq/ipq_set_verdict.3
new file mode 100644
index 00000000..de4ccdbf
--- /dev/null
+++ b/libipq/ipq_set_verdict.3
@@ -0,0 +1,95 @@
+.TH IPQ_SET_VERDICT 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
+ipq_set_verdict - issue verdict and optionally modified packet to kernel
+.SH SYNOPSIS
+.B #include <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.sp
+.BI "int ipq_set_verdict(const struct ipq_handle *" h ", ipq_id_t " id ", unsigned int " verdict ", size_t " data_len ", unsigned char *" buf ");"
+.SH DESCRIPTION
+The
+.B ipq_set_verdict
+function issues a verdict on a packet previously obtained with
+.BR ipq_read ,
+specifing the intended disposition of the packet, and optionally
+supplying a modified version of the payload data.
+.PP
+The
+.I h
+parameter is a context handle which must previously have been returned
+successfully from a call to
+.BR ipq_create_handle .
+.PP
+The
+.I id
+parameter is the packet identifier obtained via
+.BR ipq_get_packet .
+.PP
+The
+.I verdict
+parameter must be one of:
+.TP
+.B NF_ACCEPT
+Accept the packet and continue traversal within the kernel.
+.br
+.TP
+.B NF_DROP
+Drop the packet.
+.PP
+The
+.I data_len
+parameter is the length of the data pointed to
+by
+.IR buf ,
+the optional replacement payload data.
+.PP
+If simply setting a verdict without modifying the payload data, use zero
+for
+.I data_len
+and NULL for
+.IR buf .
+.PP
+The application is responsible for recalculating any packet checksums
+when modifying packets.
+.SH RETURN VALUE
+On failure, -1 is returned.
+.br
+On success, a non-zero positive value is returned.
+.SH ERRORS
+On error, a descriptive error message will be available
+via the
+.B ipq_errstr
+function.
+.SH BUGS
+None known.
+.SH AUTHOR
+James Morris <jmorris@intercode.com.au>
+.SH COPYRIGHT
+Copyright (c) 2000 Netfilter Core Team.
+.PP
+Distributed under the GNU General Public License.
+.SH SEE ALSO
+.BR iptables (8),
+.BR 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 <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.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 <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);
+ 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 <jmorris@intercode.com.au>
+.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.
+