From 3c57ff87b1b2ba034398ef34a5bed972ac68c23b Mon Sep 17 00:00:00 2001
From: Phil Sutter <phil@nwl.cc>
Date: Thu, 14 Jun 2018 14:02:11 +0200
Subject: doc: Add libnftables man page

For now, use a single man page to describe all the functions exported by
libnftables.

Signed-off-by: Phil Sutter <phil@nwl.cc>
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
---
 doc/libnftables.adoc | 315 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 315 insertions(+)
 create mode 100644 doc/libnftables.adoc

(limited to 'doc/libnftables.adoc')

diff --git a/doc/libnftables.adoc b/doc/libnftables.adoc
new file mode 100644
index 00000000..c947ef37
--- /dev/null
+++ b/doc/libnftables.adoc
@@ -0,0 +1,315 @@
+libnftables(3)
+==============
+Phil Sutter <phil@nwl.cc>
+:doctype: manpage
+:compat-mode!:
+
+== NAME
+libnftables - nftables frontend library
+
+== SYNOPSIS
+[verse]
+____
+*#include <nftables/libnftables.h>
+
+struct nft_ctx *nft_ctx_new(uint32_t* 'flags'*);
+void nft_ctx_free(struct nft_ctx* '\*ctx'*);
+
+bool nft_ctx_get_dry_run(struct nft_ctx* '\*ctx'*);
+void nft_ctx_set_dry_run(struct nft_ctx* '\*ctx'*, bool* 'dry'*);
+
+enum nft_numeric_level nft_ctx_output_get_numeric(struct nft_ctx* '\*ctx'*);
+void nft_ctx_output_set_numeric(struct nft_ctx* '\*ctx'*,
+				enum nft_numeric_level* 'level'*);
+
+bool nft_ctx_output_get_stateless(struct nft_ctx* '\*ctx'*);
+void nft_ctx_output_set_stateless(struct nft_ctx* '\*ctx'*, bool* 'val'*);
+
+bool nft_ctx_output_get_ip2name(struct nft_ctx* '\*ctx'*);
+void nft_ctx_output_set_ip2name(struct nft_ctx* '\*ctx'*, bool* 'val'*);
+
+unsigned int nft_ctx_output_get_debug(struct nft_ctx* '\*ctx'*);
+void nft_ctx_output_set_debug(struct nft_ctx* '\*ctx'*, unsigned int* 'mask'*);
+
+bool nft_ctx_output_get_handle(struct nft_ctx* '\*ctx'*);
+void nft_ctx_output_set_handle(struct nft_ctx* '\*ctx'*, bool* 'val'*);
+
+bool nft_ctx_output_get_echo(struct nft_ctx* '\*ctx'*);
+void nft_ctx_output_set_echo(struct nft_ctx* '\*ctx'*, bool* 'val'*);
+
+bool nft_ctx_output_get_json(struct nft_ctx* '\*ctx'*);
+void nft_ctx_output_set_json(struct nft_ctx* '\*ctx'*, bool* 'val'*);
+
+FILE *nft_ctx_set_output(struct nft_ctx* '\*ctx'*, FILE* '\*fp'*);
+int nft_ctx_buffer_output(struct nft_ctx* '\*ctx'*);
+int nft_ctx_unbuffer_output(struct nft_ctx* '\*ctx'*);
+const char *nft_ctx_get_output_buffer(struct nft_ctx* '\*ctx'*);
+
+FILE *nft_ctx_set_error(struct nft_ctx* '\*ctx'*, FILE* '\*fp'*);
+int nft_ctx_buffer_error(struct nft_ctx* '\*ctx'*);
+int nft_ctx_unbuffer_error(struct nft_ctx* '\*ctx'*);
+const char *nft_ctx_get_error_buffer(struct nft_ctx* '\*ctx'*);
+
+int nft_ctx_add_include_path(struct nft_ctx* '\*ctx'*, const char* '\*path'*);
+void nft_ctx_clear_include_paths(struct nft_ctx* '\*ctx'*);
+
+int nft_run_cmd_from_buffer(struct nft_ctx* '\*nft'*,
+			    char* '\*buf'*, size_t* 'buflen'*);
+int nft_run_cmd_from_filename(struct nft_ctx* '\*nft'*,
+			      const char* '\*filename'*);*
+
+Link with '-lnftables'.
+____
+
+== DESCRIPTION
+This library was designed with nftables integration into applications in mind.
+It's API is therefore kept as simple as possible, which somewhat limits its flexibility.
+Due to support for JSON markup of input and output though, convenience in constructing and parsing of input and output data may be achieved by using a third-party library such as *libjansson*.
+
+At the very basic level, one has to allocate a new object of type *struct nft_ctx* using *nft_ctx_new*() function, then pass commands via *nft_run_cmd_from_buffer*() or *nft_run_cmd_from_filename*() functions.
+By default, any output is written to *stdout* (or *stderr* for error messages).
+These file pointers may be changed using *nft_ctx_set_output*() and *nft_ctx_set_error*() functions.
+On top of that, it is possible to have any output buffered by the library for later retrieval as a static buffer.
+See *nft_ctx_buffer_output*() and *nft_ctx_buffer_error*() functions for details.
+
+=== nft_ctx_new() and nft_ctx_free()
+These functions aid in nft context management.
+In order to make use of the library, at least one context object has to be allocated.
+The context holds temporary data such as caches, library configuration and (if enabled) output and error buffers.
+
+The *nft_ctx_new*() function allocates and returns a new context object.
+The parameter 'flags' is unused at this point and should be set to zero.
+For convenience, the macro *NFT_CTX_DEFAULT* is defined to that value.
+
+The *nft_ctx_free*() function frees the context object pointed to by 'ctx' including any caches or buffers it may hold.
+
+=== nft_ctx_get_dry_run() and nft_ctx_set_dry_run()
+Dry-run setting controls whether ruleset changes are actually committed on kernel side or not.
+It allows to check whether a given operation would succeed without making actual changes to the ruleset.
+The default setting is *false*.
+
+The *nft_ctx_get_dry_run*() function returns the dry-run setting's value contained in 'ctx'.
+
+The *nft_ctx_set_dry_run*() function sets the dry-run setting in 'ctx' to the value of 'dry'.
+
+=== nft_ctx_output_get_numeric() and nft_ctx_output_set_numeric()
+These functions allow control over value representation in library output.
+For instance, port numbers by default are printed by their name (as listed in '/etc/services' file), if known.
+In libnftables, numeric output is leveled, defined as such:
+
+----
+enum nft_numeric_level {
+        NFT_NUMERIC_NONE,
+        NFT_NUMERIC_ADDR,
+        NFT_NUMERIC_PORT,
+        NFT_NUMERIC_ALL,
+};
+----
+
+Each numeric level includes all previous ones:
+
+NFT_NUMERIC_NONE::
+	No conversion into numeric format happens, this is the default.
+NFT_NUMERIC_ADDR::
+	Network addresses are always converted into numeric format.
+NFT_NUMERIC_PORT::
+	Network services are always converted into numeric format.
+NFT_NUMERIC_ALL::
+	Everything is converted into numeric format.
+
+The default numeric level is *NFT_NUMERIC_NONE*.
+
+The *nft_ctx_output_get_numeric*() function returns the numeric output setting's value contained in 'ctx'.
+
+The *nft_ctx_output_set_numeric*() function sets the numeric output setting in 'ctx' to the value of 'level'.
+
+=== nft_ctx_output_get_stateless() and nft_ctx_output_set_stateless()
+In nftables, there are stateful objects, i.e. ruleset elements which carry run-time data.
+For example the *counter* statement holds packet and byte counter values, making it stateful.
+If stateless output has been requested, this data is omitted when printing ruleset elements.
+The default setting is *false*.
+
+
+The *nft_ctx_output_get_stateless*() function returns the stateless output setting's value in 'ctx'.
+
+The *nft_ctx_output_set_stateless*() function sets the stateless output setting in 'ctx' to the value of 'val'.
+
+=== nft_ctx_output_get_ip2name() and nft_ctx_output_set_ip2name()
+The ip2name setting controls whether reverse DNS lookups are performed for IP addresses when printing them.
+Note that this may add significant delay to *list* commands depending on DNS resolver speed.
+The default setting is *false*.
+
+The *nft_ctx_output_get_ip2name*() function returns the ip2name output setting's value in 'ctx'.
+
+The *nft_ctx_output_set_ip2name*() function sets the ip2name output setting in 'ctx' to the value of 'val'.
+
+=== nft_ctx_output_get_debug() and nft_ctx_output_set_debug()
+Libnftables supports separate debugging of different parts of its internals.
+To facilitate this, debugging output is controlled via a bit mask.
+The bits are defined as such:
+
+----
+enum nft_debug_level {
+        NFT_DEBUG_SCANNER               = 0x1,
+        NFT_DEBUG_PARSER                = 0x2,
+        NFT_DEBUG_EVALUATION            = 0x4,
+        NFT_DEBUG_NETLINK               = 0x8,
+        NFT_DEBUG_MNL                   = 0x10,
+        NFT_DEBUG_PROTO_CTX             = 0x20,
+        NFT_DEBUG_SEGTREE               = 0x40,
+};
+----
+
+NFT_DEBUG_SCANNER::
+	Print LEX debug output.
+NFT_DEBUG_PARSER::
+	Print YACC debug output.
+NFT_DEBUG_EVALUATION::
+	Print debug information about evaluation phase.
+NFT_DEBUG_NETLINK::
+	Print netlink debug output.
+NFT_DEBUG_MNL::
+	Print libmnl debug output.
+NFT_DEBUG_PROTO_CTX::
+	Print protocol context debug output.
+NFT_DEBUG_SEGTREE::
+	Print segtree (i.e. interval sets) debug output.
+
+The *nft_ctx_output_get_debug*() function returns the debug output setting's value in 'ctx'.
+
+The *nft_ctx_output_set_debug*() function sets the debug output setting in 'ctx' to the value of 'mask'.
+
+=== nft_ctx_output_get_handle() and nft_ctx_output_set_handle()
+Upon insertion into the ruleset, some elements are assigned a unique handle for identification purposes.
+For example, when deleting a table or chain, it may be identified either by name or handle.
+Rules on the other hand must be deleted by handle because there is no other way to uniquely identify them.
+These functions allow to control whether ruleset listings should include handles or not.
+The default setting is *false*.
+
+The *nft_ctx_output_get_handle*() function returns the handle output setting's value in 'ctx'.
+
+The *nft_ctx_output_set_handle*() function sets the handle output setting in 'ctx' to the value of 'val'.
+
+=== nft_ctx_output_get_echo() and nft_ctx_output_set_echo()
+The echo setting makes libnftables print the changes once they are committed to the kernel, just like a running instance of *nft monitor* would.
+Amongst other things, this allows to retrieve an added rule's handle atomically.
+The default setting is *false*.
+
+The *nft_ctx_output_get_echo*() function returns the echo output setting's value in 'ctx'.
+
+The *nft_ctx_output_set_echo*() function sets the echo output setting in 'ctx' to the value of 'val'.
+
+=== nft_ctx_output_get_json() and nft_ctx_output_set_json()
+If enabled at compile-time, libnftables accepts input in JSON format and is able to print output in JSON format as well.
+See *libnftables-json*(5) for a description of the supported schema.
+These functions control JSON output format, input is auto-detected.
+The default setting is *false*.
+
+The *nft_ctx_output_get_json*() function returns the JSON output setting's value in 'ctx'.
+
+The *nft_ctx_output_set_json*() function sets the JSON output setting in 'ctx' to the value of 'val'.
+
+=== Controlling library standard and error output
+By default, any output from the library (e.g., after a *list* command) is written to 'stdout' and any error messages are written to 'stderr'.
+To give applications control over them, there are functions to assign custom file pointers as well as having the library buffer what would be written for later retrieval in a static buffer.
+This buffer is guaranteed to be null-terminated and must not be freed.
+Note that the retrieval functions rewind the buffer position indicator.
+Further library output will probably overwrite the buffer content and potentially render it invalid (due to reallocation).
+
+The *nft_ctx_set_output*() and *nft_ctx_set_error*() functions set the output or error file pointer in 'ctx' to the value of 'fp'.
+They return the previous value to aid in temporary file pointer overrides.
+On error, these functions return NULL.
+This happens only if 'fp' is NULL or invalid (tested using *ferror*() function).
+
+The *nft_ctx_buffer_output*() and *nft_ctx_buffer_error*() functions enable library standard or error output buffering.
+The functions return zero on success, non-zero otherwise.
+This may happen if the internal call to *fopencookie*() failed.
+
+The *nft_ctx_unbuffer_output*() and *nft_ctx_unbuffer_error*() functions disable library standard  or error output buffering.
+On failure, the functions return non-zero which may only happen if buffering wasn't enabled at the time the function was called.
+
+The *nft_ctx_get_output_buffer*() and *nft_ctx_get_error_buffer*() functions return a pointer to the buffered output (which may be empty).
+
+=== nft_ctx_add_include_path() and nft_ctx_clear_include_path()
+The *include* command in nftables rulesets allows to outsource parts of the ruleset into a different file.
+The include path defines where these files are searched for.
+Libnftables allows to have a list of those paths which are searched in order.
+The default include path list contains a single compile-time defined entry (typically '/etc/').
+
+The *nft_ctx_add_include_path*() function extends the list of include paths in 'ctx' by the one pointed to in 'path'.
+The function returns zero on success or non-zero if memory allocation failed.
+
+The *nft_ctx_clear_include_paths*() function removes all include paths, even the built-in default one.
+
+=== nft_run_cmd_from_buffer() and nft_run_cmd_from_filename()
+These functions perform the actual work of parsing user input into nftables commands and executing them.
+
+The *nft_run_cmd_from_buffer*() function passes the command(s) contained in 'buf' with size 'buflen' to the library, respecting settings and state in 'nft'.
+
+The *nft_run_cmd_from_filename*() function passes the content of 'filename' to the library, respecting settings and state in 'nft'.
+
+Both functions return zero on success.
+A non-zero return code indicates an error while parsing or executing the command.
+This event should be accompanied by an error message written to library error output.
+
+== EXAMPLE
+----
+#include <stdio.h>
+#include <string.h>
+#include <nftables/libnftables.h>
+
+int main(void)
+{
+	char *list_cmd = "list ruleset";
+	struct nft_ctx *nft;
+	const char *output, *p;
+	char buf[256];
+	int rc = 0;
+
+	nft = nft_ctx_new(NFT_CTX_DEFAULT);
+	if (!nft)
+		return 1;
+
+	while (1) {
+		if (nft_ctx_buffer_output(nft) ||
+		    nft_run_cmd_from_buffer(nft, list_cmd, strlen(list_cmd))) {
+			rc = 1;
+			break;
+		}
+		output = nft_ctx_get_output_buffer(nft);
+		if (strlen(output)) {
+			printf("\nThis is the current ruleset:\n| ");
+			for (p = output; *(p + 1); p++) {
+				if (*p == '\n')
+					printf("\n| ");
+				else
+					putchar(*p);
+			}
+			putchar('\n');
+		} else {
+			printf("\nCurrent ruleset is empty.\n");
+		}
+		nft_ctx_unbuffer_output(nft);
+
+		printf("\nEnter command ('q' to quit): ");
+		fflush(stdout);
+		fgets(buf, 256, stdin);
+		if (strlen(buf))
+			buf[strlen(buf) - 1] = '\0';
+
+		if (buf[0] == 'q' && buf[1] == '\0')
+			break;
+
+		if (nft_run_cmd_from_buffer(nft, buf, strlen(buf))) {
+			rc = 1;
+			break;
+		}
+	}
+
+	nft_ctx_free(nft);
+	return rc;
+}
+----
+
+== SEE ALSO
+*libnftables-json*(5), *nft*(8)
-- 
cgit v1.2.3

