path: root/doc/libnftables.adoc

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)