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 one 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_input_get_flags() and nft_ctx_input_set_flags()¶

The flags setting controls the input format.

enum {


        NFT_CTX_INPUT_NO_DNS = (1 << 0),


        NFT_CTX_INPUT_JSON   = (1 << 1),
};

NFT_CTX_INPUT_NO_DNS

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.

The nft_ctx_input_get_flags() function returns the input flags setting’s value in ctx.

The nft_ctx_input_set_flags() function sets the input flags setting in ctx to the value of val and returns the previous flags.

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),
};

NFT_CTX_OUTPUT_REVERSEDNS

NFT_CTX_OUTPUT_SERVICE

NFT_CTX_OUTPUT_STATELESS

NFT_CTX_OUTPUT_HANDLE

NFT_CTX_OUTPUT_JSON

NFT_CTX_OUTPUT_ECHO

NFT_CTX_OUTPUT_GUID

NFT_CTX_OUTPUT_NUMERIC_PROTO

NFT_CTX_OUTPUT_NUMERIC_PRIO

NFT_CTX_OUTPUT_NUMERIC_SYMBOL

NFT_CTX_OUTPUT_NUMERIC_TIME

NFT_CTX_OUTPUT_NUMERIC_ALL

NFT_CTX_OUTPUT_TERSE

The nft_ctx_output_get_flags() function returns the output flags setting’s value in ctx.

The nft_ctx_output_set_flags() function sets the output flags 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

NFT_DEBUG_PARSER

NFT_DEBUG_EVALUATION

NFT_DEBUG_NETLINK

NFT_DEBUG_MNL

NFT_DEBUG_PROTO_CTX

NFT_DEBUG_SEGTREE

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.

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 was not 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 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/).

The nft_ctx_add_include_path() function extends the list of include paths in ctx by the one given 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_ctx_add_var() and nft_ctx_clear_vars()¶

The define command in nftables ruleset allows one to define variables.

The nft_ctx_add_var() function extends the list of variables in ctx. The variable must be given in the format key=value. The function returns zero on success or non-zero if the variable is malformed.

The nft_ctx_clear_vars() function removes all 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.

The nft_run_cmd_from_buffer() function passes the command(s) contained in buf (which must be null-terminated) 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.