From e6869a8f59d779ff4d5a0984c86d80db70784962 Mon Sep 17 00:00:00 2001
From: Marc Boucher <marc@mbsi.ca>
Date: Mon, 20 Mar 2000 06:03:29 +0000
Subject: reorganized tree after kernel merge

---
 libipq/IPQ.notes.txt | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 libipq/IPQ.notes.txt

(limited to 'libipq/IPQ.notes.txt')

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
-- 
cgit v1.2.3