VPF Filter Rules¶
VPF filter rules are contained within rulesets. To create a ruleset, start in
config
mode and then use the vpf filter ruleset <name>
command to create
a filter ruleset with the name <name>
and enter
config-vpf-filter-ruleset
mode.
See also
VPF rulesets must be associated with an interface before they are active, see Interface Options for details.
The following commands are available within config-vpf-filter-ruleset
mode:
- description <text>:
Adds an optional description to the ruleset describing its purpose.
- rule <seq>:
Creates a new rule with the given sequence number and enters
config-vpf-filter-rule
mode.VPF processes rules in an order determined by the sequence number of each rule.
A common practice is to leave a gap between rule numbers when starting in case rules must be rearranged at a later date. Increasing the sequence number by 10 or 100 for each rule is a common tactic (10, 20, 30, 40, etc.).
Filter Rule Configuration¶
VPF rules contain a variety of options to control how it matches packets and what it does with them afterward.
These are all configured from within config-vpf-filter-rule
mode.
Description¶
Each rule can have its own description so the ruleset can be self-documenting.
- description <text>:
Adds an optional test description to this rule to explain its purpose.
Processing Order¶
On TNSR, VPF rules operate in a “first match wins” manner, but this can be changed on a per-rule basis. Most administrators find rules matched in this way easier to understand, but ultimately the difference in behavior is a matter of preference.
- tentative:
Setting this option on a rule marks the match as tentative if a packet matches this rule. This means that VPF will use this rule only if there are no later rules which also match the packet.
In effect using this option changes to a “last match wins” style.
Rule Action¶
These options control what VPF will do with a packet that matches the rule.
The default action if no others are present is to silently drop the packet.
- pass:
Passes the packet and, if the rule is stateful, creates a connection state table entry.
- return-icmp:
Drops the packet and if the packet was using UDP, VPF sends an ICMP “unreachable” error message back to the source informing the peer that the destination was unreachable.
- return-rst:
Drops the packet and if the packet was using TCP, VPF sends a TCP RST message back to the source informing the peer that the connection has been reset.
Using return-icmp
or return-rst
is less secure as the peer can use these
responses to determine that the packet was blocked. Therefore, the peer does
need to not wait for a response that may never come. While it is less secure, it
is also more friendly to clients, so it is common to respond in this way on
internal interfaces but not on untrusted or public-facing interfaces.
Direction¶
Controls the direction in which this rule matches packets.
- direction in:
Matches packets entering an interface (ingress). On external interfaces, such as WANs or VPNs, these are packets arriving at TNSR from hosts on the Internet or VPN going to local destinations. On internal interfaces, such as LANs, these are packets arriving at TNSR from local hosts going to other remote or local destinations.
- direction out:
Matches packets exiting an interface (egress). On external interfaces, such as WANs or VPNs, these are packets leaving TNSR from local hosts going to remote destinations on the Internet or VPNs. On internal interfaces, such as LANs, these are packets leaving TNSR coming from remote hosts.
- direction both:
Matches packets both entering and exiting an interface.
- dest-route-table <route-table>:
Configures an alternate routing table (VRF) for an inbound rule. VPF will use this VRF when determining how to route an inbound packet.
Note
Interfaces can only have one ruleset, so that ruleset must include inbound and outbound rules.
When VPF is active on an interface, any traffic not passed explicitly is blocked. This includes traffic in both directions.
State Tracking¶
A powerful feature of VPF is its ability to track connection states and pass packets associated with known connections to pass without inspecting the ruleset for every packet. This works on any protocol, even those which are technically stateless.
Not only does this allow for much simpler rulesets by only needing to pass in one direction, it also speeds up processing of packets significantly.
- stateful:
When this option is present on a rule, the first packet of a connection creates a new entry in the state table. Subsequent packets for the same connection are allowed through provided the packets match the corresponding entry in the state table.
Each state will consume a small quantity of resources to track a connection, so there is some memory overhead involved. For heavy duty workloads, it can be faster to forego stateful inspection if the connections are predictable and can be filtered with a small ruleset.
See also
There are Runtime Options to control timeouts for various connection states, and that section of the documentation also describes how connections transition through various connection states.
Address Family¶
VPF filter rules can operate on IPv4 packets and IPv6 packets, as specified in this command:
- ip-version (ipv4|ipv6):
Restrict this rule to either IPv4 packets or IPv6 packets.
When unset, the rule can match both IPv4 and IPv6.
Protocol Options¶
Rules can match one or more protocol values, and TCP matches can further be restricted to only packets with specific flags.
- protocol <values>:
Specifies protocols to allow, separated by spaces. Protocol values can be given by name (in lowercase) or protocol number. Packets can match any protocol in this list.
When unset, packets of any protocol will match the rule.
Note
If the
protocol
is unset and the rule also contains afrom
orto
value to match aport
, VPF assumes the protocol to be either TCP or UDP.- icmp (code|type) <value>:
Matches only specific ICMP codes and subtypes by numeric value.
- tcp flags value <flag-name> [<flag-name> […]]:
Configures a list of TCP Flags which must ALL be set to match a packet.
- tcp flags mask <flag-name> [<flag-name> […]]:
Configures a list of TCP flags VPF inspects when matching a packet.
If a flag is listed in the
mask
but not thevalue
then it must not be set in a packet to match.At a minimum this list must include the same set of flags listed in
tcp flags value
or it will never match.
Note
VPF assumes a default TCP flags value of syn
and a default TCP flags mask
of fin syn rst ack
. This means that for a packet to match this rule, it
must have the syn
flag set and all of fin rst ack
must be
unset.
Source and Destination Address Matching¶
VPF supports a variety of ways to match the source and destination addresses on packets.
The from
commands match the source address on packets, while the to
commands match destination addresses. Both sets of commands support the same
types of address matching mechanisms.
- ifaddrs <if-name>:
Matches any IP addresses configured on the given TNSR interface. This includes static IP addresses, VRRP addresses, and those configured via DHCP.
Note
This only refers to the IP addresses on the TNSR interface, not the entire subnet or prefix on that interface.
- inverted:
Inverts the match, matching any packet except those with the given source or destination specification.
- port <start-port> [<end-port>]:
Matches a TCP or UDP packet with the given port or continuous range of ports.
Note
Using
port
on a rule implies a protocol of TCP and/or UDP as they are the only protocols which utilize port values in VPF. If aport
is set but the protocol is not explicitly configured on the rule, then VPF assumes aprotocol
value oftcp udp
.- (ipv4-prefix|ipv6-prefix) <ip-prefix>:
Matches a specific IP prefix of the given address family. A prefix is composed of either an IPv4 or IPv6 address and a CIDR mask/prefix length. For example,
10.0.0.0/8
orff00::/8
.To define a single host, use a
/32
CIDR for IPv4 or a/128
prefix length for IPv6.Warning
When defining a network, use an appropriate network boundary as the starting address. For example, to define a prefix for an IPv4 network including the address
10.1.2.1/24
, the prefix must be defined using the network address of that subnet,10.1.2.0/24
.- table <name>:
Matches based on the contents of prefixes contained in an VPF table.
Note
If a filter rule does not contain a from
and/or to
entry to filter
by address, then VPF will match any
address. Passing an all-zeroes
prefix (0.0.0.0/0
or ::/0
) will also match any address.