summaryrefslogtreecommitdiffstats
path: root/doc/nft.txt
Commit message (Collapse)AuthorAgeFilesLines
* Add support for table's persist flagHEADmasterPhil Sutter4 days1-0/+9
| | | | | | | | | Bison parser lacked support for passing multiple flags, JSON parser did not support table flags at all. Document also 'owner' flag (and describe their relationship in nft.8. Signed-off-by: Phil Sutter <phil@nwl.cc>
* doc: nft.8: Two minor synopsis fixupsPhil Sutter13 days1-2/+2
| | | | | | | | | | | | The curly braces in 'add table' are to be put literally, so need to be bold. Also, they are optional unless either one (or both) of 'comment' and 'flags' are specified. The 'add chain' synopsis contained a stray tick, messing up the following markup. Fixes: 7fd67ce121f86 ("doc: fix synopsis of named counter, quota and ct {helper,timeout,expect}") Signed-off-by: Phil Sutter <phil@nwl.cc>
* doc: remove references to timeout in reset commandPablo Neira Ayuso2023-10-101-5/+5
| | | | | | | | | | After Linux kernel's patch ("netfilter: nf_tables: do not refresh timeout when resetting element") timers are not reset anymore, update documentation to keep this in sync. Fixes: 83e0f4402fb7 ("Implement 'reset {set,map,element}' commands") Acked-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: document add chain device parameterBrennan Paciorek2023-08-031-0/+5
| | | | | | | | | | | nft add chain lacked documentation of its optional device parameter, specifically what values the parameter accepted, what it did and when to use it. Closes: https://bugzilla.netfilter.org/show_bug.cgi?id=1093 Suggested-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Brennan Paciorek <bpaciore@redhat.com> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* Implement 'reset {set,map,element}' commandsPhil Sutter2023-07-131-5/+8
| | | | | | | | | | | All these are used to reset state in set/map elements, i.e. reset the timeout or zero quota and counter values. While 'reset element' expects a (list of) elements to be specified which should be reset, 'reset set/map' will reset all elements in the given set/map. Signed-off-by: Phil Sutter <phil@nwl.cc>
* doc: list set/map flag keywords in a tableFlorian Westphal2023-05-021-3/+18
| | | | | | add descriptions of the set/map flags. Signed-off-by: Florian Westphal <fw@strlen.de>
* parser_bison: simplify reset syntaxPablo Neira Ayuso2023-03-151-5/+3
| | | | | | | | | | | | | | | | | | | | | | | | | Simplify: *reset rules* *chain* ['family'] 'table' ['chain]' to *reset rules* ['family'] 'table' 'chain' *reset rules* *table* ['family'] 'table' to *reset rules* ['family'] 'table' *reset counters* ['family'] *table* 'table' to *reset counters* ['family'] 'table' *reset quotas* ['family'] *table* 'table' to *reset quotas* ['family'] 'table' Previous syntax remains in place for backward compatibility. Acked-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft.8: Document lower priority limit for nat type chainsPhil Sutter2023-03-101-0/+3
| | | | | | Users can't know the magic limit. Signed-off-by: Phil Sutter <phil@nwl.cc>
* src: add support to command "destroy"Fernando F. Mancera2023-02-061-10/+23
| | | | | | | | | | | | | | | | | | | | | | | | | "destroy" command performs a deletion as "delete" command but does not fail if the object does not exist. As there is no NLM_F_* flag for ignoring such error, it needs to be ignored directly on error handling. Example of use: # nft list ruleset table ip filter { chain output { } } # nft destroy table ip missingtable # echo $? 0 # nft list ruleset table ip filter { chain output { } } Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* Implement 'reset rule' and 'reset rules' commandsPhil Sutter2023-01-181-1/+5
| | | | | | | | Reset rule counters and quotas in kernel, i.e. without having to reload them. Requires respective kernel patch to support NFT_MSG_GETRULE_RESET message type. Signed-off-by: Phil Sutter <phil@nwl.cc>
* doc: no reset support for limitPablo Neira Ayuso2022-11-091-1/+1
| | | | | | | Remove reset command, this not supported for ratelimit. Fixes: eff2d606d20d ("doc: document a few reset commands supported by the parser") Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: document a few reset commands supported by the parserPablo Neira Ayuso2022-11-091-2/+10
| | | | | | | | | | | | | The following are missing in the manpage: *reset counters* ['family'] *reset quotas* ['family'] *reset counters* ['family'] *table* 'table' *reset quotas* ['family'] *table* 'table' While at it, expand type to the supported stateful objects. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc, src: make some spelling and grammatical improvementsJeremy Sowden2022-09-221-3/+3
| | | | | | | | | | | | | Fix a couple of spelling mistakes: 'expresion' -> 'expression' and correct some non-native usages: 'allows to' -> 'allows one to' Signed-off-by: Jeremy Sowden <jeremy@azazel.net> Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: nft.8: Add missing '-T' in synopsisPhil Sutter2022-08-301-1/+1
| | | | | | | | Originally a typo in fixed commit: It added 't' in lower case, but meanwhile '-t' was added as well. Fixes: f8f32deda31df ("meta: Introduce new conditions 'time', 'day' and 'hour'") Signed-off-by: Phil Sutter <phil@nwl.cc>
* doc: add undefine and redefine keywordsPierre Ducroquet2022-02-071-0/+6
| | | | Signed-off-by: Florian Westphal <fw@strlen.de>
* src: add ruleset optimization infrastructurePablo Neira Ayuso2022-01-151-0/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This patch adds a new -o/--optimize option to enable ruleset optimization. You can combine this option with the dry run mode (--check) to review the proposed ruleset updates without actually loading the ruleset, e.g. # nft -c -o -f ruleset.test Merging: ruleset.nft:16:3-37: ip daddr 192.168.0.1 counter accept ruleset.nft:17:3-37: ip daddr 192.168.0.2 counter accept ruleset.nft:18:3-37: ip daddr 192.168.0.3 counter accept into: ip daddr { 192.168.0.1, 192.168.0.2, 192.168.0.3 } counter packets 0 bytes 0 accept This infrastructure collects the common statements that are used in rules, then it builds a matrix of rules vs. statements. Then, it looks for common statements in consecutive rules which allows to merge rules. This ruleset optimization always performs an implicit dry run to validate that the original ruleset is correct. Then, on a second pass, it performs the ruleset optimization and add the rules into the kernel (unless --check has been specified by the user). From libnftables perspective, there is a new API to enable this feature: uint32_t nft_ctx_get_optimize(struct nft_ctx *ctx); void nft_ctx_set_optimize(struct nft_ctx *ctx, uint32_t flags); This patch adds support for the first optimization: Collapse a linear list of rules matching on a single selector into a set as exposed in the example above. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: Support netdev egress hookLukas Wunner2021-10-281-7/+27
| | | | | | | | | Add userspace support for the netdev egress hook which is queued up for v5.16-rc1, complete with documentation and tests. Usage is identical to the ingress hook. Signed-off-by: Lukas Wunner <lukas@wunner.de> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: fix synopsis of named counter, quota and ct {helper,timeout,expect}Pablo Neira Ayuso2021-09-161-4/+4
| | | | | | Synopsis is not complete. Add examples for counters and quotas. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: add --define key=valuePablo Neira Ayuso2021-07-201-0/+4
| | | | | | | | | | | | | | | | | This patch adds a new option to define variables from the command line. # cat test.nft table netdev x { chain y { type filter hook ingress devices = $dev priority 0; counter accept } } # nft --define dev="{ eth0, eth1 }" -f test.nft You can only combine it with -f/--filename. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: add LISTING sectionFlorian Westphal2021-06-091-0/+11
| | | | | | | mention various 'nft list' options, such as secmarks, flow tables, and so on. Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: tiny spelling fix in stateful object section s/an/aFlorian Westphal2021-05-251-1/+1
| | | | | | | | Quoting Duncan Roe: Tiny nit: suggest "by a unique" instead of "by an unique". "a" reads better to this native en-GB speaker at least. Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: nft.8: Extend monitor description by tracePhil Sutter2021-05-191-3/+22
| | | | | | Briefly describe 'nft monitor trace' command functionality. Signed-off-by: Phil Sutter <phil@nwl.cc>
* doc: use symbolic names for chain prioritiesSimon Ruderich2021-03-241-2/+2
| | | | | | | | | | | | | This replaces the numbers with the matching symbolic names with one exception: The NAT example used "priority 0" for the prerouting priority. This is replaced by "dstnat" which has priority -100 which is the new recommended priority. Also use spaces instead of tabs for consistency in lines which require updates. Signed-off-by: Simon Ruderich <simon@ruderich.org> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: add * to include example to actually include filesSimon Ruderich2021-03-091-1/+1
| | | | | | | | "/etc/firewall/rules/" causes no error but also doesn't include any files contained in the directory. Signed-off-by: Simon Ruderich <simon@ruderich.org> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft: fix some typos and formatting issuesŠtěpán Němec2021-02-221-11/+11
| | | | | | | | Trying to escape asciidoc (9.1.0) * with \ preserves the backslash in the formatted man page. Bare * works as expected. Signed-off-by: Štěpán Němec <snemec@redhat.com> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: correct chain name in example of adding a ruleJeremy Sowden2020-11-011-1/+1
| | | | | | | The example adds a rule to the `output` chain, not the `input` chain. Signed-off-by: Jeremy Sowden <jeremy@azazel.net> Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: nft.8: describe inet ingress hookPablo Neira Ayuso2020-10-161-4/+17
| | | | | | Available since Linux kernel >= 5.10. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* nft: rearrange help output to group related options togetherArturo Borrero Gonzalez2020-07-291-38/+56
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | It has been reported that nft options are a bit chaotic. With a growing list of options for the nft CLI, we can do better when presenting them to the user who requests help. This patch introduces a textual output grouping for options, in 4 groups: * Options (general) -- common Unix utility options * Options (operative) -- the options that modify the operative behaviour of nft * Options (translation) -- output text modifiers for data translation * Options (parsing) -- output text modifiers for parsing and other operations There is no behavior change in this patch, is mostly a cosmetic change in the hope that users will find the nft tool a bit less confusing to use. After this patch, the help output is: === 8< === % nft --help Usage: nft [ options ] [ cmds... ] Options (general): -h, help Show this help -v, version Show version information -V Show extended version information Options (ruleset input handling): -f, file <filename> Read input from <filename> -i, interactive Read input from interactive CLI -I, includepath <directory> Add <directory> to the paths searched for include files. Defaul[..] -c, check Check commands validity without actually applying the changes. Options (ruleset list formatting): -a, handle Output rule handle. -s, stateless Omit stateful information of ruleset. -t, terse Omit contents of sets. -S, service Translate ports to service names as described in /etc/services. -N, reversedns Translate IP addresses to names. -u, guid Print UID/GID as defined in /etc/passwd and /etc/group. -n, numeric Print fully numerical output. -y, numeric-priority Print chain priority numerically. -p, numeric-protocol Print layer 4 protocols numerically. -T, numeric-time Print time values numerically. Options (command output format): -e, echo Echo what has been added, inserted or replaced. -j, json Format output in JSON -d, debug <level [,level...]> Specify debugging level (scanner, parser, eval, netlink, mnl, p[..] === 8< === While at it, refresh the man page to better reflex this new grouping, and add some missing options. Joint work with Pablo. Signed-off-by: Arturo Borrero Gonzalez <arturo@netfilter.org> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft.8: Describe element commands in their own sectionPhil Sutter2020-02-071-3/+37
| | | | | | | This unifies the redundant information in sets and maps sections and also covers 'get' command. Signed-off-by: Phil Sutter <phil@nwl.cc>
* doc: mention 'typeof' as alternative to 'type' keywordFlorian Westphal2019-12-171-3/+9
| | | | Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: Drop incorrect requirement for nft configsPhil Sutter2019-11-061-2/+1
| | | | | | The shebang is not needed in files to be used with --file parameter. Signed-off-by: Phil Sutter <phil@nwl.cc>
* src: flowtable: add support for delete command by handleEric Jallot2019-11-061-0/+1
| | | | | | | Also, display handle when listing with '-a'. Signed-off-by: Eric Jallot <ejallot@gmail.com> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: fix missing family in plural forms list command.Eric Jallot2019-10-311-6/+7
| | | | | | Fixes: 067ac215e93f ("doc: update nft list plural form parameters") Signed-off-by: Eric Jallot <ejallot@gmail.com> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: add --terse to suppress output of set elements.Jeremy Sowden2019-10-221-0/+4
| | | | | | | | | | | | Listing an entire ruleset or a table with `nft list` prints the elements of all set definitions within the ruleset or table. Seeing the full set contents is not often necessary especially when requesting to see someone's ruleset for help and support purposes. Add a new option '-t, --terse' options to suppress the output of set contents. Link: https://bugzilla.netfilter.org/show_bug.cgi?id=1374 Signed-off-by: Jeremy Sowden <jeremy@azazel.net> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: use `-T` as the short option for `--numeric-time`.Jeremy Sowden2019-10-221-1/+1
| | | | | | | | | A new `--terse` option will be introduced in a later patch. Change the short option used for `--numeric-time` from `-t` to `-T` in order to leave `-t` free. Signed-off-by: Jeremy Sowden <jeremy@azazel.net> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* expression: extend 'nft describe' to allow listing data typesFlorian Westphal2019-10-141-1/+14
| | | | | | | | | | | | | | | | | nft describe ct_status before: symbol expression, datatype invalid (invalid), 0 bits after: datatype ct_status (conntrack status) (basetype bitmask, integer), 32 bits pre-defined symbolic constants (in hexadecimal): expected 0x00000001 seen-reply 0x00000002 [..] Signed-off-by: Florian Westphal <fw@strlen.de> Acked-by: Pablo Neira Ayuso <pablo@netfilter.org>
* meta: Introduce new conditions 'time', 'day' and 'hour'Ander Juaristi2019-09-061-1/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | These keywords introduce new checks for a timestamp, an absolute date (which is converted to a timestamp), an hour in the day (which is converted to the number of seconds since midnight) and a day of week. When converting an ISO date (eg. 2019-06-06 17:00) to a timestamp, we need to substract it the GMT difference in seconds, that is, the value of the 'tm_gmtoff' field in the tm structure. This is because the kernel doesn't know about time zones. And hence the kernel manages different timestamps than those that are advertised in userspace when running, for instance, date +%s. The same conversion needs to be done when converting hours (e.g 17:00) to seconds since midnight as well. The result needs to be computed modulo 86400 in case GMT offset (difference in seconds from UTC) is negative. We also introduce a new command line option (-t, --seconds) to show the actual timestamps when printing the values, rather than the ISO dates, or the hour. Some usage examples: time < "2019-06-06 17:00" drop; time < "2019-06-06 17:20:20" drop; time < 12341234 drop; day "Saturday" drop; day 6 drop; hour >= 17:00 drop; hour >= "17:00:01" drop; hour >= 63000 drop; We need to convert an ISO date to a timestamp without taking into account the time zone offset, since comparison will be done in kernel space and there is no time zone information there. Overwriting TZ is portable, but will cause problems when parsing a ruleset that has 'time' and 'hour' rules. Parsing an 'hour' type must not do time zone conversion, but that will be automatically done if TZ has been overwritten to UTC. Hence, we use timegm() to parse the 'time' type, even though it's not portable. Overwriting TZ seems to be a much worse solution. Finally, be aware that timestamps are converted to nanoseconds when transferring to the kernel (as comparison is done with nanosecond precision), and back to seconds when retrieving them for printing. We swap left and right values in a range to properly handle cross-day hour ranges (e.g. 23:15-03:22). Signed-off-by: Ander Juaristi <a@juaristi.eus> Reviewed-by: Florian Westphal <fw@strlen.de>
* monitor: Accept -j flagPhil Sutter2019-06-131-7/+2
| | | | | | | | | | | | Make 'nft -j monitor' equal to 'nft monitor json' and change documentation to use only the first variant since that is more intuitive and also consistent with other commands. While being at it, drop references to XML from monitor section - it was never supported. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: Review man page synopsesPhil Sutter2019-05-081-32/+31
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Fix use of font typefaces: - *bold* for terminals - 'italic' for non-terminals - plain for meta-characters Apart from that: * Variable definitions require an equals sign * 'auto-merge' option in set spec does not take a parameter * List header fields in payload expressions instead of unexplained placeholder * Introduce non-terminals in some places to avoid repetitions or clarify syntax * Fix syntax for ip6 header expresssion example * Reorganize ct expression synopsis into four parts: 1) direction not allowed 2) direction optional 3) direction mandatory 4) direction and family mandatory * Add missing 'version' keyword to osf expression * Clarify verdict statements example topic * Add synopses for payload and exthdr statements * Fix typo: differv -> diffserv * Reorganize reject statement synopsis to point out which code type is required for which type arg * Counter statement requires either one of 'packets' or 'bytes' args or both, none is an invalid variant * Limit statement accepts a unit in burst, too * Improve language in limit statement description a bit Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Florian Westphal <fw@strlen.de>
* src: add nat support for the inet familyFlorian Westphal2019-04-091-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | consider a simple ip6 nat table: table ip6 nat { chain output { type nat hook output priority 0; policy accept; dnat to dead:2::99 } Now consider same ruleset, but using 'table inet nat': nft now lacks context to determine address family to parse 'to $address'. This adds code to make the following work: table inet nat { [ .. ] # detect af from network protocol context: ip6 daddr dead::2::1 dnat to dead:2::99 # use new dnat ip6 keyword: dnat ip6 to dead:2::99 } On list side, the keyword is only shown in the inet family, else the short version (dnat to ...) is used as the family is redundant when the table already mandates the ip protocol version supported. Address mismatches such as table ip6 { .. dnat ip to 1.2.3.4 are detected/handled during the evaluation phase. Signed-off-by: Florian Westphal <fw@strlen.de> Acked-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: update nft list plural form parametersFernando Fernandez Mancera2019-04-081-0/+6
| | | | | Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: use 'flow add' syntaxPablo Neira Ayuso2019-03-201-1/+1
| | | | | | As discussed during NFWS 2018. Old syntax is stilled allowed. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: Reject 'export vm json' commandPhil Sutter2018-12-211-9/+9
| | | | | | | | | | | | | | | | | | Since libnftnl recently dropped JSON output support, this form of JSON export is not available anymore. Point at 'nft -j list ruleset' command for a replacement in error message. Since 'export' command is not useable anymore, remove it from documentation. Instead point out that 'list ruleset' command serves well for dumping and later restoring. To not cause pointless inconvenience for users wishing to store their ruleset in JSON format, make JSON parser fallback to CMD_ADD if no recognized command property was found. This allows to feed the output of 'nft -j list ruleset' into 'nft -f' without any modification. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: grammar fixesJan Engelhardt2018-11-131-15/+15
| | | | | Signed-off-by: Jan Engelhardt <jengelh@inai.de> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: Spelling and grammar fixesVille Skyttä2018-11-131-3/+3
| | | | | Signed-off-by: Ville Skyttä <ville.skytta@iki.fi> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* nft.8: Clarify 'index' option of add rule commandPhil Sutter2018-11-121-4/+2
| | | | | | | | | | | | | | | | Documentation for add rule command might trick readers into believing the optional 'index' argument does not need to be that of an existing rule. This false assumption is fueled by the fact that iptables allows to insert with last rule number + 1 to actually append to a chain. Change the relevant sentence to clarify that. While being at it, drop the deprecated 'position' option from documentation - since this will likely go away at some point, don't encourage users to use it although they should notice that they shoudn't. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: remove unnecessary extra asterisk at the end of option linePablo Neira Ayuso2018-10-301-3/+3
| | | | | | For --guid, --numeric-protocol and --numeric-priority. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: add -p to print layer 4 protocol numericallyPablo Neira Ayuso2018-10-301-1/+5
| | | | | | | | We keep printing layer 4 protocols as literals since we do not use /etc/protocols. Add -p option to print layer 4 protocols numerically. Acked-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: get rid of nft_ctx_output_{get,set}_numeric()Pablo Neira Ayuso2018-10-301-4/+1
| | | | | | | | | | | | | | | | | | | | | | | This patch adds NFT_CTX_OUTPUT_NUMERIC_SYMBOL, which replaces the last client of the numeric level approach. This patch updates `-n' option semantics to display all output numerically. Note that monitor code was still using the -n option to skip printing the process name, this patch updates that path too to print it inconditionally to simplify things. Given the numeric levels have no more clients after this patch, remove that code. Update several tests/shell not to use -nn. This patch adds NFT_CTX_OUTPUT_NUMERIC_ALL which enables all flags to provide a fully numerical output. Acked-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: add -y to priority base chain nummericallyPablo Neira Ayuso2018-10-291-0/+4
| | | | | | | | By default base chains are printed using default hook priority definitions. Add -y option to print them as numbers. Acked-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>