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_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 Link with -lnftables.
41
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 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 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 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 The nft_ctx_free() function frees the context object pointed to by ctx,
71 including any caches or buffers it may hold.
72 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 The nft_ctx_get_dry_run() function returns the dry-run setting’s value
80 contained in ctx.
81 The nft_ctx_set_dry_run() function sets the dry-run setting in ctx to
83 the value of dry.
84 nft_ctx_output_get_flags() and nft_ctx_output_set_flags()
86 The flags setting controls the output format.
87 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 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 NFT_CTX_OUTPUT_SERVICE
112 Print port numbers as services as described in the /etc/services
113 file.
114 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 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 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 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 NFT_CTX_OUTPUT_GUID
142 Display UID and GID as described in the /etc/passwd and /etc/group
143 files.
144 NFT_CTX_OUTPUT_NUMERIC_PROTO
146 Display layer 4 protocol numerically.
147 NFT_CTX_OUTPUT_NUMERIC_PRIO
149 Display base chain priority numerically.
150 NFT_CTX_OUTPUT_NUMERIC_SYMBOL
152 Display expression datatype as numeric value.
153 NFT_CTX_OUTPUT_NUMERIC_TIME
155 Display time, day and hour values in numeric format.
156 NFT_CTX_OUTPUT_NUMERIC_ALL
158 Display all numerically.
159 NFT_CTX_OUTPUT_TERSE
161 If terse output has been requested, then the contents of sets are
162 not printed.
163 The nft_ctx_output_get_flags() function returns the output flags
165 setting’s value in ctx.
166 The nft_ctx_output_set_flags() function sets the output flags setting
168 in ctx to the value of val.
169 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 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 NFT_DEBUG_SCANNER
186 Print LEX debug output.
187 NFT_DEBUG_PARSER
189 Print YACC debug output.
190 NFT_DEBUG_EVALUATION
192 Print debug information about evaluation phase.
193 NFT_DEBUG_NETLINK
195 Print netlink debug output.
196 NFT_DEBUG_MNL
198 Print libmnl debug output.
199 NFT_DEBUG_PROTO_CTX
201 Print protocol context debug output.
202 NFT_DEBUG_SEGTREE
204 Print segtree (i.e. interval sets) debug output.
205 The nft_ctx_output_get_debug() function returns the debug output
207 setting’s value in ctx.
208 The nft_ctx_output_set_debug() function sets the debug output setting
210 in ctx to the value of mask.
211 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 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 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 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 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 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 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 The nft_ctx_clear_include_paths() function removes all include paths,
254 even the built-in default one.
255 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 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 The nft_run_cmd_from_filename() function passes the content of filename
265 to the library, respecting settings and state in nft.
266 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
272 #include <stdio.h>
273 #include <string.h>
274 #include <nftables/libnftables.h>
275 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 nft = nft_ctx_new(NFT_CTX_DEFAULT);
285 if (!nft)
286 return 1;
287 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 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 if (buf[0] == 'q' && buf[1] == '\0')
316 break;
317 if (nft_run_cmd_from_buffer(nft, buf)) {
319 rc = 1;
320 break;
321 }
322 }
323 nft_ctx_free(nft);
325 return rc;
326 }
327
329 libnftables-json(5), nft(8)
330
332 Phil Sutter <phil@nwl.cc>
333 Author.
334 08/19/2021 LIBNFTABLES(3)