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 };
100 NFT_CTX_OUTPUT_REVERSEDNS
102 Reverse DNS lookups are performed for IP addresses when printing.
103 Note that this may add significant delay to list commands depending
104 on DNS resolver speed.
105 NFT_CTX_OUTPUT_SERVICE
107 Print port numbers as services as described in the /etc/services
108 file.
109 NFT_CTX_OUTPUT_STATELESS
111 If stateless output has been requested, then stateful data is not
112 printed. Stateful data refers to those objects that carry run-time
113 data, e.g. the counter statement holds packet and byte counter
114 values, making it stateful.
115 NFT_CTX_OUTPUT_HANDLE
117 Upon insertion into the ruleset, some elements are assigned a
118 unique handle for identification purposes. For example, when
119 deleting a table or chain, it may be identified either by name or
120 handle. Rules on the other hand must be deleted by handle, because
121 there is no other way to uniquely identify them. This flag makes
122 ruleset listings include handle values.
123 NFT_CTX_OUTPUT_JSON
125 If enabled at compile-time, libnftables accepts input in JSON
126 format and is able to print output in JSON format as well. See
127 libnftables-json(5) for a description of the supported schema. This
128 flag controls JSON output format, input is auto-detected.
129 NFT_CTX_OUTPUT_ECHO
131 The echo setting makes libnftables print the changes once they are
132 committed to the kernel, just like a running instance of nft
133 monitor would. Amongst other things, this allows to retrieve an
134 added rule’s handle atomically.
135 NFT_CTX_OUTPUT_GUID
137 Display UID and GID as described in the /etc/passwd and /etc/group
138 files.
139 NFT_CTX_OUTPUT_NUMERIC_PROTO
141 Display layer 4 protocol numerically.
142 NFT_CTX_OUTPUT_NUMERIC_PRIO
144 Display base chain priority numerically.
145 NFT_CTX_OUTPUT_NUMERIC_SYMBOL
147 Display expression datatype as numeric value.
148 NFT_CTX_OUTPUT_NUMERIC_ALL
150 Display all numerically.
151 The nft_ctx_output_get_flags() function returns the output flags
153 setting’s value in ctx.
154 The nft_ctx_output_set_flags() function sets the output flags setting
156 in ctx to the value of val.
157 nft_ctx_output_get_debug() and nft_ctx_output_set_debug()
159 Libnftables supports separate debugging of different parts of its
160 internals. To facilitate this, debugging output is controlled via a bit
161 mask. The bits are defined as such:
162 enum nft_debug_level {
164 NFT_DEBUG_SCANNER = 0x1,
165 NFT_DEBUG_PARSER = 0x2,
166 NFT_DEBUG_EVALUATION = 0x4,
167 NFT_DEBUG_NETLINK = 0x8,
168 NFT_DEBUG_MNL = 0x10,
169 NFT_DEBUG_PROTO_CTX = 0x20,
170 NFT_DEBUG_SEGTREE = 0x40,
171 };
172 NFT_DEBUG_SCANNER
174 Print LEX debug output.
175 NFT_DEBUG_PARSER
177 Print YACC debug output.
178 NFT_DEBUG_EVALUATION
180 Print debug information about evaluation phase.
181 NFT_DEBUG_NETLINK
183 Print netlink debug output.
184 NFT_DEBUG_MNL
186 Print libmnl debug output.
187 NFT_DEBUG_PROTO_CTX
189 Print protocol context debug output.
190 NFT_DEBUG_SEGTREE
192 Print segtree (i.e. interval sets) debug output.
193 The nft_ctx_output_get_debug() function returns the debug output
195 setting’s value in ctx.
196 The nft_ctx_output_set_debug() function sets the debug output setting
198 in ctx to the value of mask.
199 Controlling library standard and error output
201 By default, any output from the library (e.g., after a list command) is
202 written to stdout and any error messages are written to stderr. To give
203 applications control over them, there are functions to assign custom
204 file pointers as well as having the library buffer what would be
205 written for later retrieval in a static buffer. This buffer is
206 guaranteed to be null-terminated and must not be freed. Note that the
207 retrieval functions rewind the buffer position indicator. Further
208 library output will probably overwrite the buffer content and
209 potentially render it invalid (due to reallocation).
210 The nft_ctx_set_output() and nft_ctx_set_error() functions set the
212 output or error file pointer in ctx to the value of fp. They return the
213 previous value to aid in temporary file pointer overrides. On error,
214 these functions return NULL. This happens only if fp is NULL or invalid
215 (tested using ferror() function).
216 The nft_ctx_buffer_output() and nft_ctx_buffer_error() functions enable
218 library standard or error output buffering. The functions return zero
219 on success, non-zero otherwise. This may happen if the internal call to
220 fopencookie() failed.
221 The nft_ctx_unbuffer_output() and nft_ctx_unbuffer_error() functions
223 disable library standard or error output buffering. On failure, the
224 functions return non-zero which may only happen if buffering was not
225 enabled at the time the function was called.
226 The nft_ctx_get_output_buffer() and nft_ctx_get_error_buffer()
228 functions return a pointer to the buffered output (which may be empty).
229 nft_ctx_add_include_path() and nft_ctx_clear_include_path()
231 The include command in nftables rulesets allows to outsource parts of
232 the ruleset into a different file. The include path defines where these
233 files are searched for. Libnftables allows to have a list of those
234 paths which are searched in order. The default include path list
235 contains a single compile-time defined entry (typically /etc/).
236 The nft_ctx_add_include_path() function extends the list of include
238 paths in ctx by the one given in path. The function returns zero on
239 success or non-zero if memory allocation failed.
240 The nft_ctx_clear_include_paths() function removes all include paths,
242 even the built-in default one.
243 nft_run_cmd_from_buffer() and nft_run_cmd_from_filename()
245 These functions perform the actual work of parsing user input into
246 nftables commands and executing them.
247 The nft_run_cmd_from_buffer() function passes the command(s) contained
249 in buf (which must be null-terminated) to the library, respecting
250 settings and state in nft.
251 The nft_run_cmd_from_filename() function passes the content of filename
253 to the library, respecting settings and state in nft.
254 Both functions return zero on success. A non-zero return code indicates
256 an error while parsing or executing the command. This event should be
257 accompanied by an error message written to library error output.
258
260 #include <stdio.h>
261 #include <string.h>
262 #include <nftables/libnftables.h>
263 int main(void)
265 {
266 char *list_cmd = "list ruleset";
267 struct nft_ctx *nft;
268 const char *output, *p;
269 char buf[256];
270 int rc = 0;
271 nft = nft_ctx_new(NFT_CTX_DEFAULT);
273 if (!nft)
274 return 1;
275 while (1) {
277 if (nft_ctx_buffer_output(nft) ||
278 nft_run_cmd_from_buffer(nft, list_cmd)) {
279 rc = 1;
280 break;
281 }
282 output = nft_ctx_get_output_buffer(nft);
283 if (strlen(output)) {
284 printf("\nThis is the current ruleset:\n| ");
285 for (p = output; *(p + 1); p++) {
286 if (*p == '\n')
287 printf("\n| ");
288 else
289 putchar(*p);
290 }
291 putchar('\n');
292 } else {
293 printf("\nCurrent ruleset is empty.\n");
294 }
295 nft_ctx_unbuffer_output(nft);
296 printf("\nEnter command ('q' to quit): ");
298 fflush(stdout);
299 fgets(buf, 256, stdin);
300 if (strlen(buf))
301 buf[strlen(buf) - 1] = '\0';
302 if (buf[0] == 'q' && buf[1] == '\0')
304 break;
305 if (nft_run_cmd_from_buffer(nft, buf)) {
307 rc = 1;
308 break;
309 }
310 }
311 nft_ctx_free(nft);
313 return rc;
314 }
315
317 libnftables-json(5), nft(8)
318
320 Phil Sutter <phil@nwl.cc>
321 Author.
322 07/25/2019 LIBNFTABLES(3)