diff options
author | Duncan Roe <duncan_roe@optusnet.com.au> | 2019-11-02 21:29:52 +1100 |
---|---|---|
committer | Pablo Neira Ayuso <pablo@netfilter.org> | 2019-11-04 19:05:06 +0100 |
commit | f0eb6a9c15a5519daeb48ad43be4ac21af71bb2f (patch) | |
tree | a634e8545fd3fab209b96fff36f1c8fe26696803 /src | |
parent | fa1e826eff7a242327e0d478fdbf256821a69e1e (diff) |
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 <duncan_roe@optusnet.com.au>
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
Diffstat (limited to 'src')
-rw-r--r-- | src/libnetfilter_queue.c | 63 |
1 files changed, 37 insertions, 26 deletions
diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c index 0ab5030..cd14825 100644 --- a/src/libnetfilter_queue.c +++ b/src/libnetfilter_queue.c @@ -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 +\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/ * |