summaryrefslogtreecommitdiffstats
path: root/doc
Commit message (Collapse)AuthorAgeFilesLines
...
* doc: libnftables-json: Review asciidoc syntaxPhil Sutter2018-06-181-184/+142
| | | | | | | | | | | | | | | | | | | | This changes asciidoc markup according to a few best practices recommended in [1] and a quick review of html output: * Use atx-style headings everywhere apart from the document title. This requires to explicitly disable compat-mode after the latter. * Use only the minimum number of dashes for listings. * Enclose verses with empty lines in a verse block instead of having multiple verses for it. * Indent continued lines in synopsis for added readability. [1] https://asciidoctor.org/docs/asciidoc-recommended-practices/ Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* libnftables: Simplify nft_run_cmd_from_buffer footprintPhil Sutter2018-06-181-5/+4
| | | | | | | | | | | | | | | | | | | | | | | With libnftables documentation being upstream and one confirmed external user (nftlb), time to break the API! First of all, the command buffer passed to nft_run_cmd_from_buffer may (and should) be const. One should consider it a bug if that function ever changed it's content. On the other hand, there is no point in passing the buffer's length as separate argument: NULL bytes are not expected to occur in the input, so it is safe to rely upon strlen(). Also, the actual parsers don't require a buffer length passed to them, either. The only use-case for it is when reallocating the buffer to append a final newline character, there strlen() is perfectly sufficient. Suggested-by: Harald Welte <laforge@gnumonks.org> Cc: Laura Garcia Liebana <nevola@gmail.com> Cc: Eric Leblond <eric@regit.org> Cc: Arturo Borrero Gonzalez <arturo@netfilter.org> Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: Fix typo in Makefile.amPhil Sutter2018-06-161-1/+1
| | | | | | | | Previous patch adding libnftables man page missed a backslash. Fixes: 3c57ff87b1b2b ("doc: Add libnftables man page") Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: Add libnftables man pagePhil Sutter2018-06-153-3/+324
| | | | | | | | For now, use a single man page to describe all the functions exported by libnftables. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: Add JSON schema documentationPhil Sutter2018-06-113-4/+1251
| | | | | | | | | | The document is written as man page in asciidoc which means this adds another dependency to the build system. Though since the (long-term) plan is to replace the docbook-based nft man page with an asciidoc one anyway, we might ultimately get rid of docbook dependency in exchange. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* nft.8: Fix reject statement documentationPhil Sutter2018-06-061-5/+5
| | | | | | | | | | First of all, 'with icmp6' is invalid, expected is 'with icmpv6'. In addition to that, parameter 'type' expects an icmp*_code type, not icmp*_type. The respective table column was already correct, but in synopsis it was wrong. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Florian Westphal <fw@strlen.de>
* nft.8: Document limitation of reject statement in bridge familyPhil Sutter2018-05-171-0/+4
| | | | | | | | Bridge family allows reject statement in prerouting and input chains only. Users can't know without looking at kernel code. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Florian Westphal <fw@strlen.de>
* nft.8: Drop misleading adjective 'absolute'Phil Sutter2018-05-111-1/+1
| | | | | | | | Discussion showed that rule index may be interpreted as being absolute or relative, so just drop this adjective without replacement. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* Support 'add/insert rule index <IDX>'Phil Sutter2018-05-091-7/+24
| | | | | | | | | | | Allow to specify an absolute rule position in add/insert commands like with iptables. The translation to rule handle takes place in userspace, so no kernel support for this is needed. Possible undesired effects are pointed out in man page to make users aware that this way of specifying a rule location might not be ideal. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* Deprecate add/insert rule 'position' argumentPhil Sutter2018-05-091-4/+13
| | | | | | | | | | Instead, use 'handle' keyword for the same effect since that is more consistent with respect to replace/delete commands. The old keyword is still supported for backwards compatibility and also listed in man page along with a hint that it shouldn't be used anymore. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: add size keyword to meter exampleFlorian Westphal2018-05-091-1/+1
| | | | Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: update doc/ispell_nft to track recent nft.8 updatesDuncan Roe2018-05-031-2/+2
| | | | | | | | | Track changes in commits 3baa28f24b3d70a7ee17d584c113a2c4e057a565 and 4787edad132c30ae0f6bb00135ae5d970b0ccb74 (rename ibriport and obriport: s/iport/name). Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: reword insert position, this expects rule handle to insert, not a ↵Florian Westphal2018-04-241-3/+3
| | | | | | relative postition Signed-off-by: Florian Westphal <fw@strlen.de>
* src: use ibrname and obrnamePablo Neira Ayuso2018-04-191-4/+4
| | | | | | | | | Legacy tool name is 'brctl' and so the 'br' prefix is already known. If we use ibrname and obrname it looks consistent with iifname and oifname. So let's this instead of ibridgename and obridgename since Florian likes this too. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: rename ibrportname, obrportnameFlorian Westphal2018-04-171-4/+4
| | | | | | | | | | | | | | | For bridge, iifname is the port name, whereas 'ibrport' is the logical name of the bridge ("br0") the port ("iifname") is enslaved to. So, 'ibrport' is a misnomer. libnftl calls these 'bri_iifname' and 'bri_oifname', which is good but using 'briiifname' in nft is rather ugly, so use 'ibridgename' and 'obridgename' instead. Old names are still recognized, listing shows the new names. Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: nft.8 more spelling fixesDuncan Roe2018-03-272-27/+244
| | | | | | | | | | | | | | | | | | | | | | | | I ran the following command: ispell -p ./ispell_nft -H nft.xml to create the local dictionary ispell_nft. ispell_nft contains almost every special word in nft.xml. The idea is that anyone can run ispell the same way and only have to accept: - alpha strings in hexadecimal numbers - "FIXME" : that has to be fixed eventually - "differv" : I don't know what that is or whether it's correct You need to use the English (i.e. American) dictionary, and you want the screen to be about 100 chars wide (at least). The patch enforces consistent capitalisation of words, e.g. IPv4 is always that way but ipv4_addr stays as before. The existing dictionary suggested capital Ethernet so that is in there too. Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Florian Westphal <fw@strlen.de>
* Support 'nft -f -' to read from stdinPhil Sutter2018-03-201-1/+1
| | | | | | | | | | | | | | | | | | In libnftables, detect if given filename is '-' and treat it as the common way of requesting to read from stdin, then open /dev/stdin instead. (Calling 'nft -f /dev/stdin' worked before as well, but this makes it official.) With this in place and bash's support for here strings, review all tests in tests/shell for needless use of temp files. Note that two categories of test cases were intentionally left unchanged: - Tests creating potentially large rulesets to avoid running into shell parameter length limits. - Tests for 'include' directive for obvious reasons. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft.8 aim for consistent synopses throughout (again)Duncan Roe2018-03-191-15/+7
| | | | | | | | | Fix a few more items as per commit f9cb9580b924f6320005f429f7d59e52a38aff82 Also insert a missing space I noticed along the way Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: describe table dormant flagFlorian Westphal2018-03-171-1/+62
| | | | | | | | also mention how to quit interactive mode and provide small table add example. Signed-off-by: Florian Westphal <fw@strlen.de> Acked-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: fix routing header supportFlorian Westphal2018-03-171-0/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | We can't use nft_exthdr_op to encode routing header, it breaks ipv6 extension header support. When encountering RT header, userspace did now set a new ipv6 exthdr mode, but old kernel doesn't know about this, so this failed with -EOPNOTSUPP. Revert that part and use NFT_EXTHDR_OP_IPV6. When decoding a routing extension header, try the various route types until we find a match. Note this patch isn't complete: 'srh tag 127' creates following expressions: [ exthdr load 2b @ 43 + 6 => reg 1 ] [ cmp eq reg 1 0x00007f00 ] It should instead insert a dependency test ("rt type 4"): [ exthdr load 1b @ 43 + 2 => reg 1 ] [ cmp eq reg 1 0x00000004 ] [ exthdr load 2b @ 43 + 6 => reg 1 ] [ cmp eq reg 1 0x00007e00 ] nft should then use this to infer the routing header type. While add it, document the srh option. Fixes: 1400288f6d39d ("src: handle rt0 and rt2 properly") Reported-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Florian Westphal <fw@strlen.de> Acked-by: Ahmed Abdelsalam <amsalam20@gmail.com>
* src: revisit syntax to update sets and maps from packet pathPablo Neira Ayuso2018-03-161-5/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | For sets, we allow this: nft add rule x y ip protocol tcp update @y { ip saddr} For maps: table ip nftlb { map persistencia { type ipv4_addr : mark timeout 1h elements = { 192.168.1.132 expires 59m55s : 0x00000064, 192.168.56.101 expires 59m24s : 0x00000065 } } chain pre { type nat hook prerouting priority 0; policy accept; update @persistencia \ { @nh,96,32 : numgen inc mod 2 offset 100 } } } nft --debug=netlink add rule ip nftlb pre add @persistencia \ { ip saddr : numgen inc mod 2 offset 100 } More compact and it doesn't gets it confused with a simple map update command (interesting that bison didn't spew any conflict error). Former syntax for sets is preserved. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: add set information and example for run-time blackholeFlorian Westphal2018-03-111-2/+79
| | | | Signed-off-by: Florian Westphal <fw@strlen.de>
* doc/nft.xml: Add deletion for objects via handlesHarsha Sharma2018-03-051-1/+36
| | | | | | | | Add documentation for deletion of tables, chains, sets and objects via unique handles. Signed-off-by: Harsha Sharma <harshasharmaiitr@gmail.com> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft: document flowtablePablo Neira Ayuso2018-03-051-0/+103
| | | | | | Document the new flowtable objects available since Linux kernel 4.16-rc. Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: add example for rule add/deleteFlorian Westphal2018-02-281-0/+27
| | | | | | also mention that 'ip' is used when the family gets omitted. Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: remove ipv6 address FIXMEFlorian Westphal2018-02-281-1/+11
| | | | Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: mention meta l4proto and ipv6 nexthdr issue wrt. extension headersFlorian Westphal2018-02-271-1/+25
| | | | Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: document raw protocol expressionFlorian Westphal2018-02-261-0/+59
| | | | Signed-off-by: Florian Westphal <fw@strlen.de>
* meta: introduce datatype ifname_typeArturo Borrero Gonzalez2018-02-251-4/+4
| | | | | | | | | | | | | | | | | | | | | | | | This new datatype is a string subtype. It will allow us to build named maps/sets using meta keys like 'iifname', 'oifname', 'ibriport' or 'obriport'. Example: table inet t { set s { type ifname elements = { "eth0", "eth1" } } chain c { iifname @s accept oifname @s accept } } Signed-off-by: Arturo Borrero Gonzalez <arturo@netfilter.org> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc/nft.xml: fix typoDuncan Roe2018-02-181-1/+1
| | | | | Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Florian Westphal <fw@strlen.de>
* src: Spelling fixesVille Skyttä2018-02-151-1/+1
| | | | | Signed-off-by: Ville Skyttä <ville.skytta@iki.fi> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: dup and fwd statementsFlorian Westphal2018-01-311-0/+80
| | | | | Signed-off-by: Florian Westphal <fw@strlen.de> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: add 'auto-merge' option to setsPablo Neira Ayuso2018-01-221-0/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | After discussions with Karel here: https://bugzilla.netfilter.org/show_bug.cgi?id=1184 And later on with Phil Sutter, we decided to disable the automatic merge feature in sets with intervals. This feature is problematic because it introduces an inconsistency between what we add and what we later on get. This is going to get worse with the upcoming timeout support for intervals. Therefore, we turned off this by default. However, Jeff Kletsky and folks like this feature, so let's restore this behaviour on demand with this new 'auto-merge' statement, that you can place on the set definition, eg. # nft list ruleset table ip x { ... set y { type ipv4_addr flags interval auto-merge } } # nft add element x z { 1.1.1.1-2.2.2.2, 1.1.1.2 } Regarding implementation details: Given this feature only makes sense from userspace, let's store this in the set user data area, so nft knows it has to do automatic merge of adjacent/overlapping elements as per user request. # nft add set x z { type ipv4_addr\; auto-merge\; } Error: auto-merge only works with interval sets add set x z { type ipv4_addr; auto-merge; } ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Fixes: https://bugzilla.netfilter.org/show_bug.cgi?id=1216 Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc/nft.xml: mention nftables earlierArturo Borrero Gonzalez2018-01-191-3/+4
| | | | | | | | | | | | | | | | | Mention nftables earlier in the documentation, so users have more context on what we are talking about. This is Debian bug #887718, which contains: <<< Currently one must read down 100 lines before it is even mentioned. You might want to make the connection between "nft" and "nftables" as early as the NAME or DESCRIPTION. >>> Requested-by: Dan Jacobson <jidanni@jidanni.org> Signed-off-by: Arturo Borrero Gonzalez <arturo@netfilter.org> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* meta: add secpath supportFlorian Westphal2018-01-161-0/+10
| | | | | | | | | This can be used to check if a packet has a secpath attached to it, i.e. was subject to ipsec processing. Example: add rule inet raw prerouting meta secpath exists accept Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: nft.8 aim for consistent synopses throughoutDuncan Roe2017-12-031-74/+73
| | | | | | | | | | | Single items in braces have the braces removed as per wiki Scripting: "It is simply overkill to define a set that only stores one single element". Items that were in braces or square brackets are made consistent, e.g. {family} expands to single wor Ip, inet &c., but (type) in set spec expands to "type type_name ;". Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: nft.8 Syslog level is introduced by "level" not "syslog-level"Duncan Roe2017-11-271-1/+1
| | | | | | | | | | The log synopsis line correctly documents that keyword "level" introduces "syslog-level", but the keyword table entry did not. Discovered on trying to use "syslog-level" in a script. Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft.8 document use of -f option to start nft scriptsDuncan Roe2017-11-201-0/+3
| | | | | | | | | The man page didn't document nft scripts at all before, so putting that with the -f option seemed as good a place as any. It does work to start scripts is also updated. Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: nft.8 simplify initial SYNOPSIS lineDuncan Roe2017-10-241-52/+14
| | | | | | | | | In the style of tcpdump.8: where options have short and long forms, only show short form in synopsis but mention long form in description. Re-order option descriptions to match order in synopsis (move -N to just after -n). Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft.8 change "Native Address Translation" to "Network Address Translation"Duncan Roe2017-10-171-1/+1
| | | | | | | | | | A Google search for "Native Address Translation" found 1 entry (http://encyclopedia2.thefreedictionary.com/Native+address+translation) which redirects to .../Network+address+translation. All other matches are to entries about "Network Address Translation". Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft.8 Document rule replaceDuncan Roe2017-10-091-0/+17
| | | | | | | Insert synopsis and description between those for add|insert and delete Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: nft.8 add chain synopsisDuncan Roe2017-10-061-2/+2
| | | | | | | | | | | | | | | | | The man page says this: > {add | create} chain [family] table chain [ { {type} {hook} [device] {priority} } [policy] ] But I suggest it should say this: > {add | create} chain [family] table chain [ { {type} {hook} [device] {priority ;} [policy ;] } ] i.e. the policy tuple should be inside the braces along with type, hook, device & priority. Also the device & priority tuples each need to be followed by a semicolon. Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* doc: update man pageFlorian Westphal2017-09-291-5/+18
| | | | | | | you can now use "rt ip|ip6 nexthop" and "ct original|reply ip|ip6 saddr|daddr" to tell nft if you want to match ipv4 or ipv6. Signed-off-by: Florian Westphal <fw@strlen.de>
* doc: nft: Fix and enhance synopsis sectionPhil Sutter2017-08-281-24/+50
| | | | | | | | | | | | | | | | | | | This patch addresses shortcomings in the main synopsis section illustrating possible invocations of nft command: - Fix font styles to correctly put options into bold font and meta characters (brackets, pipes) into normal font. - Add missing options to synopsis line. - Use curly braces where either one of the alternatives is required. - Remove choice="opt" attribute since that is the default anyway. - Note that --includepath option is allowed to be given multiple times. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* evaluate: convert expr_rt byteorder when evaluating statment argFlorian Westphal2017-08-281-2/+2
| | | | | | | | | | | | | | expr_rt might write data in host byte order, so make sure to convert if needed. This makes 'tcp option maxseg size rt mtu' actually work, right now such rules are no-ops because nft_exthdr never increases the mss. While at it, extend the example to not bother testing non-syn packets. Reported-by: Matteo Croce <technoboy85@gmail.com> Signed-off-by: Florian Westphal <fw@strlen.de> Acked-by: Pablo Neira Ayuso <pablo@netfilter.org>
* rt: add path mtu supportFlorian Westphal2017-08-221-0/+7
| | | | | | | | | | Only use case is to allow similar behaviour to iptables TCPMSS --clamp-mss-to-pmtu, by combining this with exthdr statement: tcp option maxseg size set rt mtu Signed-off-by: Florian Westphal <fw@strlen.de> Acked-by: Pablo Neira Ayuso <pablo@netfilter.org>
* src: add tcp options set supportFlorian Westphal2017-08-221-0/+16
| | | | | | | | | | | | This adds support for tcp mss mangling: nft add rule filter input tcp option maxseg size 1200 Its also possible to change other tcp option fields, but maxseg is one of the more useful ones to change. Signed-off-by: Florian Westphal <fw@strlen.de> Acked-by: Pablo Neira Ayuso <pablo@netfilter.org>
* man: use https for wiki linkDaniel Kahn Gillmor2017-08-141-1/+1
| | | | | | | | | | https works for the wiki, and users should prefer it by default, whether they are logging in (to protect their credentials) or whether they're reading data (to protect the integrity of the content). Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net> Acked-by: Arturo Borrero Gonzalez <arturo@netfilter.org> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* man: Fix typo.Varsha Rao2017-08-141-1/+1
| | | | | | | The word 'occur' is misspelled as 'ocurr'. This patch fixes it. Signed-off-by: Varsha Rao <rvarsha016@gmail.com> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
* nft.8: Complete short description of arp familyPhil Sutter2017-08-141-1/+1
| | | | | | | Although not very informational, still better than ending mid-sentence. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>