1LIBNFTABLES(3) LIBNFTABLES(3)
2
6 libnftables - nftables frontend library
7
9 #include <nftables/libnftables.h>
10 struct nft_ctx *nft_ctx_new(uint32_t flags);
12 void nft_ctx_free(struct nft_ctx *ctx);
13 bool nft_ctx_get_dry_run(struct nft_ctx *ctx);
15 void nft_ctx_set_dry_run(struct nft_ctx *ctx, bool dry);
16 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 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 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 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 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 int nft_ctx_add_var(struct nft_ctx *ctx, const char *var);
37 void nft_ctx_clear_vars(struct nft_ctx \*ctx);
38 int nft_run_cmd_from_buffer(struct nft_ctx* *nft, const char *buf);
40 int nft_run_cmd_from_filename(struct nft_ctx *nft,
41 const char *filename);
42 Link with -lnftables.
44
46 This library was designed with nftables integration into applications
47 in mind. Its API is therefore kept as simple as possible, which
48 somewhat limits its flexibility. Due to support for JSON markup of
49 input and output though, convenience in constructing and parsing of
50 input and output data may be achieved by using a third-party library
51 such as libjansson.
52 At the very basic level, one has to allocate a new object of type
54 struct nft_ctx using nft_ctx_new() function, then pass commands via
55 nft_run_cmd_from_buffer() or nft_run_cmd_from_filename() functions. By
56 default, any output is written to stdout (or stderr for error
57 messages). These file pointers may be changed using
58 nft_ctx_set_output() and nft_ctx_set_error() functions. On top of that,
59 it is possible to have any output buffered by the library for later
60 retrieval as a static buffer. See nft_ctx_buffer_output() and
61 nft_ctx_buffer_error() functions for details.
62 nft_ctx_new() and nft_ctx_free()
64 These functions aid in nft context management. In order to make use of
65 the library, at least one context object has to be allocated. The
66 context holds temporary data such as caches, library configuration and
67 (if enabled) output and error buffers.
68 The nft_ctx_new() function allocates and returns a new context object.
70 The parameter flags is unused at this point and should be set to zero.
71 For convenience, the macro NFT_CTX_DEFAULT is defined to that value.
72 The nft_ctx_free() function frees the context object pointed to by ctx,
74 including any caches or buffers it may hold.
75 nft_ctx_get_dry_run() and nft_ctx_set_dry_run()
77 Dry-run setting controls whether ruleset changes are actually committed
78 on kernel side or not. It allows one to check whether a given operation
79 would succeed without making actual changes to the ruleset. The default
80 setting is false.
81 The nft_ctx_get_dry_run() function returns the dry-run setting’s value
83 contained in ctx.
84 The nft_ctx_set_dry_run() function sets the dry-run setting in ctx to
86 the value of dry.
87 nft_ctx_output_get_flags() and nft_ctx_output_set_flags()
89 The flags setting controls the output format.
90 enum {
92 NFT_CTX_OUTPUT_REVERSEDNS = (1 << 0),
93 NFT_CTX_OUTPUT_SERVICE = (1 << 1),
94 NFT_CTX_OUTPUT_STATELESS = (1 << 2),
95 NFT_CTX_OUTPUT_HANDLE = (1 << 3),
96 NFT_CTX_OUTPUT_JSON = (1 << 4),
97 NFT_CTX_OUTPUT_ECHO = (1 << 5),
98 NFT_CTX_OUTPUT_GUID = (1 << 6),
99 NFT_CTX_OUTPUT_NUMERIC_PROTO = (1 << 7),
100 NFT_CTX_OUTPUT_NUMERIC_PRIO = (1 << 8),
101 NFT_CTX_OUTPUT_NUMERIC_SYMBOL = (1 << 9),
102 NFT_CTX_OUTPUT_NUMERIC_TIME = (1 << 10),
103 NFT_CTX_OUTPUT_NUMERIC_ALL = (NFT_CTX_OUTPUT_NUMERIC_PROTO |
104 NFT_CTX_OUTPUT_NUMERIC_PRIO |
105 NFT_CTX_OUTPUT_NUMERIC_SYMBOL |
106 NFT_CTX_OUTPUT_NUMERIC_TIME),
107 NFT_CTX_OUTPUT_TERSE = (1 << 11),
108 };
109 NFT_CTX_OUTPUT_REVERSEDNS
111 Reverse DNS lookups are performed for IP addresses when printing.
112 Note that this may add significant delay to list commands depending
113 on DNS resolver speed.
114 NFT_CTX_OUTPUT_SERVICE
116 Print port numbers as services as described in the /etc/services
117 file.
118 NFT_CTX_OUTPUT_STATELESS
120 If stateless output has been requested, then stateful data is not
121 printed. Stateful data refers to those objects that carry run-time
122 data, e.g. the counter statement holds packet and byte counter
123 values, making it stateful.
124 NFT_CTX_OUTPUT_HANDLE
126 Upon insertion into the ruleset, some elements are assigned a
127 unique handle for identification purposes. For example, when
128 deleting a table or chain, it may be identified either by name or
129 handle. Rules on the other hand must be deleted by handle, because
130 there is no other way to uniquely identify them. This flag makes
131 ruleset listings include handle values.
132 NFT_CTX_OUTPUT_JSON
134 If enabled at compile-time, libnftables accepts input in JSON
135 format and is able to print output in JSON format as well. See
136 libnftables-json(5) for a description of the supported schema. This
137 flag controls JSON output format, input is auto-detected.
138 NFT_CTX_OUTPUT_ECHO
140 The echo setting makes libnftables print the changes once they are
141 committed to the kernel, just like a running instance of nft
142 monitor would. Amongst other things, this allows one to retrieve an
143 added rule’s handle atomically.
144 NFT_CTX_OUTPUT_GUID
146 Display UID and GID as described in the /etc/passwd and /etc/group
147 files.
148 NFT_CTX_OUTPUT_NUMERIC_PROTO
150 Display layer 4 protocol numerically.
151 NFT_CTX_OUTPUT_NUMERIC_PRIO
153 Display base chain priority numerically.
154 NFT_CTX_OUTPUT_NUMERIC_SYMBOL
156 Display expression datatype as numeric value.
157 NFT_CTX_OUTPUT_NUMERIC_TIME
159 Display time, day and hour values in numeric format.
160 NFT_CTX_OUTPUT_NUMERIC_ALL
162 Display all numerically.
163 NFT_CTX_OUTPUT_TERSE
165 If terse output has been requested, then the contents of sets are
166 not printed.
167 The nft_ctx_output_get_flags() function returns the output flags
169 setting’s value in ctx.
170 The nft_ctx_output_set_flags() function sets the output flags setting
172 in ctx to the value of val.
173 nft_ctx_output_get_debug() and nft_ctx_output_set_debug()
175 Libnftables supports separate debugging of different parts of its
176 internals. To facilitate this, debugging output is controlled via a bit
177 mask. The bits are defined as such:
178 enum nft_debug_level {
180 NFT_DEBUG_SCANNER = 0x1,
181 NFT_DEBUG_PARSER = 0x2,
182 NFT_DEBUG_EVALUATION = 0x4,
183 NFT_DEBUG_NETLINK = 0x8,
184 NFT_DEBUG_MNL = 0x10,
185 NFT_DEBUG_PROTO_CTX = 0x20,
186 NFT_DEBUG_SEGTREE = 0x40,
187 };
188 NFT_DEBUG_SCANNER
190 Print LEX debug output.
191 NFT_DEBUG_PARSER
193 Print YACC debug output.
194 NFT_DEBUG_EVALUATION
196 Print debug information about evaluation phase.
197 NFT_DEBUG_NETLINK
199 Print netlink debug output.
200 NFT_DEBUG_MNL
202 Print libmnl debug output.
203 NFT_DEBUG_PROTO_CTX
205 Print protocol context debug output.
206 NFT_DEBUG_SEGTREE
208 Print segtree (i.e. interval sets) debug output.
209 The nft_ctx_output_get_debug() function returns the debug output
211 setting’s value in ctx.
212 The nft_ctx_output_set_debug() function sets the debug output setting
214 in ctx to the value of mask.
215 Controlling library standard and error output
217 By default, any output from the library (e.g., after a list command) is
218 written to stdout and any error messages are written to stderr. To give
219 applications control over them, there are functions to assign custom
220 file pointers as well as having the library buffer what would be
221 written for later retrieval in a static buffer. This buffer is
222 guaranteed to be null-terminated and must not be freed. Note that the
223 retrieval functions rewind the buffer position indicator. Further
224 library output will probably overwrite the buffer content and
225 potentially render it invalid (due to reallocation).
226 The nft_ctx_set_output() and nft_ctx_set_error() functions set the
228 output or error file pointer in ctx to the value of fp. They return the
229 previous value to aid in temporary file pointer overrides. On error,
230 these functions return NULL. This happens only if fp is NULL or invalid
231 (tested using ferror() function).
232 The nft_ctx_buffer_output() and nft_ctx_buffer_error() functions enable
234 library standard or error output buffering. The functions return zero
235 on success, non-zero otherwise. This may happen if the internal call to
236 fopencookie() failed.
237 The nft_ctx_unbuffer_output() and nft_ctx_unbuffer_error() functions
239 disable library standard or error output buffering. On failure, the
240 functions return non-zero which may only happen if buffering was not
241 enabled at the time the function was called.
242 The nft_ctx_get_output_buffer() and nft_ctx_get_error_buffer()
244 functions return a pointer to the buffered output (which may be empty).
245 nft_ctx_add_include_path() and nft_ctx_clear_include_path()
247 The include command in nftables rulesets allows one to outsource parts
248 of the ruleset into a different file. The include path defines where
249 these files are searched for. Libnftables allows one to have a list of
250 those paths which are searched in order. The default include path list
251 contains a single compile-time defined entry (typically /etc/).
252 The nft_ctx_add_include_path() function extends the list of include
254 paths in ctx by the one given in path. The function returns zero on
255 success or non-zero if memory allocation failed.
256 The nft_ctx_clear_include_paths() function removes all include paths,
258 even the built-in default one.
259 nft_ctx_add_var() and nft_ctx_clear_vars()
261 The define command in nftables ruleset allows one to define variables.
262 The nft_ctx_add_var() function extends the list of variables in ctx.
264 The variable must be given in the format key=value. The function
265 returns zero on success or non-zero if the variable is malformed.
266 The nft_ctx_clear_vars() function removes all variables.
268 nft_run_cmd_from_buffer() and nft_run_cmd_from_filename()
270 These functions perform the actual work of parsing user input into
271 nftables commands and executing them.
272 The nft_run_cmd_from_buffer() function passes the command(s) contained
274 in buf (which must be null-terminated) to the library, respecting
275 settings and state in nft.
276 The nft_run_cmd_from_filename() function passes the content of filename
278 to the library, respecting settings and state in nft.
279 Both functions return zero on success. A non-zero return code indicates
281 an error while parsing or executing the command. This event should be
282 accompanied by an error message written to library error output.
283
285 #include <stdio.h>
286 #include <string.h>
287 #include <nftables/libnftables.h>
288 int main(void)
290 {
291 char *list_cmd = "list ruleset";
292 struct nft_ctx *nft;
293 const char *output, *p;
294 char buf[256];
295 int rc = 0;
296 nft = nft_ctx_new(NFT_CTX_DEFAULT);
298 if (!nft)
299 return 1;
300 while (1) {
302 if (nft_ctx_buffer_output(nft) ||
303 nft_run_cmd_from_buffer(nft, list_cmd)) {
304 rc = 1;
305 break;
306 }
307 output = nft_ctx_get_output_buffer(nft);
308 if (strlen(output)) {
309 printf("\nThis is the current ruleset:\n| ");
310 for (p = output; *(p + 1); p++) {
311 if (*p == '\n')
312 printf("\n| ");
313 else
314 putchar(*p);
315 }
316 putchar('\n');
317 } else {
318 printf("\nCurrent ruleset is empty.\n");
319 }
320 nft_ctx_unbuffer_output(nft);
321 printf("\nEnter command ('q' to quit): ");
323 fflush(stdout);
324 fgets(buf, 256, stdin);
325 if (strlen(buf))
326 buf[strlen(buf) - 1] = '\0';
327 if (buf[0] == 'q' && buf[1] == '\0')
329 break;
330 if (nft_run_cmd_from_buffer(nft, buf)) {
332 rc = 1;
333 break;
334 }
335 }
336 nft_ctx_free(nft);
338 return rc;
339 }
340
342 libnftables-json(5), nft(8)
343
345 Phil Sutter <phil@nwl.cc>
346 Author.
347 03/13/2023 LIBNFTABLES(3)