NAME
libnftables - nftables frontend librarySYNOPSIS
#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); unsigned int nft_ctx_output_get_flags(struct nft_ctx *ctx); void nft_ctx_output_set_flags(struct nft_ctx *ctx, unsigned int flags); unsigned int nft_ctx_output_get_debug(struct nft_ctx *ctx); void nft_ctx_output_set_debug(struct nft_ctx *ctx, unsigned int mask); 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_ctx_add_var(struct nft_ctx *ctx, const char *var); void nft_ctx_clear_vars(struct nft_ctx \*ctx); int nft_run_cmd_from_buffer(struct nft_ctx* *nft, const char *buf); 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. 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 libjansson.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.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 one to check whether a given operation would succeed without making actual changes to the ruleset. The default setting is false.nft_ctx_output_get_flags() and nft_ctx_output_set_flags()
The flags setting controls the output format.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), };
Reverse DNS lookups are performed for IP
addresses when printing. Note that this may add significant delay to
list commands depending on DNS resolver speed.
NFT_CTX_OUTPUT_SERVICE
Print port numbers as services as described in
the /etc/services file.
NFT_CTX_OUTPUT_STATELESS
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 counter statement holds packet and byte counter
values, making it stateful.
NFT_CTX_OUTPUT_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. This flag makes ruleset listings include handle
values.
NFT_CTX_OUTPUT_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. This flag controls JSON output format, input is auto-detected.
NFT_CTX_OUTPUT_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 one to retrieve an
added rule’s handle atomically.
NFT_CTX_OUTPUT_GUID
Display UID and GID as described in the
/etc/passwd and /etc/group files.
NFT_CTX_OUTPUT_NUMERIC_PROTO
Display layer 4 protocol numerically.
NFT_CTX_OUTPUT_NUMERIC_PRIO
Display base chain priority numerically.
NFT_CTX_OUTPUT_NUMERIC_SYMBOL
Display expression datatype as numeric
value.
NFT_CTX_OUTPUT_NUMERIC_TIME
Display time, day and hour values in numeric
format.
NFT_CTX_OUTPUT_NUMERIC_ALL
Display all numerically.
NFT_CTX_OUTPUT_TERSE
If terse output has been requested, then the
contents of sets are not printed.
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, };
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.
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).nft_ctx_add_include_path() and nft_ctx_clear_include_path()
The include 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 /etc/).nft_ctx_add_var() and nft_ctx_clear_vars()
The define command in nftables ruleset allows one to define variables.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.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)) { 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)) { rc = 1; break; } } nft_ctx_free(nft); return rc; }
SEE ALSO
libnftables-json(5), nft(8)AUTHOR
Phil Sutter <[email protected]>Author.
09/16/2023 |