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_SYMBOL |
103 NFT_CTX_OUTPUT_NUMERIC_TIME),
104 NFT_CTX_OUTPUT_TERSE = (1 << 11),
105 };
106 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 NFT_CTX_OUTPUT_SERVICE
113 Print port numbers as services as described in the /etc/services
114 file.
115 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 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 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 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 NFT_CTX_OUTPUT_GUID
143 Display UID and GID as described in the /etc/passwd and /etc/group
144 files.
145 NFT_CTX_OUTPUT_NUMERIC_PROTO
147 Display layer 4 protocol numerically.
148 NFT_CTX_OUTPUT_NUMERIC_PRIO
150 Display base chain priority numerically.
151 NFT_CTX_OUTPUT_NUMERIC_SYMBOL
153 Display expression datatype as numeric value.
154 NFT_CTX_OUTPUT_NUMERIC_TIME
156 Display time, day and hour values in numeric format.
157 NFT_CTX_OUTPUT_NUMERIC_ALL
159 Display all numerically.
160 NFT_CTX_OUTPUT_TERSE
162 If terse output has been requested, then the contents of sets are
163 not printed.
164 The nft_ctx_output_get_flags() function returns the output flags
166 setting’s value in ctx.
167 The nft_ctx_output_set_flags() function sets the output flags setting
169 in ctx to the value of val.
170 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 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 NFT_DEBUG_SCANNER
187 Print LEX debug output.
188 NFT_DEBUG_PARSER
190 Print YACC debug output.
191 NFT_DEBUG_EVALUATION
193 Print debug information about evaluation phase.
194 NFT_DEBUG_NETLINK
196 Print netlink debug output.
197 NFT_DEBUG_MNL
199 Print libmnl debug output.
200 NFT_DEBUG_PROTO_CTX
202 Print protocol context debug output.
203 NFT_DEBUG_SEGTREE
205 Print segtree (i.e. interval sets) debug output.
206 The nft_ctx_output_get_debug() function returns the debug output
208 setting’s value in ctx.
209 The nft_ctx_output_set_debug() function sets the debug output setting
211 in ctx to the value of mask.
212 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 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 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 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 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 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 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 The nft_ctx_clear_include_paths() function removes all include paths,
255 even the built-in default one.
256 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 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 The nft_run_cmd_from_filename() function passes the content of filename
266 to the library, respecting settings and state in nft.
267 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
273 #include <stdio.h>
274 #include <string.h>
275 #include <nftables/libnftables.h>
276 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 nft = nft_ctx_new(NFT_CTX_DEFAULT);
286 if (!nft)
287 return 1;
288 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 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 if (buf[0] == 'q' && buf[1] == '\0')
317 break;
318 if (nft_run_cmd_from_buffer(nft, buf)) {
320 rc = 1;
321 break;
322 }
323 }
324 nft_ctx_free(nft);
326 return rc;
327 }
328
330 libnftables-json(5), nft(8)
331
333 Phil Sutter <phil@nwl.cc>
334 Author.
335 11/18/2021 LIBNFTABLES(3)