1LIBNFTABLES(3)                                                  LIBNFTABLES(3)
2
3
4

NAME

6       libnftables - nftables frontend library
7

SYNOPSIS

9       #include <nftables/libnftables.h>
10
11       struct nft_ctx *nft_ctx_new(uint32_t flags);
12       void nft_ctx_free(struct nft_ctx *ctx);
13
14       bool nft_ctx_get_dry_run(struct nft_ctx *ctx);
15       void nft_ctx_set_dry_run(struct nft_ctx *ctx, bool dry);
16
17       unsigned int nft_ctx_output_get_flags(struct nft_ctx *ctx);
18       void nft_ctx_output_set_flags(struct nft_ctx *ctx, unsigned int flags);
19
20       unsigned int nft_ctx_output_get_debug(struct nft_ctx *ctx);
21       void nft_ctx_output_set_debug(struct nft_ctx *ctx, unsigned int mask);
22
23       FILE *nft_ctx_set_output(struct nft_ctx *ctx, FILE *fp);
24       int nft_ctx_buffer_output(struct nft_ctx *ctx);
25       int nft_ctx_unbuffer_output(struct nft_ctx *ctx);
26       const char *nft_ctx_get_output_buffer(struct nft_ctx *ctx);
27
28       FILE *nft_ctx_set_error(struct nft_ctx *ctx, FILE *fp);
29       int nft_ctx_buffer_error(struct nft_ctx *ctx);
30       int nft_ctx_unbuffer_error(struct nft_ctx *ctx);
31       const char *nft_ctx_get_error_buffer(struct nft_ctx *ctx);
32
33       int nft_ctx_add_include_path(struct nft_ctx *ctx, const char *path);
34       void nft_ctx_clear_include_paths(struct nft_ctx *ctx);
35
36       int nft_run_cmd_from_buffer(struct nft_ctx *nft, const char *buf);
37       int nft_run_cmd_from_filename(struct nft_ctx *nft,
38                                     const char *filename);
39
40       Link with -lnftables.
41

DESCRIPTION

43       This library was designed with nftables integration into applications
44       in mind. Its API is therefore kept as simple as possible, which
45       somewhat limits its flexibility. Due to support for JSON markup of
46       input and output though, convenience in constructing and parsing of
47       input and output data may be achieved by using a third-party library
48       such as libjansson.
49
50       At the very basic level, one has to allocate a new object of type
51       struct nft_ctx using nft_ctx_new() function, then pass commands via
52       nft_run_cmd_from_buffer() or nft_run_cmd_from_filename() functions. By
53       default, any output is written to stdout (or stderr for error
54       messages). These file pointers may be changed using
55       nft_ctx_set_output() and nft_ctx_set_error() functions. On top of that,
56       it is possible to have any output buffered by the library for later
57       retrieval as a static buffer. See nft_ctx_buffer_output() and
58       nft_ctx_buffer_error() functions for details.
59
60   nft_ctx_new() and nft_ctx_free()
61       These functions aid in nft context management. In order to make use of
62       the library, at least one context object has to be allocated. The
63       context holds temporary data such as caches, library configuration and
64       (if enabled) output and error buffers.
65
66       The nft_ctx_new() function allocates and returns a new context object.
67       The parameter flags is unused at this point and should be set to zero.
68       For convenience, the macro NFT_CTX_DEFAULT is defined to that value.
69
70       The nft_ctx_free() function frees the context object pointed to by ctx,
71       including any caches or buffers it may hold.
72
73   nft_ctx_get_dry_run() and nft_ctx_set_dry_run()
74       Dry-run setting controls whether ruleset changes are actually committed
75       on kernel side or not. It allows to check whether a given operation
76       would succeed without making actual changes to the ruleset. The default
77       setting is false.
78
79       The nft_ctx_get_dry_run() function returns the dry-run setting’s value
80       contained in ctx.
81
82       The nft_ctx_set_dry_run() function sets the dry-run setting in ctx to
83       the value of dry.
84
85   nft_ctx_output_get_flags() and nft_ctx_output_set_flags()
86       The flags setting controls the output format.
87
88           enum {
89                   NFT_CTX_OUTPUT_REVERSEDNS     = (1 << 0),
90                   NFT_CTX_OUTPUT_SERVICE        = (1 << 1),
91                   NFT_CTX_OUTPUT_STATELESS      = (1 << 2),
92                   NFT_CTX_OUTPUT_HANDLE         = (1 << 3),
93                   NFT_CTX_OUTPUT_JSON           = (1 << 4),
94                   NFT_CTX_OUTPUT_ECHO           = (1 << 5),
95                   NFT_CTX_OUTPUT_GUID           = (1 << 6),
96                   NFT_CTX_OUTPUT_NUMERIC_PROTO  = (1 << 7),
97                   NFT_CTX_OUTPUT_NUMERIC_PRIO   = (1 << 8),
98                   NFT_CTX_OUTPUT_NUMERIC_SYMBOL = (1 << 9),
99                   NFT_CTX_OUTPUT_NUMERIC_TIME   = (1 << 10),
100                   NFT_CTX_OUTPUT_NUMERIC_ALL    = (NFT_CTX_OUTPUT_NUMERIC_PROTO |
101                                                    NFT_CTX_OUTPUT_NUMERIC_PRIO  |
102                                                    NFT_CTX_OUTPUT_NUMERIC_SYMBOL |
103                                                    NFT_CTX_OUTPUT_NUMERIC_TIME),
104                   NFT_CTX_OUTPUT_TERSE          = (1 << 11),
105           };
106
107       NFT_CTX_OUTPUT_REVERSEDNS
108           Reverse DNS lookups are performed for IP addresses when printing.
109           Note that this may add significant delay to list commands depending
110           on DNS resolver speed.
111
112       NFT_CTX_OUTPUT_SERVICE
113           Print port numbers as services as described in the /etc/services
114           file.
115
116       NFT_CTX_OUTPUT_STATELESS
117           If stateless output has been requested, then stateful data is not
118           printed. Stateful data refers to those objects that carry run-time
119           data, e.g. the counter statement holds packet and byte counter
120           values, making it stateful.
121
122       NFT_CTX_OUTPUT_HANDLE
123           Upon insertion into the ruleset, some elements are assigned a
124           unique handle for identification purposes. For example, when
125           deleting a table or chain, it may be identified either by name or
126           handle. Rules on the other hand must be deleted by handle, because
127           there is no other way to uniquely identify them. This flag makes
128           ruleset listings include handle values.
129
130       NFT_CTX_OUTPUT_JSON
131           If enabled at compile-time, libnftables accepts input in JSON
132           format and is able to print output in JSON format as well. See
133           libnftables-json(5) for a description of the supported schema. This
134           flag controls JSON output format, input is auto-detected.
135
136       NFT_CTX_OUTPUT_ECHO
137           The echo setting makes libnftables print the changes once they are
138           committed to the kernel, just like a running instance of nft
139           monitor would. Amongst other things, this allows to retrieve an
140           added rule’s handle atomically.
141
142       NFT_CTX_OUTPUT_GUID
143           Display UID and GID as described in the /etc/passwd and /etc/group
144           files.
145
146       NFT_CTX_OUTPUT_NUMERIC_PROTO
147           Display layer 4 protocol numerically.
148
149       NFT_CTX_OUTPUT_NUMERIC_PRIO
150           Display base chain priority numerically.
151
152       NFT_CTX_OUTPUT_NUMERIC_SYMBOL
153           Display expression datatype as numeric value.
154
155       NFT_CTX_OUTPUT_NUMERIC_TIME
156           Display time, day and hour values in numeric format.
157
158       NFT_CTX_OUTPUT_NUMERIC_ALL
159           Display all numerically.
160
161       NFT_CTX_OUTPUT_TERSE
162           If terse output has been requested, then the contents of sets are
163           not printed.
164
165       The nft_ctx_output_get_flags() function returns the output flags
166       setting’s value in ctx.
167
168       The nft_ctx_output_set_flags() function sets the output flags setting
169       in ctx to the value of val.
170
171   nft_ctx_output_get_debug() and nft_ctx_output_set_debug()
172       Libnftables supports separate debugging of different parts of its
173       internals. To facilitate this, debugging output is controlled via a bit
174       mask. The bits are defined as such:
175
176           enum nft_debug_level {
177                   NFT_DEBUG_SCANNER               = 0x1,
178                   NFT_DEBUG_PARSER                = 0x2,
179                   NFT_DEBUG_EVALUATION            = 0x4,
180                   NFT_DEBUG_NETLINK               = 0x8,
181                   NFT_DEBUG_MNL                   = 0x10,
182                   NFT_DEBUG_PROTO_CTX             = 0x20,
183                   NFT_DEBUG_SEGTREE               = 0x40,
184           };
185
186       NFT_DEBUG_SCANNER
187           Print LEX debug output.
188
189       NFT_DEBUG_PARSER
190           Print YACC debug output.
191
192       NFT_DEBUG_EVALUATION
193           Print debug information about evaluation phase.
194
195       NFT_DEBUG_NETLINK
196           Print netlink debug output.
197
198       NFT_DEBUG_MNL
199           Print libmnl debug output.
200
201       NFT_DEBUG_PROTO_CTX
202           Print protocol context debug output.
203
204       NFT_DEBUG_SEGTREE
205           Print segtree (i.e. interval sets) debug output.
206
207       The nft_ctx_output_get_debug() function returns the debug output
208       setting’s value in ctx.
209
210       The nft_ctx_output_set_debug() function sets the debug output setting
211       in ctx to the value of mask.
212
213   Controlling library standard and error output
214       By default, any output from the library (e.g., after a list command) is
215       written to stdout and any error messages are written to stderr. To give
216       applications control over them, there are functions to assign custom
217       file pointers as well as having the library buffer what would be
218       written for later retrieval in a static buffer. This buffer is
219       guaranteed to be null-terminated and must not be freed. Note that the
220       retrieval functions rewind the buffer position indicator. Further
221       library output will probably overwrite the buffer content and
222       potentially render it invalid (due to reallocation).
223
224       The nft_ctx_set_output() and nft_ctx_set_error() functions set the
225       output or error file pointer in ctx to the value of fp. They return the
226       previous value to aid in temporary file pointer overrides. On error,
227       these functions return NULL. This happens only if fp is NULL or invalid
228       (tested using ferror() function).
229
230       The nft_ctx_buffer_output() and nft_ctx_buffer_error() functions enable
231       library standard or error output buffering. The functions return zero
232       on success, non-zero otherwise. This may happen if the internal call to
233       fopencookie() failed.
234
235       The nft_ctx_unbuffer_output() and nft_ctx_unbuffer_error() functions
236       disable library standard or error output buffering. On failure, the
237       functions return non-zero which may only happen if buffering was not
238       enabled at the time the function was called.
239
240       The nft_ctx_get_output_buffer() and nft_ctx_get_error_buffer()
241       functions return a pointer to the buffered output (which may be empty).
242
243   nft_ctx_add_include_path() and nft_ctx_clear_include_path()
244       The include command in nftables rulesets allows to outsource parts of
245       the ruleset into a different file. The include path defines where these
246       files are searched for. Libnftables allows to have a list of those
247       paths which are searched in order. The default include path list
248       contains a single compile-time defined entry (typically /etc/).
249
250       The nft_ctx_add_include_path() function extends the list of include
251       paths in ctx by the one given in path. The function returns zero on
252       success or non-zero if memory allocation failed.
253
254       The nft_ctx_clear_include_paths() function removes all include paths,
255       even the built-in default one.
256
257   nft_run_cmd_from_buffer() and nft_run_cmd_from_filename()
258       These functions perform the actual work of parsing user input into
259       nftables commands and executing them.
260
261       The nft_run_cmd_from_buffer() function passes the command(s) contained
262       in buf (which must be null-terminated) to the library, respecting
263       settings and state in nft.
264
265       The nft_run_cmd_from_filename() function passes the content of filename
266       to the library, respecting settings and state in nft.
267
268       Both functions return zero on success. A non-zero return code indicates
269       an error while parsing or executing the command. This event should be
270       accompanied by an error message written to library error output.
271

EXAMPLE

273           #include <stdio.h>
274           #include <string.h>
275           #include <nftables/libnftables.h>
276
277           int main(void)
278           {
279                   char *list_cmd = "list ruleset";
280                   struct nft_ctx *nft;
281                   const char *output, *p;
282                   char buf[256];
283                   int rc = 0;
284
285                   nft = nft_ctx_new(NFT_CTX_DEFAULT);
286                   if (!nft)
287                           return 1;
288
289                   while (1) {
290                           if (nft_ctx_buffer_output(nft) ||
291                               nft_run_cmd_from_buffer(nft, list_cmd)) {
292                                   rc = 1;
293                                   break;
294                           }
295                           output = nft_ctx_get_output_buffer(nft);
296                           if (strlen(output)) {
297                                   printf("\nThis is the current ruleset:\n| ");
298                                   for (p = output; *(p + 1); p++) {
299                                           if (*p == '\n')
300                                                   printf("\n| ");
301                                           else
302                                                   putchar(*p);
303                                   }
304                                   putchar('\n');
305                           } else {
306                                   printf("\nCurrent ruleset is empty.\n");
307                           }
308                           nft_ctx_unbuffer_output(nft);
309
310                           printf("\nEnter command ('q' to quit): ");
311                           fflush(stdout);
312                           fgets(buf, 256, stdin);
313                           if (strlen(buf))
314                                   buf[strlen(buf) - 1] = '\0';
315
316                           if (buf[0] == 'q' && buf[1] == '\0')
317                                   break;
318
319                           if (nft_run_cmd_from_buffer(nft, buf)) {
320                                   rc = 1;
321                                   break;
322                           }
323                   }
324
325                   nft_ctx_free(nft);
326                   return rc;
327           }
328

SEE ALSO

330       libnftables-json(5), nft(8)
331

AUTHOR

333       Phil Sutter <phil@nwl.cc>
334           Author.
335
336
337
338                                  08/09/2022                    LIBNFTABLES(3)
Impressum