Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/netbsd-8]: src/usr.sbin/npf/npfctl Pull up the following, requested by m...
details: https://anonhg.NetBSD.org/src/rev/4d714fcd1bf5
branches: netbsd-8
changeset: 852011:4d714fcd1bf5
user: martin <martin%NetBSD.org@localhost>
date: Thu Sep 27 14:33:30 2018 +0000
description:
Pull up the following, requested by maxv in ticket #1030:
usr.sbin/npf/npfctl/npf.conf.5 1.71-1.79 (patch)
npf.conf(5): fix some of the previous incorrect or inaccurate changes.
The TCP flags option is not only for the stateful tracking. Dynamic NAT
implies NAPT; algorithms, at least for now, are for static NAT mappings.
Mention that ALG ICMP is also for traceroute behind NAT; also mention
"MSS clamping" (some users might search for this term, so keeping the
terminology is helpful).
--------------------------------------------------------------------------------
Remove superfluous Pp.
--------------------------------------------------------------------------------
Be clearer about the difference between static vs dynamic interface list,
and slightly improve wording.
My understanding is that when none of inet4/inet6/ifaddrs is passed, NPF
assumes ifaddrs.
--------------------------------------------------------------------------------
New sentence, new line. Use Fn for functions.
--------------------------------------------------------------------------------
Fix the "Interfaces" section, I understood wrong. Talk about inference,
because it was not mentioned before, and it plays an important role.
Discussed with rmind. Probably not the last pass.
--------------------------------------------------------------------------------
Switch back to tabs, it was nicer this way.
--------------------------------------------------------------------------------
Wrap long lines, so that nothing overflows.
--------------------------------------------------------------------------------
Improve markup.
--------------------------------------------------------------------------------
According to the grammar and examples the static table is defined with
"file" keyword, not "static".
diffstat:
usr.sbin/npf/npfctl/npf.conf.5 | 420 ++++++++++++++++++++++++----------------
1 files changed, 251 insertions(+), 169 deletions(-)
diffs (truncated from 618 to 300 lines):
diff -r 2de11016b6ff -r 4d714fcd1bf5 usr.sbin/npf/npfctl/npf.conf.5
--- a/usr.sbin/npf/npfctl/npf.conf.5 Sun Sep 23 18:04:52 2018 +0000
+++ b/usr.sbin/npf/npfctl/npf.conf.5 Thu Sep 27 14:33:30 2018 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: npf.conf.5,v 1.48.4.1 2018/09/01 06:19:12 martin Exp $
+.\" $NetBSD: npf.conf.5,v 1.48.4.2 2018/09/27 14:33:30 martin Exp $
.\"
.\" Copyright (c) 2009-2017 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd August 31, 2018
+.Dd September 21, 2018
.Dt NPF.CONF 5
.Os
.Sh NAME
@@ -46,7 +46,8 @@
There are multiple structural elements that
.Nm
may contain, such as:
-.Bl -bullet -offset indent
+.Pp
+.Bl -bullet -offset indent -compact
.It
variables
.It
@@ -64,86 +65,123 @@
.El
.Sh SYNTAX
.Ss Variables
-Variables are specified using the dollar ($) sign, which is used for both
+Variables are specified using the dollar
+.Pq Li $
+sign, which is used for both
definition and referencing of a variable.
Variables are defined by assigning a value to them as follows:
-.Bd -literal
-$var1 = 10.0.0.1
-.Ed
+.Pp
+.Dl $var1 = 10.0.0.1
.Pp
A variable may also be defined as a set:
-.Bd -literal
-$var2 = { 10.0.0.1, 10.0.0.2 }
-.Ed
+.Pp
+.Dl $var2 = { 10.0.0.1, 10.0.0.2 }
.Pp
Common variable definitions are for IP addresses, networks, ports,
and interfaces.
.Ss Tables
Tables are specified using a name between angle brackets
-< and >.
+.Sq Li <
+and
+.Sq Li > .
The following is an example of table definition:
-.Bd -literal
-table <black> type hash dynamic
+.Pp
+.Dl table <black> type hash dynamic
.Pp
-.Ed
-Currently, tables support three data storage types: "hash", "tree", or "cdb".
-Tables can also be set as containing "dynamic" or "static" data i.e. loaded from
- a specified file.
-Tables of type "hash" and "cdb" can only contain IP addresses.
-Only static data can be used with a storage type of "cdb".
+Currently, tables support three data storage types:
+.Cm hash,
+.Cm tree ,
+or
+.Cm cdb .
+Tables can also be set as containing
+.Cm dynamic
+data or static
+.Cm file Ar filename
+data loaded from a specified file.
+Tables of type
+.Dq hash
+and
+.Dq cdb
+can only contain IP addresses.
+Only static data can be used with a storage type of
+.Dq cdb .
.Pp
The specified file should contain a list of IP addresses and/or networks in the
-form of:
-.Bd -literal
-10.0.0.0/24
-10.1.1.1
-.Ed
+form of
+.Li 10.1.1.1
+or
+.Li 10.0.0.0/24
.Ss Interfaces
-Interfaces can be specified as the values of the variables:
-.Bd -literal
-$pub_if_list = { inet4(wm0), inet4(wm1) }
+In NPF, an interface can be referenced directly by using its name, or can be
+passed to an extraction function which will return a list of IP addresses
+configured on the actual associated interface.
+.Pp
+It is legal to pass an extracted list from an interface in keywords where
+NPF would expect instead a direct reference to said interface.
+In this case, NPF infers a direct reference to the interface, and does not
+consider the list.
+.Pp
+There are two types of IP address lists.
+With a static list, NPF will capture the interface addresses on configuration
+load, whereas with a dynamic list NPF will capture the runtime list of
+addresses, reflecting any changes to the interface, including the attach and
+detach.
+Note that with a dynamic list, bringing the interface down has no effect,
+all addresses will remain present.
+.Pp
+Three functions exist, to extract addresses from an interface with a chosen
+list type and IP address type:
+.Bl -tag -width "Fn ifaddrs interface" -offset indent
+.It Fn inet4 interface
+Static list. IPv4 addresses.
+.It Fn inet6 interface
+Static list. IPv6 addresses.
+.It Fn ifaddrs interface
+Dynamic list. Both IPv4 and IPv6.
+The
+.Cm family
+keyword of a filtering rule can be used in combination to explicitly select
+an IP address type.
+.El
+.Pp
+Example of configuration:
+.Bd -literal -offset indent
+$var1 = inet4(wm0)
+$var2 = ifaddrs(wm0)
+group default {
+ block in on wm0 all # rule 1
+ block in on $var1 all # rule 2
+ block in on inet4(wm0) all # rule 3
+ pass in on inet6(wm0) from $var2 # rule 4
+ pass in on wm0 from ifaddrs(wm0) # rule 5
+}
.Ed
.Pp
-In the context of filtering, an interface provides a list of all its IP
-addresses, both IPv4 and IPv6.
-Specific addresses configured on an interface can also be selected by family,
-e.g.:
-.Bd -literal
-$pub_if4 = inet4(wm0)
-$pub_if46 = { inet4(wm0), inet6(wm0) }
-.Ed
-.Pp
-In the above examples, NPF will statically capture the interface
-addresses on configuration load.
-.Pp
-The following can be used for dynamic handling of the interface addresses:
-.Bd -literal
-$pub_if = ifaddrs(wm0)
-.Ed
-.Pp
-In this case, the expression will represent the runtime list of addresses,
-reflecting any changes to the interface, including the attach and detach.
-Marking the interface as ``down'' has no effect, i.e. all addresses will
-remain present.
-.Pp
-A dynamic address list represents both the IPv4 and IPv6 addresses configured on
-an interface.
-The
-.Cd family
-keyword can be used in combination of a filtering rule to be explicit.
+In the above example,
+.Li $var1
+is the static list of IPv4 addresses configured
+on wm0, and
+.Li $var2
+is the dynamic list of all the IPv4 and IPv6 addresses configured on wm0.
+The first three rules are equivalent, because with the
+.Li Ic block Ar "..." Cm on Li < Ns Ar interface Ns Li >
+syntax, NPF expects a direct reference to an interface, and therefore does
+not consider the extraction functions.
+The fourth and fifth rules are equivalent, for the same reason.
.Ss Groups
NPF requires that all rules be defined within groups.
Groups can be thought of as higher level rules which can contain subrules.
Groups may have the following options: name, interface, and direction.
Packets matching group criteria are passed to the ruleset of that group.
If a packet does not match any group, it is passed to the
-.Cd default group .
+.Dv default
+group.
The
-.Cd default group
-must always be defined.
+.Dv default
+group must always be defined.
.Pp
Example of configuration:
-.Bd -literal
+.Bd -literal -offset indent
group "my-name" in on wm0 {
# List of rules, for packets received on wm0
}
@@ -153,68 +191,103 @@
.Ed
.Ss Rules
With a rule statement NPF is instructed to
-.Cd pass
+.Ic pass
or
-.Cd block
+.Ic block
a packet depending on packet header information, transit direction and
the interface it arrived on, either immediately upon match or using the
last match.
.Pp
If a packet matches a rule which has the
-.Cd final
+.Cm final
option set, this rule is considered the last matching rule, and
evaluation of subsequent rules is skipped.
Otherwise, the last matching rule is used.
.Pp
-A rule can also instruct NPF to create an entry in the state table
-when passing the packet, to notify the sender when blocking it, and
-to apply a procedure to the packet (e.g. "log") in either case.
+The
+.Cm proto
+keyword can be used to filter packets by layer 4 protocol (TCP, UDP, ICMP
+or other).
+Its parameter should be a protocol number or its symbolic name,
+as specified in the
+.Pa /etc/protocols
+file.
+This keyword can additionally have protocol-specific options, such as
+.Cm flags .
+.Pp
+The
+.Cd flags
+keyword can be used to match the packets against specific TCP flags,
+according to the following syntax:
+.Pp
+.Dl Ic proto Cm tcp flags Ar match Ns Li [/ Ns Ar mask Ns Li ]
+.Pp
+Where
+.Ar match
+is the set of TCP flags to be matched, out of the
+.Ar mask
+set, both sets being represented as a string combination of:
+.Sq Cm S
+(SYN),
+.Sq Cm A
+(ACK),
+.Sq Cm F
+(FIN), and
+.Sq Cm R
+(RST).
+The flags that are not present in
+.Ar mask
+are ignored.
.Pp
To notify the sender of a blocking decision, three
-.Cd return
+.Cm return
options can be used in conjunction with a
-.Cd block
+.Ic block
rule:
-.Bl -tag -width Xreturn-icmpXX -offset indent
-.It return
-Behaves as return-rst or return-icmp, depending on whether the packet
-being blocked is TCP or UDP.
-.It return-rst
+.Bl -tag -width "Cm return-icmp" -offset indent
+.It Cm return
+Behaves as
+.Cm return-rst
+or
+.Cm return-icmp ,
+depending on whether the packet being blocked is TCP or UDP.
+.It Cm return-rst
Return a TCP RST message, when the packet being blocked is a TCP packet.
Applies to IPv4 and IPv6.
-.It return-icmp
+.It Cm return-icmp
Return an ICMP UNREACHABLE message, when the packet being blocked is a UDP packet.
Applies to IPv4 and IPv6.
.El
.Pp
-A "fully-featured" rule would for example be:
-.Bd -literal
-pass stateful in final family inet4 proto tcp flags S/SA \\
- from $source port $sport to $dest port $dport apply "someproc"
-.Ed
+Further packet specification at present is limited to TCP and UDP
+understanding source and destination ports, and ICMP and IPv6-ICMP
Home |
Main Index |
Thread Index |
Old Index