'\" t .\" Title: libnftables .\" Author: Phil Sutter .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 10/11/2023 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" .TH "LIBNFTABLES" "3" "10/11/2023" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" libnftables \- nftables frontend library .SH "SYNOPSIS" .sp .nf \fB#include struct nft_ctx *nft_ctx_new(uint32_t\fR \fIflags\fR\fB); void nft_ctx_free(struct nft_ctx\fR \fI*ctx\fR\fB); bool nft_ctx_get_dry_run(struct nft_ctx\fR \fI*ctx\fR\fB); void nft_ctx_set_dry_run(struct nft_ctx\fR \fI*ctx\fR\fB, bool\fR \fIdry\fR\fB); unsigned int nft_ctx_input_get_flags(struct nft_ctx\fR \fI*ctx\fR\fB); unsigned int nft_ctx_input_set_flags(struct nft_ctx\fR \fI*ctx\fR\fB, unsigned int\fR \fIflags\fR\fB); unsigned int nft_ctx_output_get_flags(struct nft_ctx\fR \fI*ctx\fR\fB); void nft_ctx_output_set_flags(struct nft_ctx\fR \fI*ctx\fR\fB, unsigned int\fR \fIflags\fR\fB); unsigned int nft_ctx_output_get_debug(struct nft_ctx\fR \fI*ctx\fR\fB); void nft_ctx_output_set_debug(struct nft_ctx\fR \fI*ctx\fR\fB, unsigned int\fR \fImask\fR\fB); FILE *nft_ctx_set_output(struct nft_ctx\fR \fI*ctx\fR\fB, FILE\fR \fI*fp\fR\fB); int nft_ctx_buffer_output(struct nft_ctx\fR \fI*ctx\fR\fB); int nft_ctx_unbuffer_output(struct nft_ctx\fR \fI*ctx\fR\fB); const char *nft_ctx_get_output_buffer(struct nft_ctx\fR \fI*ctx\fR\fB); FILE *nft_ctx_set_error(struct nft_ctx\fR \fI*ctx\fR\fB, FILE\fR \fI*fp\fR\fB); int nft_ctx_buffer_error(struct nft_ctx\fR \fI*ctx\fR\fB); int nft_ctx_unbuffer_error(struct nft_ctx\fR \fI*ctx\fR\fB); const char *nft_ctx_get_error_buffer(struct nft_ctx\fR \fI*ctx\fR\fB); int nft_ctx_add_include_path(struct nft_ctx\fR \fI*ctx\fR\fB, const char\fR \fI*path\fR\fB); void nft_ctx_clear_include_paths(struct nft_ctx\fR \fI*ctx\fR\fB); int nft_ctx_add_var(struct nft_ctx\fR \fI*ctx\fR\fB, const char\fR \fI*var\fR\fB); void nft_ctx_clear_vars(struct nft_ctx \fR\fB\fI\e*ctx\fR\fR); int nft_run_cmd_from_buffer(struct nft_ctx* \fI*nft\fR\fB, const char\fR \fI*buf\fR\fB); int nft_run_cmd_from_filename(struct nft_ctx\fR \fI*nft\fR\fB, const char\fR \fI*filename\fR\fB);\fR Link with \fI\-lnftables\fR\&. .fi .SH "DESCRIPTION" .sp This library was designed with nftables integration into applications in mind\&. Its 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 \fBlibjansson\fR\&. .sp At the very basic level, one has to allocate a new object of type \fBstruct nft_ctx\fR using \fBnft_ctx_new\fR() function, then pass commands via \fBnft_run_cmd_from_buffer\fR() or \fBnft_run_cmd_from_filename\fR() functions\&. By default, any output is written to \fBstdout\fR (or \fBstderr\fR for error messages)\&. These file pointers may be changed using \fBnft_ctx_set_output\fR() and \fBnft_ctx_set_error\fR() functions\&. On top of that, it is possible to have any output buffered by the library for later retrieval as a static buffer\&. See \fBnft_ctx_buffer_output\fR() and \fBnft_ctx_buffer_error\fR() functions for details\&. .SS "nft_ctx_new() and nft_ctx_free()" .sp 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\&. .sp The \fBnft_ctx_new\fR() function allocates and returns a new context object\&. The parameter \fIflags\fR is unused at this point and should be set to zero\&. For convenience, the macro \fBNFT_CTX_DEFAULT\fR is defined to that value\&. .sp The \fBnft_ctx_free\fR() function frees the context object pointed to by \fIctx\fR, including any caches or buffers it may hold\&. .SS "nft_ctx_get_dry_run() and nft_ctx_set_dry_run()" .sp Dry\-run setting controls whether ruleset changes are actually committed on kernel side or not\&. It allows one to check whether a given operation would succeed without making actual changes to the ruleset\&. The default setting is \fBfalse\fR\&. .sp The \fBnft_ctx_get_dry_run\fR() function returns the dry\-run setting\(cqs value contained in \fIctx\fR\&. .sp The \fBnft_ctx_set_dry_run\fR() function sets the dry\-run setting in \fIctx\fR to the value of \fIdry\fR\&. .SS "nft_ctx_input_get_flags() and nft_ctx_input_set_flags()" .sp The flags setting controls the input format\&. .sp .if n \{\ .RS 4 .\} .nf enum { NFT_CTX_INPUT_NO_DNS = (1 << 0), NFT_CTX_INPUT_JSON = (1 << 1), }; .fi .if n \{\ .RE .\} .PP NFT_CTX_INPUT_NO_DNS .RS 4 Avoid resolving IP addresses with blocking getaddrinfo()\&. In that case, only plain IP addresses are accepted\&. .RE .sp NFT_CTX_INPUT_JSON: When parsing the input, first try to interpret the input as JSON before falling back to the nftables format\&. This behavior is implied when setting the NFT_CTX_OUTPUT_JSON flag\&. .sp The \fBnft_ctx_input_get_flags\fR() function returns the input flags setting\(cqs value in \fIctx\fR\&. .sp The \fBnft_ctx_input_set_flags\fR() function sets the input flags setting in \fIctx\fR to the value of \fIval\fR and returns the previous flags\&. .SS "nft_ctx_output_get_flags() and nft_ctx_output_set_flags()" .sp The flags setting controls the output format\&. .sp .if n \{\ .RS 4 .\} .nf enum { NFT_CTX_OUTPUT_REVERSEDNS = (1 << 0), NFT_CTX_OUTPUT_SERVICE = (1 << 1), NFT_CTX_OUTPUT_STATELESS = (1 << 2), NFT_CTX_OUTPUT_HANDLE = (1 << 3), NFT_CTX_OUTPUT_JSON = (1 << 4), NFT_CTX_OUTPUT_ECHO = (1 << 5), NFT_CTX_OUTPUT_GUID = (1 << 6), NFT_CTX_OUTPUT_NUMERIC_PROTO = (1 << 7), NFT_CTX_OUTPUT_NUMERIC_PRIO = (1 << 8), NFT_CTX_OUTPUT_NUMERIC_SYMBOL = (1 << 9), NFT_CTX_OUTPUT_NUMERIC_TIME = (1 << 10), NFT_CTX_OUTPUT_NUMERIC_ALL = (NFT_CTX_OUTPUT_NUMERIC_PROTO | NFT_CTX_OUTPUT_NUMERIC_PRIO | NFT_CTX_OUTPUT_NUMERIC_SYMBOL | NFT_CTX_OUTPUT_NUMERIC_TIME), NFT_CTX_OUTPUT_TERSE = (1 << 11), }; .fi .if n \{\ .RE .\} .PP NFT_CTX_OUTPUT_REVERSEDNS .RS 4 Reverse DNS lookups are performed for IP addresses when printing\&. Note that this may add significant delay to \fBlist\fR commands depending on DNS resolver speed\&. .RE .PP NFT_CTX_OUTPUT_SERVICE .RS 4 Print port numbers as services as described in the /etc/services file\&. .RE .PP NFT_CTX_OUTPUT_STATELESS .RS 4 If stateless output has been requested, then stateful data is not printed\&. Stateful data refers to those objects that carry run\-time data, e\&.g\&. the \fBcounter\fR statement holds packet and byte counter values, making it stateful\&. .RE .PP NFT_CTX_OUTPUT_HANDLE .RS 4 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\&. This flag makes ruleset listings include handle values\&. .RE .PP NFT_CTX_OUTPUT_JSON .RS 4 If enabled at compile\-time, libnftables accepts input in JSON format and is able to print output in JSON format as well\&. See \fBlibnftables\-json\fR(5) for a description of the supported schema\&. This flag enables JSON output format\&. If the flag is set, the input will first be tried as JSON format, before falling back to nftables format\&. This flag implies NFT_CTX_INPUT_JSON\&. .RE .PP NFT_CTX_OUTPUT_ECHO .RS 4 The echo setting makes libnftables print the changes once they are committed to the kernel, just like a running instance of \fBnft monitor\fR would\&. Amongst other things, this allows one to retrieve an added rule\(cqs handle atomically\&. .RE .PP NFT_CTX_OUTPUT_GUID .RS 4 Display UID and GID as described in the /etc/passwd and /etc/group files\&. .RE .PP NFT_CTX_OUTPUT_NUMERIC_PROTO .RS 4 Display layer 4 protocol numerically\&. .RE .PP NFT_CTX_OUTPUT_NUMERIC_PRIO .RS 4 Display base chain priority numerically\&. .RE .PP NFT_CTX_OUTPUT_NUMERIC_SYMBOL .RS 4 Display expression datatype as numeric value\&. .RE .PP NFT_CTX_OUTPUT_NUMERIC_TIME .RS 4 Display time, day and hour values in numeric format\&. .RE .PP NFT_CTX_OUTPUT_NUMERIC_ALL .RS 4 Display all numerically\&. .RE .PP NFT_CTX_OUTPUT_TERSE .RS 4 If terse output has been requested, then the contents of sets are not printed\&. .RE .sp The \fBnft_ctx_output_get_flags\fR() function returns the output flags setting\(cqs value in \fIctx\fR\&. .sp The \fBnft_ctx_output_set_flags\fR() function sets the output flags setting in \fIctx\fR to the value of \fIval\fR\&. .SS "nft_ctx_output_get_debug() and nft_ctx_output_set_debug()" .sp 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: .sp .if n \{\ .RS 4 .\} .nf 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, }; .fi .if n \{\ .RE .\} .PP NFT_DEBUG_SCANNER .RS 4 Print LEX debug output\&. .RE .PP NFT_DEBUG_PARSER .RS 4 Print YACC debug output\&. .RE .PP NFT_DEBUG_EVALUATION .RS 4 Print debug information about evaluation phase\&. .RE .PP NFT_DEBUG_NETLINK .RS 4 Print netlink debug output\&. .RE .PP NFT_DEBUG_MNL .RS 4 Print libmnl debug output\&. .RE .PP NFT_DEBUG_PROTO_CTX .RS 4 Print protocol context debug output\&. .RE .PP NFT_DEBUG_SEGTREE .RS 4 Print segtree (i\&.e\&. interval sets) debug output\&. .RE .sp The \fBnft_ctx_output_get_debug\fR() function returns the debug output setting\(cqs value in \fIctx\fR\&. .sp The \fBnft_ctx_output_set_debug\fR() function sets the debug output setting in \fIctx\fR to the value of \fImask\fR\&. .SS "Controlling library standard and error output" .sp By default, any output from the library (e\&.g\&., after a \fBlist\fR command) is written to \fIstdout\fR and any error messages are written to \fIstderr\fR\&. 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)\&. .sp The \fBnft_ctx_set_output\fR() and \fBnft_ctx_set_error\fR() functions set the output or error file pointer in \fIctx\fR to the value of \fIfp\fR\&. They return the previous value to aid in temporary file pointer overrides\&. On error, these functions return NULL\&. This happens only if \fIfp\fR is NULL or invalid (tested using \fBferror\fR() function)\&. .sp The \fBnft_ctx_buffer_output\fR() and \fBnft_ctx_buffer_error\fR() 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 \fBfopencookie\fR() failed\&. .sp The \fBnft_ctx_unbuffer_output\fR() and \fBnft_ctx_unbuffer_error\fR() functions disable library standard or error output buffering\&. On failure, the functions return non\-zero which may only happen if buffering was not enabled at the time the function was called\&. .sp The \fBnft_ctx_get_output_buffer\fR() and \fBnft_ctx_get_error_buffer\fR() functions return a pointer to the buffered output (which may be empty)\&. .SS "nft_ctx_add_include_path() and nft_ctx_clear_include_path()" .sp The \fBinclude\fR command in nftables rulesets allows one to outsource parts of the ruleset into a different file\&. The include path defines where these files are searched for\&. Libnftables allows one 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 \fI/etc/\fR)\&. .sp The \fBnft_ctx_add_include_path\fR() function extends the list of include paths in \fIctx\fR by the one given in \fIpath\fR\&. The function returns zero on success or non\-zero if memory allocation failed\&. .sp The \fBnft_ctx_clear_include_paths\fR() function removes all include paths, even the built\-in default one\&. .SS "nft_ctx_add_var() and nft_ctx_clear_vars()" .sp The \fBdefine\fR command in nftables ruleset allows one to define variables\&. .sp The \fBnft_ctx_add_var\fR() function extends the list of variables in \fIctx\fR\&. The variable must be given in the format \fIkey=value\fR\&. The function returns zero on success or non\-zero if the variable is malformed\&. .sp The \fBnft_ctx_clear_vars\fR() function removes all variables\&. .SS "nft_run_cmd_from_buffer() and nft_run_cmd_from_filename()" .sp These functions perform the actual work of parsing user input into nftables commands and executing them\&. .sp The \fBnft_run_cmd_from_buffer\fR() function passes the command(s) contained in \fIbuf\fR (which must be null\-terminated) to the library, respecting settings and state in \fInft\fR\&. .sp The \fBnft_run_cmd_from_filename\fR() function passes the content of \fIfilename\fR to the library, respecting settings and state in \fInft\fR\&. .sp 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\&. .SH "EXAMPLE" .sp .if n \{\ .RS 4 .\} .nf #include #include #include 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)) { rc = 1; break; } output = nft_ctx_get_output_buffer(nft); if (strlen(output)) { printf("\enThis is the current ruleset:\en| "); for (p = output; *(p + 1); p++) { if (*p == \*(Aq\en\*(Aq) printf("\en| "); else putchar(*p); } putchar(\*(Aq\en\*(Aq); } else { printf("\enCurrent ruleset is empty\&.\en"); } nft_ctx_unbuffer_output(nft); printf("\enEnter command (\*(Aqq\*(Aq to quit): "); fflush(stdout); fgets(buf, 256, stdin); if (strlen(buf)) buf[strlen(buf) \- 1] = \*(Aq\e0\*(Aq; if (buf[0] == \*(Aqq\*(Aq && buf[1] == \*(Aq\e0\*(Aq) break; if (nft_run_cmd_from_buffer(nft, buf)) { rc = 1; break; } } nft_ctx_free(nft); return rc; } .fi .if n \{\ .RE .\} .SH "SEE ALSO" .sp \fBlibnftables\-json\fR(5), \fBnft\fR(8) .SH "AUTHOR" .PP \fBPhil Sutter\fR <\&phil@nwl\&.cc\&> .RS 4 Author. .RE