|author||Duncan Roe <email@example.com>||2019-11-02 21:29:52 +1100|
|committer||Pablo Neira Ayuso <firstname.lastname@example.org>||2019-11-04 19:05:06 +0100|
src: doc: Update the Main Page to be nft-focussed
Updated: src/libnetfilter_queue.c: - ip_queue withdrawn in kernel 3.5 - Update some URLs - libmnl is a dependency - Multiword section headers need a tag - Re-work cinematic to refer to nft - Some native English speaker updates (e.g. enqueue *is* a word) - Prefer nf-queue.c over deprecated doxygen doco Signed-off-by: Duncan Roe <email@example.com> Signed-off-by: Pablo Neira Ayuso <firstname.lastname@example.org>
1 files changed, 37 insertions, 26 deletions
diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c
index 0ab5030..cd14825 100644
@@ -39,49 +39,60 @@
* libnetfilter_queue is a userspace library providing an API to packets that
* have been queued by the kernel packet filter. It is is part of a system that
- * deprecates the old ip_queue / libipq mechanism.
+ * replaces the old ip_queue / libipq mechanism (withdrawn in kernel 3.5).
* libnetfilter_queue homepage is:
- * http://netfilter.org/projects/libnetfilter_queue/
+ * https://netfilter.org/projects/libnetfilter_queue/
- * \section Dependencies
- * libnetfilter_queue requires libnfnetlink and a kernel that includes the
- * nfnetlink_queue subsystem (i.e. 2.6.14 or later).
+ * \section deps Dependencies
+ * libnetfilter_queue requires libmnl, libnfnetlink and a kernel that includes
+ * the Netfilter NFQUEUE over NFNETLINK interface (i.e. 2.6.14 or later).
- * \section Main Features
+ * \section features Main Features
* - receiving queued packets from the kernel nfnetlink_queue subsystem
- * - issuing verdicts and/or reinjecting altered packets to the kernel
+ * - issuing verdicts and possibly 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.
+ * The cinematic is the following: When an nft rule with action **queue**
+ * matches, the kernel terminates the current nft chain and enqueues the packet
+ * in a chained list. It then formats and sends an nfnetlink message containing
+ * the packet id and whatever information the userspace program configured to
+ * receive (packet data and/or metadata) via a socket to the userspace program.
- * 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.
+ * The userspace program must issue a verdict advising the kernel to **accept**
+ * or **drop** the packet. Either verdict takes the packet off the queue:
+ * **drop** discards the packet while
+ * **accept** passes it on to the next chain.
+ * Userspace can also alter packet contents or metadata (e.g. packet mark,
+ * contrack mark). 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.
+ * When a queue is full, packets that should have been enqueued are dropped by
+ * kernel instead of being enqueued.
- * \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.
+ * \section git Git Tree
+ * The current development version of libnetfilter_queue can be accessed at
+ * https://git.netfilter.org/libnetfilter_queue.
- * \section Privileges
+ * \section privs Privileges
* You need the CAP_NET_ADMIN capability in order to allow your application
* to receive from and to send packets to kernel-space.
- * \section Using libnetfilter_queue
+ * \section using Using libnetfilter_queue
- * To write your own program using libnetfilter_queue, you should start by reading
- * the doxygen documentation (start by \link LibrarySetup \endlink page) and
+ * To write your own program using libnetfilter_queue, you should start by
+ * reading (or, if feasible, compiling and stepping through with *gdb*)
* nf-queue.c source file.
+ * Simple compile line:
+ * \verbatim
+gcc -g3 -ggdb -Wall -lmnl -lnetfilter_queue -o nf-queue nf-queue.c
+ * The doxygen documentation \link LibrarySetup \endlink is Deprecated and
+ * incompatible with non-deprecated functions. It is hoped to produce a
+ * corresponding non-deprecated (*Current*) topic soon.
- * Another source of information on libnetfilter_queue usage is the following
+ * Somewhat outdated but possibly providing some insight into
+ * libnetfilter_queue usage is the following