path: root/doc/libnftables.3

'\" 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