diff options
Diffstat (limited to 'doc/libnftables.adoc')
-rw-r--r-- | doc/libnftables.adoc | 50 |
1 files changed, 45 insertions, 5 deletions
diff --git a/doc/libnftables.adoc b/doc/libnftables.adoc index ce4a361b..2cf78d7a 100644 --- a/doc/libnftables.adoc +++ b/doc/libnftables.adoc @@ -18,6 +18,9 @@ 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_input_get_flags(struct nft_ctx* '\*ctx'*); +unsigned int nft_ctx_input_set_flags(struct nft_ctx* '\*ctx'*, unsigned int* 'flags'*); + unsigned int nft_ctx_output_get_flags(struct nft_ctx* '\*ctx'*); void nft_ctx_output_set_flags(struct nft_ctx* '\*ctx'*, unsigned int* 'flags'*); @@ -37,6 +40,9 @@ 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'*);* @@ -68,13 +74,37 @@ The *nft_ctx_free*() function frees the context object pointed to by 'ctx', incl === 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 to check whether a given operation would succeed without making actual changes to the ruleset. +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:: + Avoid resolving IP addresses with blocking getaddrinfo(). In that case, + only plain IP addresses are accepted. + +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. @@ -93,6 +123,7 @@ enum { 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), }; @@ -114,10 +145,11 @@ NFT_CTX_OUTPUT_HANDLE:: 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. + 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. 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 to retrieve an added rule's handle atomically. + 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:: @@ -195,9 +227,9 @@ On failure, the functions return non-zero which may only happen if buffering was 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 to outsource parts of the ruleset into a different file. +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 to have a list of those paths which are searched in order. +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'. @@ -205,6 +237,14 @@ 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. |