summaryrefslogtreecommitdiffstats
path: root/libipq/IPQ.notes.txt
diff options
context:
space:
mode:
authorMarc Boucher <marc@mbsi.ca>2000-03-20 06:03:29 +0000
committerMarc Boucher <marc@mbsi.ca>2000-03-20 06:03:29 +0000
commite6869a8f59d779ff4d5a0984c86d80db70784962 (patch)
treecbaf2a4e3f8249de3967b959a214c27ff5fdee2a /libipq/IPQ.notes.txt
reorganized tree after kernel merge
Diffstat (limited to 'libipq/IPQ.notes.txt')
-rw-r--r--libipq/IPQ.notes.txt118
1 files changed, 118 insertions, 0 deletions
diff --git a/libipq/IPQ.notes.txt b/libipq/IPQ.notes.txt
new file mode 100644
index 00000000..a2547fa4
--- /dev/null
+++ b/libipq/IPQ.notes.txt
@@ -0,0 +1,118 @@
+------------------------------------------------------------------------------------
+IPv4 Queuing Documentation
+------------------------------------------------------------------------------------
+
+Note: this file is temporary until the documentation is complete.
+
+Upgrade information:
+ * If upgrading from the queue device (v0.90.4 or below), you will need to
+ delete the old shared library, usually found in
+ /usr/local/lib/iptables/libipt_QUEUE.so
+
+TODO List:
+ * Non-blocking i/o for userspace api
+ * Buffered verdicts
+ * Reschedule processing if userspace busy
+ * Better session reliability
+ * Testsuite scripts, fix/improve tools
+ * Documentation
+ * Multiple queues per protocol?
+ * Performance analysis
+ * Userspace language bindings
+
+
+Overview:
+The following diagram is a conceptual view of how the queue operates:
+
+ +---------+
+ | QUEUE |
+ +---------+
+ | |
+ | +---+ | --> dequeue() --> nf_reinject() [stack]
+ | | V | |
+ | +---+ |
+ | |
+ | +---+ |
+ | | W | |
+ | +---+ |
+ | |
+ | +---+ |
+ | | V | |
+ | +---+ |
+ | |
+ | +---+ |
+ | | V | | <-- set_verdict() [user]
+ | +---+ |
+ | |
+ | +---+ |
+ | | W | |
+ | +---+ |
+ | |
+ | +---+ |
+ | | N | | --> notify_user() [user]
+ | +---+ |
+ | |
+ +---------+ <-- set_mode() [user]
+ ^
+ |
+ enqueue()
+ ^
+ |
+ nf_queue() [stack]
+
+
+The queue is processed via a kernel thread, which is woken up upon enqueue()
+set_mode() and set_verdict().
+
+As the queue is modal, and netlink is connectionless, a reasonable amount of
+state needs to be maintained.
+
+Packet states:
+N = new packet (default initial state)
+W = user notfied, waiting for verdict
+V = verdict set (usually by user)
+
+Queue states (settable by user):
+* HOLD (default initial state)
+enqueue packets
+do not notify user
+do not accept verdicts
+do not dequeue packets
+
+* NORMAL
+enqueue packets
+notify user of new packets (may copy entire packet)
+accept verdicts from user (may include modified packet)
+dequeue packets
+
+* FLUSH (returns to HOLD when queue is empty, unless terminating)
+do not enqueue packets
+do not not notify user
+set verdicts on all packets to NF_DROP
+dequeue all packets for dropping
+
+Note that for HOLD & NORMAL queue states, new packets are dropped if the
+queue is full.
+
+Known bugs:
+- Userspace app gets unknown message from kernel if it sends an invalid
+ message type (should get an NLMSG_ERROR).
+
+Documentation notes:
+libipq:
+- Queue is held after flush completes, user must either start copying
+ or shutdown or the queue will fill up.
+
+- If you get a IPQ_ERR_RTRUNC message, your local receive
+ buffer is probably too small. Netlink has no way of detecting
+ this, and thinks the message was delivered (technically, it was,
+ to your *socket* receive buffer though). Thus you need to respond
+ with an NF_DROP for the packet and use a bigger buffer.
+
+- If you modify a packet, you must recalculate checksums as
+ appropriate before sending it back.
+
+- The code wont stop you from doing this, but try not to set NF_QUEUE
+ verdict on packets.
+
+ \ No newline at end of file