diff options
| -rw-r--r-- | doc/data-types.txt | 16 | ||||
| -rw-r--r-- | doc/nft.txt | 50 | ||||
| -rw-r--r-- | doc/payload-expression.txt | 10 | ||||
| -rw-r--r-- | doc/primary-expression.txt | 18 | ||||
| -rw-r--r-- | doc/statements.txt | 50 |
5 files changed, 72 insertions, 72 deletions
diff --git a/doc/data-types.txt b/doc/data-types.txt index 87962595..2692afde 100644 --- a/doc/data-types.txt +++ b/doc/data-types.txt @@ -39,7 +39,7 @@ variable | The string type is used for character strings. A string begins with an alphabetic character (a-zA-Z) followed by zero or more alphanumeric characters -or the characters /, -, _ and .. In addition anything enclosed in double +or the characters /, -, _ and .. In addition anything enclosed in double quotes (") is recognized as a string. .String specification @@ -83,7 +83,7 @@ ipv4_addr| integer |=================== -The IPv4 address type is used for IPv4 addresses. Addresses are specified in +The IPv4 address type is used for IPv4 addresses. Addresses are specified in either dotted decimal, dotted hexadecimal, dotted octal, decimal, hexadecimal, octal notation or as a host name. A host name will be resolved using the standard system resolver. @@ -108,7 +108,7 @@ ipv6_addr| integer |=================== -The IPv6 address type is used for IPv6 addresses. Addresses are specified as a +The IPv6 address type is used for IPv6 addresses. Addresses are specified as a host name or as hexadecimal halfwords separated by colons. Addresses might be enclosed in square brackets ("[]") to differentiate them from port numbers. @@ -136,7 +136,7 @@ boolean | integer |=================== -The boolean type is a syntactical helper type in userspace. It's use is in the +The boolean type is a syntactical helper type in userspace. It's use is in the right-hand side of a (typically implicit) relational expression to change the expression on the left-hand side into a boolean check (usually for existence). + @@ -160,7 +160,7 @@ Check route existence. |exthdr| Check IPv6 extension header existence. |tcp option | -Check TCP option header existence. +Check TCP option header existence. |=================== .Boolean specification @@ -240,7 +240,7 @@ icmp_code | integer |=================== -The ICMP Code type is used to conveniently specify the ICMP header's code field. +The ICMP Code type is used to conveniently specify the ICMP header's code field. .Keywords may be used when specifying the ICMP code [options="header"] @@ -273,7 +273,7 @@ icmpx_code | integer |=================== -The ICMPv6 Type type is used to conveniently specify the ICMPv6 header's type field. +The ICMPv6 Type type is used to conveniently specify the ICMPv6 header's type field. .keywords may be used when specifying the ICMPv6 type: [options="header"] @@ -336,7 +336,7 @@ icmpv6_code | integer |=================== -The ICMPv6 Code type is used to conveniently specify the ICMPv6 header's code field. +The ICMPv6 Code type is used to conveniently specify the ICMPv6 header's code field. .keywords may be used when specifying the ICMPv6 code [options="header"] diff --git a/doc/nft.txt b/doc/nft.txt index 2a1a2977..9d04e435 100644 --- a/doc/nft.txt +++ b/doc/nft.txt @@ -17,7 +17,7 @@ DESCRIPTION ----------- nft is the command line tool used to set up, maintain and inspect packet filtering and classification rules in the Linux kernel, in the nftables -framework. The Linux kernel subsystem is known as nf_tables, and `nf' stands +framework. The Linux kernel subsystem is known as nf_tables, and `nf' stands for Netfilter. OPTIONS @@ -46,9 +46,9 @@ For a full summary of options, run *nft --help*. *-l*:: *--literal*:: Translate numeric to literal. When used once (the default - behaviour), print services (instead of numerical port numbers). Use + behaviour), print services (instead of numerical port numbers). Use twice to perform the IP address to name lookup, this usually - requires network traffic for DNS lookup that slows down the + requires network traffic for DNS lookup that slows down the ruleset listing. *-c*:: @@ -61,7 +61,7 @@ For a full summary of options, run *nft --help*. *-e*:: *--echo*:: - When inserting items into the ruleset using *add*, *insert* or *replace* commands, print notifications + When inserting items into the ruleset using *add*, *insert* or *replace* commands, print notifications just like *nft monitor*. *-I*:: @@ -76,7 +76,7 @@ For a full summary of options, run *nft --help*. *-i*:: *--interactive*:: - Read input from an interactive readline CLI. You can use quit to exit, or use the EOF marker, + Read input from an interactive readline CLI. You can use quit to exit, or use the EOF marker, normally this is CTRL-D. INPUT FILE FORMATS @@ -105,7 +105,7 @@ Other files can be included by using the *include* statement. The directories to be searched for include files can be specified using the *-I*/*--includepath* option. You can override this behaviour either by prepending `./' to your path to force inclusion of files located in the current working directory (i.e. -relative path) or / for file location expressed as an absolute path. + +relative path) or / for file location expressed as an absolute path. + If *-I*/*--includepath* is not specified, then nft relies on the default directory that is specified at compile time. You can retrieve this default @@ -332,7 +332,7 @@ statements for instance). |route | ip, ip6 | output | If a packet has traversed a chain of this type and is about to be accepted, a new route lookup is performed if relevant parts of the IP header have changed. -This allows to e.g. implement policy routing selectors in nftables. +This allows to e.g. implement policy routing selectors in nftables. |================= Apart from the special cases illustrated above (e.g. *nat* type not supporting @@ -403,11 +403,11 @@ ip family is used. Rules are constructed from two kinds of components according to a set of grammatical rules: expressions and statements. The add and insert commands support an optional location specifier, which is -either a 'handle' of an existing rule or an 'index' (starting at zero). +either a 'handle' of an existing rule or an 'index' (starting at zero). Internally, rule locations are always identified by 'handle' and the translation from 'index' happens in userspace. This has two potential implications in case a concurrent ruleset change happens after the translation was done: The effective -rule index might change if a rule was inserted or deleted before the referred +rule index might change if a rule was inserted or deleted before the referred one. If the referred rule was deleted, the command is rejected by the kernel just as if an invalid 'handle' was given. @@ -449,7 +449,7 @@ table inet filter { SETS ---- -nftables offers two kinds of set concepts. Anonymous sets are sets that have no +nftables offers two kinds of set concepts. Anonymous sets are sets that have no specific name. The set members are enclosed in curly braces, with commas to separate elements when creating the rule the set is used in. Once that rule is removed, the set is removed as well. They cannot be updated, i.e. once an @@ -504,7 +504,7 @@ string: ipv4_addr, ipv6_addr, ether_addr, inet_proto, inet_service, mark set flags | string: constant, dynamic, interval, timeout |timeout | -time an element stays in the set, mandatory if set is added to from the packet path (ruleset).| +time an element stays in the set, mandatory if set is added to from the packet path (ruleset).| string, decimal followed by unit. Units are: d, h, m, s |gc-interval | garbage collection interval, only available when timeout or flag timeout are @@ -520,7 +520,7 @@ unsigned integer (64 bit) set policy | string: performance [default], memory |auto-merge | -automatic merge of adjacent/overlapping set elements (only for interval sets) | +automatic merge of adjacent/overlapping set elements (only for interval sets) | |================= @@ -573,7 +573,7 @@ Flowtables allow you to accelerate packet forwarding in software. Flowtables entries are represented through a tuple that is composed of the input interface, source and destination address, source and destination port; and layer 3/4 protocols. Each entry also caches the destination interface and the gateway -address - to update the destination link-layer address - to forward packets. +address - to update the destination link-layer address - to forward packets. The ttl and hoplimit fields are also decremented. Hence, flowtables provides an alternative path that allow packets to bypass the classic forwarding path. Flowtables reside in the ingress hook, that is located before the prerouting @@ -581,7 +581,7 @@ hook. You can select what flows you want to offload through the flow offload expression from the forward chain. Flowtables are identified by their address family and their name. The address family must be one of ip, ip6, inet. The inet address family is a dummy family which is used to create hybrid IPv4/IPv6 -tables. When no address family is specified, ip is used by default. +tables. When no address family is specified, ip is used by default. The *priority* can be a signed integer or *filter* which stands for 0. Addition and substraction can be used to set relative priority eg. filter + 5 equals to @@ -614,7 +614,7 @@ include::stateful-objects.txt[] EXPRESSIONS ------------ Expressions represent values, either constants like network addresses, port -numbers etc. or data gathered from the packet during ruleset evaluation. +numbers etc. or data gathered from the packet during ruleset evaluation. Expressions can be combined using binary, logical, relational and other types of expressions to form complex or relational (match) expressions. They are also used as arguments to certain types of operations, like NAT, packet marking etc. @@ -648,8 +648,8 @@ cwr 0x80 DATA TYPES ---------- -Data types determine the size, parsing and representation of symbolic values -and type compatibility of expressions. A number of global data types exist, in +Data types determine the size, parsing and representation of symbolic values +and type compatibility of expressions. A number of global data types exist, in addition some expression types define further data types specific to the expression type. Most data types have a fixed size, some however may have a dynamic size, f.i. the string type. + @@ -665,7 +665,7 @@ include::data-types.txt[] PRIMARY EXPRESSIONS ------------------- -The lowest order expression is a primary expression, representing either a +The lowest order expression is a primary expression, representing either a constant or a single datum from a packet's payload, meta data or a stateful module. @@ -683,10 +683,10 @@ Statements represent actions to be performed. They can alter control flow (return, jump to a different chain, accept or drop the packet) or can perform actions, such as logging, rejecting a packet, etc. + -Statements exist in two kinds. Terminal statements unconditionally terminate +Statements exist in two kinds. Terminal statements unconditionally terminate evaluation of the current rule, non-terminal statements either only conditionally or never terminate evaluation of the current rule, in other words, -they are passive from the ruleset evaluation perspective. There can be an +they are passive from the ruleset evaluation perspective. There can be an arbitrary amount of non-terminal statements in a rule, but only a single terminal statement as the final statement. @@ -699,13 +699,13 @@ These are some additional commands included in nft. MONITOR ~~~~~~~~ The monitor command allows you to listen to Netlink events produced by the -nf_tables subsystem, related to creation and deletion of objects. When they +nf_tables subsystem, related to creation and deletion of objects. When they occur, nft will print to stdout the monitored events in either XML, JSON or native nft format. + To filter events related to a concrete object, use one of the keywords 'tables', 'chains', 'sets', 'rules', 'elements', 'ruleset'. + -To filter events related to a concrete action, use keyword 'new' or 'destroy'. +To filter events related to a concrete action, use keyword 'new' or 'destroy'. Hit ^C to finish the monitor operation. @@ -736,7 +736,7 @@ Hit ^C to finish the monitor operation. ERROR REPORTING --------------- -When an error is detected, nft shows the line(s) containing the error, the +When an error is detected, nft shows the line(s) containing the error, the position of the erroneous parts in the input stream and marks up the erroneous parts using carets (^). If the error results from the combination of two expressions or statements, the part imposing the constraints which are violated @@ -781,13 +781,13 @@ There is an official wiki at: https://wiki.nftables.org AUTHORS ------- -nftables was written by Patrick McHardy and Pablo Neira Ayuso, among many other contributors from the Netfilter community. +nftables was written by Patrick McHardy and Pablo Neira Ayuso, among many other contributors from the Netfilter community. COPYRIGHT --------- Copyright © 2008-2014 Patrick McHardy <kaber@trash.net> Copyright © 2013-2018 Pablo Neira Ayuso <pablo@netfilter.org> + -nftables is free software; you can redistribute it and/or modify it under the +nftables is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. + diff --git a/doc/payload-expression.txt b/doc/payload-expression.txt index b67818b6..2a89b922 100644 --- a/doc/payload-expression.txt +++ b/doc/payload-expression.txt @@ -136,7 +136,7 @@ integer (16 bit) ID of echo request/response | integer (16 bit) |sequence| -sequence number of echo request/response| +sequence number of echo request/response| integer (16 bit) |gateway| gateway of redirects| @@ -543,7 +543,7 @@ Conntrack expressions refer to meta data of the connection tracking entry associ There are three types of conntrack expressions. Some conntrack expressions require the flow direction before the conntrack key, others must be used -directly because they are direction agnostic. The *packets*, *bytes* and +directly because they are direction agnostic. The *packets*, *bytes* and *avgpkt* keywords can be used with or without a direction. If the direction is omitted, the sum of the original and the reply direction is returned. The same is true for the *zone*, if a direction is given, the zone is only matched if the @@ -577,7 +577,7 @@ time Helper associated with the connection| string |label| -Connection tracking label bit or symbolic name defined in connlabel.conf in the nftables include path| +Connection tracking label bit or symbolic name defined in connlabel.conf in the nftables include path| ct_label |l3proto| Layer 3 protocol of the connection| @@ -595,7 +595,7 @@ inet_proto Layer 4 protocol source for the given direction| integer (16 bit) |proto-dst| -Layer 4 protocol destination for the given direction | +Layer 4 protocol destination for the given direction | integer (16 bit) |packets| packet count seen in the given direction or sum of original and reply | @@ -604,7 +604,7 @@ integer (64 bit) byte count seen, see description for *packets* keyword | integer (64 bit) |avgpkt| -average bytes per packet, see description for *packets* keyword | +average bytes per packet, see description for *packets* keyword | integer (64 bit) |zone| conntrack zone | diff --git a/doc/primary-expression.txt b/doc/primary-expression.txt index 12b88bdd..18b4c52f 100644 --- a/doc/primary-expression.txt +++ b/doc/primary-expression.txt @@ -11,7 +11,7 @@ A meta expression refers to meta data associated with a packet. There are two types of meta expressions: unqualified and qualified meta expressions. Qualified meta expressions require the meta keyword before the meta key, unqualified meta expressions can be specified by using the meta key -directly or as qualified meta expressions. Meta l4proto is useful to match a +directly or as qualified meta expressions. Meta l4proto is useful to match a particular transport protocol that is part of either an IPv4 or IPv6 packet. It will also skip any IPv6 extension headers present in an IPv6 packet. @@ -23,7 +23,7 @@ will also skip any IPv6 extension headers present in an IPv6 packet. Length of the packet in bytes| integer (32 bit) |nfproto| -real hook protocol family, useful only in inet table| +real hook protocol family, useful only in inet table| integer (32 bit) |l4proto| layer 4 protocol, skips ipv6 extension headers| @@ -56,10 +56,10 @@ ifname Output interface hardware type| iface_type |skuid| -UID associated with originating socket| +UID associated with originating socket| uid |skgid| -GID associated with originating socket| +GID associated with originating socket| gid |rtclassid| Routing realm| @@ -98,7 +98,7 @@ boolean (1 bit) |================== |Type | Description |iface_index | -Interface index (32 bit number). Can be specified numerically or as name of an existing interface. +Interface index (32 bit number). Can be specified numerically or as name of an existing interface. |ifname| Interface name (16 byte string). Does not have to exist. |iface_type| @@ -108,11 +108,11 @@ User ID (32 bit number). Can be specified numerically or as user name. |gid| Group ID (32 bit number). Can be specified numerically or as group name. |realm| -Routing Realm (32 bit number). Can be specified numerically or as symbolic name defined in /etc/iproute2/rt_realms. +Routing Realm (32 bit number). Can be specified numerically or as symbolic name defined in /etc/iproute2/rt_realms. |devgroup_type| -Device group (32 bit number). Can be specified numerically or as symbolic name defined in /etc/iproute2/group. +Device group (32 bit number). Can be specified numerically or as symbolic name defined in /etc/iproute2/group. |pkt_type| -Packet type: Unicast (addressed to local host), Broadcast (to all), Multicast (to group). +Packet type: Unicast (addressed to local host), Broadcast (to all), Multicast (to group). |============================= .Using meta expressions @@ -266,7 +266,7 @@ integer (16 bit) |======================= |Type| Description |realm| -Routing Realm (32 bit number). Can be specified numerically or as symbolic name defined in /etc/iproute2/rt_realms. +Routing Realm (32 bit number). Can be specified numerically or as symbolic name defined in /etc/iproute2/rt_realms. |======================== .Using routing expressions diff --git a/doc/statements.txt b/doc/statements.txt index b93cf2cf..39d9f144 100644 --- a/doc/statements.txt +++ b/doc/statements.txt @@ -13,7 +13,7 @@ The verdict statement alters control flow in the ruleset and issues policy decis *continue*:: Continue ruleset evaluation with the next rule. FIXME *return*:: Return from the current chain and continue evaluation at the next rule in the last chain. If issued in a base chain, it is equivalent to *accept*. -*jump* 'chain':: Continue evaluation at the first rule in 'chain'. The current +*jump* 'chain':: Continue evaluation at the first rule in 'chain'. The current position in the ruleset is pushed to a call stack and evaluation will continue there when the new chain is entirely evaluated of a *return* verdict is issued. *goto* 'chain':: Similar to *jump*, but the current position is not pushed to the @@ -31,7 +31,7 @@ filter input iif eth0 drop PAYLOAD STATEMENT ~~~~~~~~~~~~~~~~~ -The payload statement alters packet content. It can be used for example to +The payload statement alters packet content. It can be used for example to set ip DSCP (differv) header field or ipv6 flow labels. .route some packets instead of bridging @@ -71,7 +71,7 @@ packets, such as header fields, via the kernel log (where it can be read with dmesg(1) or read in the syslog). If the group number is specified, the Linux kernel will pass the packet to nfnetlink_log which will multicast the packet through a netlink socket to the specified multicast group. One or more userspace -processes may subscribe to the group to receive the packets, see +processes may subscribe to the group to receive the packets, see libnetfilter_queue documentation for details. This is a non-terminating statement, so the rule evaluation continues after the packet is logged. @@ -84,7 +84,7 @@ Log message prefix| quoted string |level| Syslog level of logging | -string: emerg, alert, crit, err, warn [default], notice, info, debug +string: emerg, alert, crit, err, warn [default], notice, info, debug |group| NFLOG group to send messages to| unsigned integer (16 bit) @@ -92,7 +92,7 @@ unsigned integer (16 bit) Length of packet payload to include in netlink message | unsigned integer (32 bit) |queue-threshold| -Number of packets to queue inside the kernel before sending them to userspace | +Number of packets to queue inside the kernel before sending them to userspace | unsigned integer (32 bit) |================================== @@ -154,7 +154,7 @@ icmpx_code |================== For a description of the different types and a list of supported keywords refer -to DATA TYPES section above. The common default reject value is +to DATA TYPES section above. The common default reject value is *port-unreachable*. + Note that in bridge family, reject statement is only allowed in base chains @@ -174,7 +174,7 @@ The conntrack statement can be used to set the conntrack mark and conntrack labe [verse] *ct* {mark | event | label | zone} set 'value' -The ct statement sets meta data associated with a connection. The zone id +The ct statement sets meta data associated with a connection. The zone id has to be assigned before a conntrack lookup takes place, i.e. this has to be done in prerouting and possibly output (if locally generated packets need to be placed in a distinct zone), with a hook priority of -300. @@ -258,7 +258,7 @@ LIMIT STATEMENT *limit* rate [over] 'byte_number' {bytes | kbytes | mbytes} / {second | minute | hour | day | week} [burst 'byte_number' bytes] A limit statement matches at a limited rate using a token bucket filter. A rule -using this statement will match until this limit is reached. It can be used in +using this statement will match until this limit is reached. It can be used in combination with the log statement to give limited logging. The over keyword, that is optional, makes it match over the specified rate. @@ -289,11 +289,11 @@ NAT STATEMENTS The nat statements are only valid from nat chain types. + The *snat* and *masquerade* statements specify that the source address of the -packet should be modified. While *snat* is only valid in the postrouting and +packet should be modified. While *snat* is only valid in the postrouting and input chains, *masquerade* makes sense only in postrouting. The dnat and redirect statements are only valid in the prerouting and output chains, they -specify that the destination address of the packet should be modified. You can -use non-base chains which are called from base chains of nat chain type too. +specify that the destination address of the packet should be modified. You can +use non-base chains which are called from base chains of nat chain type too. All future packets in this connection will also be mangled, and rules should cease being examined. @@ -301,7 +301,7 @@ The *masquerade* statement is a special form of snat which always uses the outgoing interface's IP address to translate to. It is particularly useful on gateways with dynamic (public) IP addresses. -The *redirect* statement is a special form of dnat which always translates the +The *redirect* statement is a special form of dnat which always translates the destination address to the local host's one. It comes in handy if one only wants to alter the destination port of incoming traffic on different interfaces. @@ -314,7 +314,7 @@ netfilter and therefore no reverse translation will take place. |================== |Expression| Description| Type |address| -Specifies that the source/destination address of the packet should be modified. +Specifies that the source/destination address of the packet should be modified. You may specify a mapping to relate a list of tuples composed of arbitrary expression key with address value. | ipv4_addr, ipv6_addr, e.g. abcd::1234, or you can use a mapping, e.g. meta mark map { 10 : 192.168.1.2, 20 : 192.168.1.3 } @@ -332,7 +332,7 @@ Gives a client the same source-/destination-address for each connection. |random| If used then port mapping will be randomized using a random seeded MD5 hash mix using source and destination address and destination port. |fully-random| -If used then port mapping is generated based on a 32-bit pseudo-random algorithm. +If used then port mapping is generated based on a 32-bit pseudo-random algorithm. |============================= .Using NAT statements @@ -359,8 +359,8 @@ add rule nat prerouting tcp dport 22 redirect to :2222 TPROXY STATEMENT ~~~~~~~~~~~~~~~~ Tproxy redirects the packet to a local socket without changing the packet header -in any way. If any of the arguments is missing the data of the incoming packet -is used as parameter. Tproxy matching requires another rule that ensures the +in any way. If any of the arguments is missing the data of the incoming packet +is used as parameter. Tproxy matching requires another rule that ensures the presence of transport protocol header is specified. [verse] @@ -377,7 +377,7 @@ tproxy to : 'port' This syntax can be used in *inet* tables. The *ip/ip6* parameter defines the family the rule will match. The *address* parameter must be of this family. -When only *port* is defined, the address family should not be specified. In +When only *port* is defined, the address family should not be specified. In this case the rule will match for both families. .tproxy attributes @@ -417,7 +417,7 @@ table inet x { FLOW OFFLOAD STATEMENT ~~~~~~~~~~~~~~~~~~~~~~ A flow offload statement allows us to select what flows you want to accelerate -forwarding through layer 3 network stack bypass. You have to specify the +forwarding through layer 3 network stack bypass. You have to specify the flowtable name where you want to offload this flow. *flow offload* @flowtable @@ -442,19 +442,19 @@ for details. Sets queue number, default is 0. | unsigned integer (16 bit) |queue_number_from | -Sets initial queue in the range, if fanout is used. | +Sets initial queue in the range, if fanout is used. | unsigned integer (16 bit) |queue_number_to | -Sets closing queue in the range, if fanout is used. | +Sets closing queue in the range, if fanout is used. | unsigned integer (16 bit) |===================== .queue statement flags [options="header"] |================== -|Flag | Description +|Flag | Description |bypass | -Let packets go through if userspace application cannot back off. Before using +Let packets go through if userspace application cannot back off. Before using this flag, read libnetfilter_queue documentation for performance tuning recommendations. |fanout | Distribute packets between several queues. @@ -498,7 +498,7 @@ dup to ip daddr map { 192.168.7.1 : "eth0", 192.168.7.2 : "eth1" } FWD STATEMENT ~~~~~~~~~~~~~ The fwd statement is used to redirect a raw packet to another interface. It is -only available in the netdev family ingress hook. It is similar to the dup +only available in the netdev family ingress hook. It is similar to the dup statement except that no copy is made. *fwd* to 'device' @@ -507,8 +507,8 @@ SET STATEMENT ~~~~~~~~~~~~~ The set statement is used to dynamically add or update elements in a set from the packet path. The set setname must already exist in the given table and must -have been created with the dynamic flag. Furthermore, these sets must specify -both a maximum set size (to prevent memory exhaustion) and a timeout (so that +have been created with the dynamic flag. Furthermore, these sets must specify +both a maximum set size (to prevent memory exhaustion) and a timeout (so that number of entries in set will not grow indefinitely). The set statement can be used to e.g. create dynamic blacklists. |