[PATCH libnetfilter_queue 0/2] src: doc: Main Page updates

[PATCH libnetfilter_queue 0/2] src: doc: Main Page updates

[Duncan Roe]

This is a first pass at modernising the Main Page.
Please, get back to me quickly with any disagreement about the new content:
the next phase of updates will be modifying the same file.
(next phase is to address the numerous doxygen warnings regarding argument
descriptions that don't match prototype).
I suspect the Privileges section should also specify CAP_NET_RAW,
but haven't had time to test this.

Duncan Roe (2):
  src: whitespace: Eliminate useless spaces before tabs
  src: doc: Update the Main Page to be nft-focusssed

 src/libnetfilter_queue.c | 83 ++++++++++++++++++++++++++++--------------------
 1 file changed, 48 insertions(+), 35 deletions(-)

-- 
2.14.5

[PATCH libnetfilter_queue 1/2] src: whitespace: Eliminate useless spaces before tabs

[Duncan Roe]

The extra spaces had no effect on how the file looked (except cat -A).

This patch reduces the file size by a few bytes, but the main motivation was
that my editor makes this change automatically.

Updated:

 src/libnetfilter_queue.c: Leading whitespace is canonically tabbed

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 src/libnetfilter_queue.c | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c
index 7014878..0ab5030 100644
--- a/src/libnetfilter_queue.c
+++ b/src/libnetfilter_queue.c
@@ -510,7 +510,7 @@ int nfq_unbind_pf(struct nfq_handle *h, uint16_t pf)
  * The nfq_callback type is defined in libnetfilter_queue.h as:
  * \verbatim
 typedef int nfq_callback(struct nfq_q_handle *qh,
-		    	 struct nfgenmsg *nfmsg,
+			 struct nfgenmsg *nfmsg,
 			 struct nfq_data *nfad, void *data);
 \endverbatim
  *
@@ -831,7 +831,7 @@ static int __set_verdict(struct nfq_q_handle *qh, uint32_t id,
 	int id;
 	struct nfqnl_msg_packet_hdr *ph = nfq_get_msg_packet_hdr(tb);
 	if (ph)
- 		id = ntohl(ph->packet_id);
+		id = ntohl(ph->packet_id);
 \endverbatim
  *
  * Notifies netfilter of the userspace verdict for the given packet.  Every
@@ -1077,15 +1077,15 @@ uint32_t nfq_get_physoutdev(struct nfq_data *nfad)
  * during all your program life:
  * \verbatim
 	h = nlif_open();
- 	if (h == NULL) {
- 		perror("nlif_open");
- 		exit(EXIT_FAILURE);
- 	}
+	if (h == NULL) {
+		perror("nlif_open");
+		exit(EXIT_FAILURE);
+	}
 \endverbatim
  * Once the handler is open, you need to fetch the interface table at a
  * whole via a call to nlif_query.
  * \verbatim
-  	nlif_query(h);
+	nlif_query(h);
 \endverbatim
  * libnfnetlink is able to update the interface mapping when a new interface
  * appears. To do so, you need to call nlif_catch() on the handler after each
@@ -1093,11 +1093,11 @@ uint32_t nfq_get_physoutdev(struct nfq_data *nfad)
  * a select() or poll() against the nlif file descriptor. To get this file 
  * descriptor, you need to use nlif_fd:
  * \verbatim
- 	if_fd = nlif_fd(h);
+	if_fd = nlif_fd(h);
 \endverbatim
  * Don't forget to close the handler when you don't need the feature anymore:
  * \verbatim
- 	nlif_close(h);
+	nlif_close(h);
 \endverbatim
  *
  */
-- 
2.14.5

[PATCH libnetfilter_queue 2/2] src: doc: Update the Main Page to be nft-focussed

[Duncan Roe]

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 <duncan_roe@optusnet.com.au>
---
 src/libnetfilter_queue.c | 65 +++++++++++++++++++++++++++++-------------------
 1 file changed, 39 insertions(+), 26 deletions(-)

diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c
index 0ab5030..7033174 100644
--- a/src/libnetfilter_queue.c
+++ b/src/libnetfilter_queue.c
@@ -39,49 +39,62 @@
  *
  * 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.
- *
- * 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
+ * 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.
+ *
+ * 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
+\endverbatim
+ * 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
  * article:
  *  https://home.regit.org/netfilter-en/using-nfqueue-and-libnetfilter_queue/
  *
-- 
2.14.5

Re: [PATCH libnetfilter_queue 0/2] src: doc: Main Page updates

[Pablo Neira Ayuso]

On Sat, Nov 02, 2019 at 09:29:50PM +1100, Duncan Roe wrote:
> This is a first pass at modernising the Main Page.

Applied, thanks.