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_TIME),
103                   NFT_CTX_OUTPUT_TERSE          = (1 << 11),
104           };
105
106       NFT_CTX_OUTPUT_REVERSEDNS
107           Reverse DNS lookups are performed for IP addresses when printing.
108           Note that this may add significant delay to list commands depending
109           on DNS resolver speed.
110
111       NFT_CTX_OUTPUT_SERVICE
112           Print port numbers as services as described in the /etc/services
113           file.
114
115       NFT_CTX_OUTPUT_STATELESS
116           If stateless output has been requested, then stateful data is not
117           printed. Stateful data refers to those objects that carry run-time
118           data, e.g. the counter statement holds packet and byte counter
119           values, making it stateful.
120
121       NFT_CTX_OUTPUT_HANDLE
122           Upon insertion into the ruleset, some elements are assigned a
123           unique handle for identification purposes. For example, when
124           deleting a table or chain, it may be identified either by name or
125           handle. Rules on the other hand must be deleted by handle, because
126           there is no other way to uniquely identify them. This flag makes
127           ruleset listings include handle values.
128
129       NFT_CTX_OUTPUT_JSON
130           If enabled at compile-time, libnftables accepts input in JSON
131           format and is able to print output in JSON format as well. See
132           libnftables-json(5) for a description of the supported schema. This
133           flag controls JSON output format, input is auto-detected.
134
135       NFT_CTX_OUTPUT_ECHO
136           The echo setting makes libnftables print the changes once they are
137           committed to the kernel, just like a running instance of nft
138           monitor would. Amongst other things, this allows to retrieve an
139           added rule’s handle atomically.
140
141       NFT_CTX_OUTPUT_GUID
142           Display UID and GID as described in the /etc/passwd and /etc/group
143           files.
144
145       NFT_CTX_OUTPUT_NUMERIC_PROTO
146           Display layer 4 protocol numerically.
147
148       NFT_CTX_OUTPUT_NUMERIC_PRIO
149           Display base chain priority numerically.
150
151       NFT_CTX_OUTPUT_NUMERIC_SYMBOL
152           Display expression datatype as numeric value.
153
154       NFT_CTX_OUTPUT_NUMERIC_TIME
155           Display time, day and hour values in numeric format.
156
157       NFT_CTX_OUTPUT_NUMERIC_ALL
158           Display all numerically.
159
160       NFT_CTX_OUTPUT_TERSE
161           If terse output has been requested, then the contents of sets are
162           not printed.
163
164       The nft_ctx_output_get_flags() function returns the output flags
165       setting’s value in ctx.
166
167       The nft_ctx_output_set_flags() function sets the output flags setting
168       in ctx to the value of val.
169
170   nft_ctx_output_get_debug() and nft_ctx_output_set_debug()
171       Libnftables supports separate debugging of different parts of its
172       internals. To facilitate this, debugging output is controlled via a bit
173       mask. The bits are defined as such:
174
175           enum nft_debug_level {
176                   NFT_DEBUG_SCANNER               = 0x1,
177                   NFT_DEBUG_PARSER                = 0x2,
178                   NFT_DEBUG_EVALUATION            = 0x4,
179                   NFT_DEBUG_NETLINK               = 0x8,
180                   NFT_DEBUG_MNL                   = 0x10,
181                   NFT_DEBUG_PROTO_CTX             = 0x20,
182                   NFT_DEBUG_SEGTREE               = 0x40,
183           };
184
185       NFT_DEBUG_SCANNER
186           Print LEX debug output.
187
188       NFT_DEBUG_PARSER
189           Print YACC debug output.
190
191       NFT_DEBUG_EVALUATION
192           Print debug information about evaluation phase.
193
194       NFT_DEBUG_NETLINK
195           Print netlink debug output.
196
197       NFT_DEBUG_MNL
198           Print libmnl debug output.
199
200       NFT_DEBUG_PROTO_CTX
201           Print protocol context debug output.
202
203       NFT_DEBUG_SEGTREE
204           Print segtree (i.e. interval sets) debug output.
205
206       The nft_ctx_output_get_debug() function returns the debug output
207       setting’s value in ctx.
208
209       The nft_ctx_output_set_debug() function sets the debug output setting
210       in ctx to the value of mask.
211
212   Controlling library standard and error output
213       By default, any output from the library (e.g., after a list command) is
214       written to stdout and any error messages are written to stderr. To give
215       applications control over them, there are functions to assign custom
216       file pointers as well as having the library buffer what would be
217       written for later retrieval in a static buffer. This buffer is
218       guaranteed to be null-terminated and must not be freed. Note that the
219       retrieval functions rewind the buffer position indicator. Further
220       library output will probably overwrite the buffer content and
221       potentially render it invalid (due to reallocation).
222
223       The nft_ctx_set_output() and nft_ctx_set_error() functions set the
224       output or error file pointer in ctx to the value of fp. They return the
225       previous value to aid in temporary file pointer overrides. On error,
226       these functions return NULL. This happens only if fp is NULL or invalid
227       (tested using ferror() function).
228
229       The nft_ctx_buffer_output() and nft_ctx_buffer_error() functions enable
230       library standard or error output buffering. The functions return zero
231       on success, non-zero otherwise. This may happen if the internal call to
232       fopencookie() failed.
233
234       The nft_ctx_unbuffer_output() and nft_ctx_unbuffer_error() functions
235       disable library standard or error output buffering. On failure, the
236       functions return non-zero which may only happen if buffering was not
237       enabled at the time the function was called.
238
239       The nft_ctx_get_output_buffer() and nft_ctx_get_error_buffer()
240       functions return a pointer to the buffered output (which may be empty).
241
242   nft_ctx_add_include_path() and nft_ctx_clear_include_path()
243       The include command in nftables rulesets allows to outsource parts of
244       the ruleset into a different file. The include path defines where these
245       files are searched for. Libnftables allows to have a list of those
246       paths which are searched in order. The default include path list
247       contains a single compile-time defined entry (typically /etc/).
248
249       The nft_ctx_add_include_path() function extends the list of include
250       paths in ctx by the one given in path. The function returns zero on
251       success or non-zero if memory allocation failed.
252
253       The nft_ctx_clear_include_paths() function removes all include paths,
254       even the built-in default one.
255
256   nft_run_cmd_from_buffer() and nft_run_cmd_from_filename()
257       These functions perform the actual work of parsing user input into
258       nftables commands and executing them.
259
260       The nft_run_cmd_from_buffer() function passes the command(s) contained
261       in buf (which must be null-terminated) to the library, respecting
262       settings and state in nft.
263
264       The nft_run_cmd_from_filename() function passes the content of filename
265       to the library, respecting settings and state in nft.
266
267       Both functions return zero on success. A non-zero return code indicates
268       an error while parsing or executing the command. This event should be
269       accompanied by an error message written to library error output.
270

EXAMPLE

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

SEE ALSO

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

AUTHOR

332       Phil Sutter <phil@nwl.cc>
333           Author.
334
335
336
337                                  01/15/2021                    LIBNFTABLES(3)
Impressum