diff options
Diffstat (limited to 'doc/libnftables.3')
| -rw-r--r-- | doc/libnftables.3 | 393 |
1 files changed, 393 insertions, 0 deletions
diff --git a/doc/libnftables.3 b/doc/libnftables.3 new file mode 100644 index 0000000..4778a8e --- /dev/null +++ b/doc/libnftables.3 @@ -0,0 +1,393 @@ +'\" t +.\" Title: libnftables +.\" Author: Phil Sutter <phil@nwl.cc> +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" 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 <nftables/libnftables\&.h> + +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 <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)) { + 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 |