[libnetfilter_queue PATCH 1/2] doxygen: improve fail-open documentation.

[libnetfilter_queue PATCH 1/2] doxygen: improve fail-open documentation.

[Eric Leblond]

---
 src/libnetfilter_queue.c |    8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c
index 9fe9dfa..f93ac66 100644
--- a/src/libnetfilter_queue.c
+++ b/src/libnetfilter_queue.c
@@ -87,6 +87,8 @@
  * (requires Linux kernel >= 2.6.30).
  * - see --queue-balance option in NFQUEUE target for multi-threaded apps
  * (it requires Linux kernel >= 2.6.31).
+ * - consider using fail-open option see nfq_set_queue_flags() (it requires
+ *  Linux kernel >= 3.6)
  */
 
 struct nfq_handle
@@ -620,6 +622,12 @@ int nfq_set_mode(struct nfq_q_handle *qh,
 	flags &= ~NFQA_CFG_F_FAIL_OPEN;
 	err = nfq_set_queue_flags(qh, mask, flags);
 \endverbatim
+ *
+ * If NFQA_CFG_F_FAIL_OPEN is used, the kernel will accept instead of
+ * drop packets that should have been enqueued to a full queue. This
+ * results in the system being able to handle high network load but at
+ * the depend of the control on the packets.
+ *
  * \return -1 on error with errno set appropriately; =0 otherwise.
  */
 int nfq_set_queue_flags(struct nfq_q_handle *qh,
-- 
1.7.10.4

[libnetfilter_queue PATCH 2/2] doxygen: improve documentation

[Eric Leblond]

This patch improves the doxygen documentation and adds a reference
to an external article.
---
 src/libnetfilter_queue.c |   22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c
index f93ac66..be25217 100644
--- a/src/libnetfilter_queue.c
+++ b/src/libnetfilter_queue.c
@@ -51,7 +51,21 @@
  *  - receiving queued packets from the kernel nfnetlink_queue subsystem
  *  - issuing verdicts and/or reinjecting altered packets to the kernel
  *  nfnetlink_queue subsystem
- * 
+ *
+ * The cinematic is the following: When an iptables rules with target NFQUEUE
+ * matches, the kernel en-queued the packet in a chained list. It then format
+ * a nfnetlink message and sends the information (packet data , packet id and
+ * metadata) via a socket to the software connected to the queue. The software
+ * can then read the message.
+ *
+ * To remove the packet from the queue, the userspace software must issue a
+ * verdict asking kernel to accept or drop the packet. Userspace can also alter
+ * the packet. Verdict can be done in asynchronous manner, as the only needed
+ * information is the packet id.
+ *
+ * When a queue is full, packets that should have been en-queued are dropped by
+ * kernel instead of being en-queued.
+ *
  * \section Git Tree
  * The current development version of libnetfilter_queue can be accessed
  * at https://git.netfilter.org/cgi-bin/gitweb.cgi?p=libnetfilter_queue.git;a=summary.
@@ -66,6 +80,10 @@
  * the doxygen documentation (start by \link LibrarySetup \endlink page) and
  * nf-queue.c source file.
  *
+ * Another source of information on libnetfilter_queue usage is the following
+ * article:
+ *  https://home.regit.org/netfilter-en/using-nfqueue-and-libnetfilter_queue/
+ *
  * \section errors ENOBUFS errors in recv()
  *
  * recv() may return -1 and errno is set to ENOBUFS in case that your
@@ -89,6 +107,8 @@
  * (it requires Linux kernel >= 2.6.31).
  * - consider using fail-open option see nfq_set_queue_flags() (it requires
  *  Linux kernel >= 3.6)
+ * - increase queue max length with nfq_set_queue_maxlen() to resist to packets
+ * burst
  */
 
 struct nfq_handle
-- 
1.7.10.4