Skip to content

Commit be8ddc6

Browse files
author
Matt Fox
committed
Specify any callback, no more use by inheritance
Change version to 0.3.0 Update and bugfixes in readme.rst
1 parent 76113a9 commit be8ddc6

File tree

5 files changed

+1014
-861
lines changed

5 files changed

+1014
-861
lines changed

‎README.rst

Lines changed: 41 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,16 @@ Example
1212

1313
The following script prints a short description of each packet before accepting it. ::
1414

15-
from netfilterqueue import QueueHandler
15+
from netfilterqueue import NetfilterQueue
1616
17-
class PacketPrinter(QueueHandler):
18-
def handle(self, packet):
19-
print packet
20-
packet.accept()
17+
def print_and_accept(pkt):
18+
print pkt
19+
pkt.accept()
2120
22-
p = PacketPrinter()
23-
p.bind(1)
21+
nfqueue = NetfilterQueue()
22+
nfqueue.bind(1, print_and_accept)
2423
try:
25-
p.run()
24+
nfqueue.run()
2625
except KeyboardInterrupt:
2726
print
2827

@@ -43,7 +42,7 @@ NetfilterQueue is a C extention module that links against libnetfilter_queue. Be
4342

4443
On Debian or Ubuntu, install these files with::
4544

46-
sudo apt-get install build-essential python-dev libnetfilter-queue-dev
45+
apt-get install build-essential python-dev libnetfilter-queue-dev
4746

4847
From PyPI
4948
---------
@@ -57,12 +56,12 @@ From source
5756

5857
To install from source::
5958

60-
wget http://pypi.python.org/packages/source/N/NetfilterQueue/NetfilterQueue-0.2.tar.gz
61-
tar -xvzf NetfilterQueue-0.2.tar.gz
62-
cd NetfilterQueue-0.2
59+
wget http://pypi.python.org/packages/source/N/NetfilterQueue/NetfilterQueue-0.3.tar.gz
60+
tar -xvzf NetfilterQueue-0.3.tar.gz
61+
cd NetfilterQueue-0.3
6362
python setup.py install
6463

65-
Setup will use Cython if it is installed, regenerating the .c source from the .pyx before compiling the .so.
64+
If Cython is installed, Distutils will use it to regenerate the .c source from the .pyx. It will then compile the .c into a .so.
6665

6766
API
6867
===
@@ -74,35 +73,32 @@ API
7473
``NetfilterQueue.COPY_PACKET``
7574
These constants specify how much of the packet should be given to the script- nothing, metadata, or the whole packet.
7675

77-
QueueHandler objects
78-
--------------------
76+
NetfilterQueue objects
77+
----------------------
7978

80-
You should define a class that inherits from QueueHandler and implenents the
81-
handle() method. Handle() is called for each packet that appears in the queue.
79+
A NetfilterQueue object represents a single queue. Configure your queue with
80+
a call to ``bind``, then start receiving packets with a call to ``run``.
8281

83-
``QueueHandler.bind(queue_num[, max_len[, mode[, range]]])``
82+
``QueueHandler.bind(queue_num, callback[, max_len[, mode[, range]]])``
8483
Create and bind to the queue. ``queue_num`` must match the number in your
85-
iptables rule. ``max_len`` sets the largest number of packets that can be
86-
in the queue; new packets are dropped if the size of the queue reaches this
87-
number. ``mode`` determines how much of the packet data is provided to
88-
your script. Use the constants above. ``range`` defines how many bytes of
89-
the packet you want to get. For example, if you only want the source and
90-
destination IPs of a IPv4 packet, ``range`` could be 20.
84+
iptables rule. ``callback`` is a function or method that takes one
85+
argument, a Packet object (see below). ``max_len`` sets the largest number
86+
of packets that can be in the queue; new packets are dropped if the size of
87+
the queue reaches this number. ``mode`` determines how much of the packet
88+
data is provided to your script. Use the constants above. ``range`` defines
89+
how many bytes of the packet you want to get. For example, if you only want
90+
the source and destination IPs of a IPv4 packet, ``range`` could be 20.
9191

9292
``QueueHandler.unbind()``
9393
Remove the queue. Packets matched by your iptables rule will be dropped.
9494

9595
``QueueHandler.run()``
96-
Begin accepting packets.
97-
98-
``QueueHandler.handle(packet)``
99-
Handle a single packet from the queue. You must call either
100-
``packet.accept()`` or ``packet.drop()``.
96+
Send packets to your callback. This method blocks.
10197

10298
Packet objects
10399
--------------
104100

105-
Objects of this type are passed to your handle() method.
101+
Objects of this type are passed to your callback.
106102

107103
``Packet.get_payload()``
108104
Return the packet's payload as a string.
@@ -118,11 +114,22 @@ Objects of this type are passed to your handle() method.
118114

119115
``Packet.drop()``
120116
Drop the packet.
117+
118+
Callback objects
119+
----------------
120+
121+
Your callback can be function or a method and must accept one argument, a
122+
Packet object. You must call either Packet.accept() or Packet.drop() before
123+
returning.
124+
125+
``callback(packet)`` or ``callback(self, packet)``
126+
Handle a single packet from the queue. You must call either
127+
``packet.accept()`` or ``packet.drop()``.
121128

122129
Usage
123130
=====
124131

125-
To route packets to the queue::
132+
To send packets to the queue::
126133

127134
iptables -I <table or chain> <match specification> -j NFQUEUE --queue-num <queue number>
128135
@@ -133,7 +140,7 @@ For example::
133140
The only special part of the rule is the target. Rules can have any match and
134141
can be added to any table or chain.
135142

136-
Valid queue numbers are integers from 0 to 65,536 inclusive.
143+
Valid queue numbers are integers from 0 to 65,535 inclusive.
137144

138145
To view libnetfilter_queue stats, refer to /proc/net/netfilter/nfnetlink_queue::
139146

@@ -158,7 +165,7 @@ The fields are:
158165

159166
8. Total number of packets sent to queue
160167

161-
9. Libnetfilter_queue internal use
168+
9. Something for libnetfilter_queue's internal use
162169

163170
Limitations
164171
===========
@@ -190,6 +197,5 @@ License
190197
=======
191198

192199
Copyright (c) 2011, Kerkhoff Technologies, Inc.
193-
All rights reserved.
194200

195-
Licensed under `BSD <https://github.com/kti/python-netfilterqueue/blob/master/LICENSE.txt>`_
201+
`MIT licensed <https://github.com/kti/python-netfilterqueue/blob/master/LICENSE.txt>`_

0 commit comments

Comments
 (0)