|
Packit Service |
d1fe03 |
.TH LIBIPQ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
|
|
Packit Service |
d1fe03 |
.\"
|
|
Packit Service |
d1fe03 |
.\" Copyright (c) 2000-2001 Netfilter Core Team
|
|
Packit Service |
d1fe03 |
.\"
|
|
Packit Service |
d1fe03 |
.\" This program is free software; you can redistribute it and/or modify
|
|
Packit Service |
d1fe03 |
.\" it under the terms of the GNU General Public License as published by
|
|
Packit Service |
d1fe03 |
.\" the Free Software Foundation; either version 2 of the License, or
|
|
Packit Service |
d1fe03 |
.\" (at your option) any later version.
|
|
Packit Service |
d1fe03 |
.\"
|
|
Packit Service |
d1fe03 |
.\" This program is distributed in the hope that it will be useful,
|
|
Packit Service |
d1fe03 |
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit Service |
d1fe03 |
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
Packit Service |
d1fe03 |
.\" GNU General Public License for more details.
|
|
Packit Service |
d1fe03 |
.\"
|
|
Packit Service |
d1fe03 |
.\" You should have received a copy of the GNU General Public License
|
|
Packit Service |
d1fe03 |
.\" along with this program; if not, write to the Free Software
|
|
Packit Service |
d1fe03 |
.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
Packit Service |
d1fe03 |
.\"
|
|
Packit Service |
d1fe03 |
.\"
|
|
Packit Service |
d1fe03 |
.SH NAME
|
|
Packit Service |
d1fe03 |
libipq \(em iptables userspace packet queuing library.
|
|
Packit Service |
d1fe03 |
.SH SYNOPSIS
|
|
Packit Service |
d1fe03 |
.B #include <linux/netfilter.h>
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
.B #include <libipq.h>
|
|
Packit Service |
d1fe03 |
.SH DESCRIPTION
|
|
Packit Service |
d1fe03 |
libipq is a development library for iptables userspace packet queuing.
|
|
Packit Service |
d1fe03 |
.SS Userspace Packet Queuing
|
|
Packit Service |
d1fe03 |
Netfilter provides a mechanism for passing packets out of the stack for
|
|
Packit Service |
d1fe03 |
queueing to userspace, then receiving these packets back into the kernel
|
|
Packit Service |
d1fe03 |
with a verdict specifying what to do with the packets (such as ACCEPT
|
|
Packit Service |
d1fe03 |
or DROP). These packets may also be modified in userspace prior to
|
|
Packit Service |
d1fe03 |
reinjection back into the kernel.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
For each supported protocol, a kernel module called a
|
|
Packit Service |
d1fe03 |
.I queue handler
|
|
Packit Service |
d1fe03 |
may register with Netfilter to perform the mechanics of passing
|
|
Packit Service |
d1fe03 |
packets to and from userspace.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
The standard queue handler for IPv4 is ip_queue. It is provided as an
|
|
Packit Service |
d1fe03 |
experimental module with 2.4 kernels, and uses a Netlink socket for
|
|
Packit Service |
d1fe03 |
kernel/userspace communication.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
Once ip_queue is loaded, IP packets may be selected with iptables
|
|
Packit Service |
d1fe03 |
and queued for userspace processing via the QUEUE target. For example,
|
|
Packit Service |
d1fe03 |
running the following commands:
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
# modprobe iptable_filter
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
# modprobe ip_queue
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
# iptables \-A OUTPUT \-p icmp \-j QUEUE
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
will cause any locally generated ICMP packets (e.g. ping output) to
|
|
Packit Service |
d1fe03 |
be sent to the ip_queue module, which will then attempt to deliver the
|
|
Packit Service |
d1fe03 |
packets to a userspace application. If no userspace application is waiting,
|
|
Packit Service |
d1fe03 |
the packets will be dropped
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
An application may receive and process these packets via libipq.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
.SS Libipq Overview
|
|
Packit Service |
d1fe03 |
Libipq provides an API for communicating with ip_queue. The following is
|
|
Packit Service |
d1fe03 |
an overview of API usage, refer to individual man pages for more details
|
|
Packit Service |
d1fe03 |
on each function.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
.B Initialisation
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
To initialise the library, call
|
|
Packit Service |
d1fe03 |
.BR ipq_create_handle (3).
|
|
Packit Service |
d1fe03 |
This will attempt to bind to the Netlink socket used by ip_queue and
|
|
Packit Service |
d1fe03 |
return an opaque context handle for subsequent library calls.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
.B Setting the Queue Mode
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
.BR ipq_set_mode (3)
|
|
Packit Service |
d1fe03 |
allows the application to specify whether packet metadata, or packet
|
|
Packit Service |
d1fe03 |
payloads as well as metadata are copied to userspace. It is also used to
|
|
Packit Service |
d1fe03 |
initially notify ip_queue that an application is ready to receive queue
|
|
Packit Service |
d1fe03 |
messages.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
.B Receiving Packets from the Queue
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
.BR ipq_read (3)
|
|
Packit Service |
d1fe03 |
waits for queue messages to arrive from ip_queue and copies
|
|
Packit Service |
d1fe03 |
them into a supplied buffer.
|
|
Packit Service |
d1fe03 |
Queue messages may be
|
|
Packit Service |
d1fe03 |
.I packet messages
|
|
Packit Service |
d1fe03 |
or
|
|
Packit Service |
d1fe03 |
.I error messages.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
The type of packet may be determined with
|
|
Packit Service |
d1fe03 |
.BR ipq_message_type (3).
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
If it's a packet message, the metadata and optional payload may be retrieved with
|
|
Packit Service |
d1fe03 |
.BR ipq_get_packet (3).
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
To retrieve the value of an error message, use
|
|
Packit Service |
d1fe03 |
.BR ipq_get_msgerr (3).
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
.B Issuing Verdicts on Packets
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
To issue a verdict on a packet, and optionally return a modified version
|
|
Packit Service |
d1fe03 |
of the packet to the kernel, call
|
|
Packit Service |
d1fe03 |
.BR ipq_set_verdict (3).
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
.B Error Handling
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
An error string corresponding to the current value of the internal error
|
|
Packit Service |
d1fe03 |
variable
|
|
Packit Service |
d1fe03 |
.B ipq_errno
|
|
Packit Service |
d1fe03 |
may be obtained with
|
|
Packit Service |
d1fe03 |
.BR ipq_errstr (3).
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
For simple applications, calling
|
|
Packit Service |
d1fe03 |
.BR ipq_perror (3)
|
|
Packit Service |
d1fe03 |
will print the same message as
|
|
Packit Service |
d1fe03 |
.BR ipq_errstr (3),
|
|
Packit Service |
d1fe03 |
as well as the string corresponding to the global
|
|
Packit Service |
d1fe03 |
.B errno
|
|
Packit Service |
d1fe03 |
value (if set) to stderr.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
.B Cleaning Up
|
|
Packit Service |
d1fe03 |
.br
|
|
Packit Service |
d1fe03 |
To free up the Netlink socket and destroy resources associated with
|
|
Packit Service |
d1fe03 |
the context handle, call
|
|
Packit Service |
d1fe03 |
.BR ipq_destroy_handle (3).
|
|
Packit Service |
d1fe03 |
.SH SUMMARY
|
|
Packit Service |
d1fe03 |
.TP 4
|
|
Packit Service |
d1fe03 |
.BR ipq_create_handle (3)
|
|
Packit Service |
d1fe03 |
Initialise library, return context handle.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_set_mode (3)
|
|
Packit Service |
d1fe03 |
Set the queue mode, to copy either packet metadata, or payloads
|
|
Packit Service |
d1fe03 |
as well as metadata to userspace.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_read (3)
|
|
Packit Service |
d1fe03 |
Wait for a queue message to arrive from ip_queue and read it into
|
|
Packit Service |
d1fe03 |
a buffer.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_message_type (3)
|
|
Packit Service |
d1fe03 |
Determine message type in the buffer.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_get_packet (3)
|
|
Packit Service |
d1fe03 |
Retrieve a packet message from the buffer.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_get_msgerr (3)
|
|
Packit Service |
d1fe03 |
Retrieve an error message from the buffer.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_set_verdict (3)
|
|
Packit Service |
d1fe03 |
Set a verdict on a packet, optionally replacing its contents.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_errstr (3)
|
|
Packit Service |
d1fe03 |
Return an error message corresponding to the internal ipq_errno variable.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_perror (3)
|
|
Packit Service |
d1fe03 |
Helper function to print error messages to stderr.
|
|
Packit Service |
d1fe03 |
.TP
|
|
Packit Service |
d1fe03 |
.BR ipq_destroy_handle (3)
|
|
Packit Service |
d1fe03 |
Destroy context handle and associated resources.
|
|
Packit Service |
d1fe03 |
.SH EXAMPLE
|
|
Packit Service |
d1fe03 |
The following is an example of a simple application which receives
|
|
Packit Service |
d1fe03 |
packets and issues NF_ACCEPT verdicts on each packet.
|
|
Packit Service |
d1fe03 |
.RS
|
|
Packit Service |
d1fe03 |
.nf
|
|
Packit Service |
d1fe03 |
/*
|
|
Packit Service |
d1fe03 |
* This code is GPL.
|
|
Packit Service |
d1fe03 |
*/
|
|
Packit Service |
d1fe03 |
#include <linux/netfilter.h>
|
|
Packit Service |
d1fe03 |
#include <libipq.h>
|
|
Packit Service |
d1fe03 |
#include <stdio.h>
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
#define BUFSIZE 2048
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
static void die(struct ipq_handle *h)
|
|
Packit Service |
d1fe03 |
{
|
|
Packit Service |
d1fe03 |
ipq_perror("passer");
|
|
Packit Service |
d1fe03 |
ipq_destroy_handle(h);
|
|
Packit Service |
d1fe03 |
exit(1);
|
|
Packit Service |
d1fe03 |
}
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
int main(int argc, char **argv)
|
|
Packit Service |
d1fe03 |
{
|
|
Packit Service |
d1fe03 |
int status;
|
|
Packit Service |
d1fe03 |
unsigned char buf[BUFSIZE];
|
|
Packit Service |
d1fe03 |
struct ipq_handle *h;
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
h = ipq_create_handle(0, NFPROTO_IPV4);
|
|
Packit Service |
d1fe03 |
if (!h)
|
|
Packit Service |
d1fe03 |
die(h);
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE);
|
|
Packit Service |
d1fe03 |
if (status < 0)
|
|
Packit Service |
d1fe03 |
die(h);
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
do{
|
|
Packit Service |
d1fe03 |
status = ipq_read(h, buf, BUFSIZE, 0);
|
|
Packit Service |
d1fe03 |
if (status < 0)
|
|
Packit Service |
d1fe03 |
die(h);
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
switch (ipq_message_type(buf)) {
|
|
Packit Service |
d1fe03 |
case NLMSG_ERROR:
|
|
Packit Service |
d1fe03 |
fprintf(stderr, "Received error message %d\\n",
|
|
Packit Service |
d1fe03 |
ipq_get_msgerr(buf));
|
|
Packit Service |
d1fe03 |
break;
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
case IPQM_PACKET: {
|
|
Packit Service |
d1fe03 |
ipq_packet_msg_t *m = ipq_get_packet(buf);
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
status = ipq_set_verdict(h, m->packet_id,
|
|
Packit Service |
d1fe03 |
NF_ACCEPT, 0, NULL);
|
|
Packit Service |
d1fe03 |
if (status < 0)
|
|
Packit Service |
d1fe03 |
die(h);
|
|
Packit Service |
d1fe03 |
break;
|
|
Packit Service |
d1fe03 |
}
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
default:
|
|
Packit Service |
d1fe03 |
fprintf(stderr, "Unknown message type!\\n");
|
|
Packit Service |
d1fe03 |
break;
|
|
Packit Service |
d1fe03 |
}
|
|
Packit Service |
d1fe03 |
} while (1);
|
|
Packit Service |
d1fe03 |
|
|
Packit Service |
d1fe03 |
ipq_destroy_handle(h);
|
|
Packit Service |
d1fe03 |
return 0;
|
|
Packit Service |
d1fe03 |
}
|
|
Packit Service |
d1fe03 |
.RE
|
|
Packit Service |
d1fe03 |
.fi
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
Pointers to more libipq application examples may be found in The
|
|
Packit Service |
d1fe03 |
Netfilter FAQ.
|
|
Packit Service |
d1fe03 |
.SH DIAGNOSTICS
|
|
Packit Service |
d1fe03 |
For information about monitoring and tuning ip_queue, refer to the
|
|
Packit Service |
d1fe03 |
Linux 2.4 Packet Filtering HOWTO.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
If an application modifies a packet, it needs to also update any
|
|
Packit Service |
d1fe03 |
checksums for the packet. Typically, the kernel will silently discard
|
|
Packit Service |
d1fe03 |
modified packets with invalid checksums.
|
|
Packit Service |
d1fe03 |
.SH SECURITY
|
|
Packit Service |
d1fe03 |
Processes require CAP_NET_ADMIN capabilty to access the kernel ip_queue
|
|
Packit Service |
d1fe03 |
module. Such processes can potentially access and modify any IP packets
|
|
Packit Service |
d1fe03 |
received, generated or forwarded by the kernel.
|
|
Packit Service |
d1fe03 |
.SH TODO
|
|
Packit Service |
d1fe03 |
Per-handle
|
|
Packit Service |
d1fe03 |
.B ipq_errno
|
|
Packit Service |
d1fe03 |
values.
|
|
Packit Service |
d1fe03 |
.SH BUGS
|
|
Packit Service |
d1fe03 |
Probably.
|
|
Packit Service |
d1fe03 |
.SH AUTHOR
|
|
Packit Service |
d1fe03 |
James Morris <jmorris@intercode.com.au>
|
|
Packit Service |
d1fe03 |
.SH COPYRIGHT
|
|
Packit Service |
d1fe03 |
Copyright (c) 2000-2001 Netfilter Core Team.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
Distributed under the GNU General Public License.
|
|
Packit Service |
d1fe03 |
.SH CREDITS
|
|
Packit Service |
d1fe03 |
Joost Remijn implemented the
|
|
Packit Service |
d1fe03 |
.B ipq_read
|
|
Packit Service |
d1fe03 |
timeout feature, which appeared in the 1.2.4 release of iptables.
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
Fernando Anton added support for IPv6.
|
|
Packit Service |
d1fe03 |
.SH SEE ALSO
|
|
Packit Service |
d1fe03 |
.BR iptables (8),
|
|
Packit Service |
d1fe03 |
.BR ipq_create_handle (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_destroy_handle (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_errstr (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_get_msgerr (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_get_packet (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_message_type (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_perror (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_read (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_set_mode (3),
|
|
Packit Service |
d1fe03 |
.BR ipq_set_verdict (3).
|
|
Packit Service |
d1fe03 |
.PP
|
|
Packit Service |
d1fe03 |
The Netfilter home page at http://netfilter.samba.org/
|
|
Packit Service |
d1fe03 |
which has links to The Networking Concepts HOWTO, The Linux 2.4 Packet
|
|
Packit Service |
d1fe03 |
Filtering HOWTO, The Linux 2.4 NAT HOWTO, The Netfilter Hacking HOWTO,
|
|
Packit Service |
d1fe03 |
The Netfilter FAQ and many other useful resources.
|
|
Packit Service |
d1fe03 |
|