vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update policy route docs. Gral structure change, moving forward to a similar structure that firewall docs. Also, new matching options was added to the docs.

Browse Source
This commit is contained in:
Nicolas Fort 2022-09-08 13:23:42 -03:00
parent adbffa6d47
commit 5ce3679ff3
1 changed files with 145 additions and 318 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

463
docs/configuration/policy/route.rst
View File

@ -1,43 +1,59 @@
############ #######################
Route Policy Route and Route6 Policy
############ #######################
Route and IPv6 route policies are defined in this section. This route policies IPv4 route and IPv6 route policies are defined in this section. These route
can then be associated to interfaces. policies can then be associated to interfaces.
************* *********
Configuration Rule-Sets
************* *********
Route A rule-set is a named collection of rules that can be applied to an interface.
===== Each rule is numbered, has an action to apply if the rule is matched, and the
ability to specify the criteria to match. Data packets go through the rules
.. cfgcmd:: set policy route <name> from 1 - 999999, at the first match the action of the rule will be executed.
This command creates a new route policy, identified by <text>.
.. cfgcmd:: set policy route <name> description <text> .. cfgcmd:: set policy route <name> description <text>
.. cfgcmd:: set policy route6 <name> description <text>
Set description for the route policy. Provide a rule-set description.
.. cfgcmd:: set policy route <name> enable-default-log .. cfgcmd:: set policy route <name> enable-default-log
.. cfgcmd:: set policy route6 <name> enable-default-log
Option to log packets hitting default-action. Option to log packets hitting default-action.
.. cfgcmd:: set policy route <name> rule <n> description <text> .. cfgcmd:: set policy route <name> rule <n> description <text>
.. cfgcmd:: set policy route6 <name> rule <n> description <text>
Set description for rule in route policy. Provide a description for each rule.
.. cfgcmd:: set policy route <name> rule <n> action drop .. cfgcmd:: set policy route <name> rule <n> log <enable|disable>
.. cfgcmd:: set policy route6 <name> rule <n> log <enable|disable>
Set rule action to drop. Option to enable or disable log matching rule.
Matching criteria
=================
There are a lot of matching criteria options available, both for
``policy route`` and ``policy route6``. These options are listed
in this section.
.. cfgcmd:: set policy route <name> rule <n> source address
<match_criteria>
.. cfgcmd:: set policy route <name> rule <n> destination address .. cfgcmd:: set policy route <name> rule <n> destination address
<match_criteria> <match_criteria>
.. cfgcmd:: set policy route6 <name> rule <n> source address
<match_criteria>
.. cfgcmd:: set policy route6 <name> rule <n> destination address
<match_criteria>
Set match criteria based on destination address, where <match_criteria> Set match criteria based on source or destination ipv4|ipv6 address, where
could be: <match_criteria> could be:
For ipv4:
* <x.x.x.x>: IP address to match. * <x.x.x.x>: IP address to match.
* <x.x.x.x/x>: Subnet to match. * <x.x.x.x/x>: Subnet to match.
* <x.x.x.x>-<x.x.x.x>: IP range to match. * <x.x.x.x>-<x.x.x.x>: IP range to match.
@ -45,14 +61,30 @@ Route
* !<x.x.x.x/x>: Match everything except the specified subnet. * !<x.x.x.x/x>: Match everything except the specified subnet.
* !<x.x.x.x>-<x.x.x.x>: Match everything except the specified range. * !<x.x.x.x>-<x.x.x.x>: Match everything except the specified range.
And for ipv6:
* <h:h:h:h:h:h:h:h>: IPv6 address to match.
* <h:h:h:h:h:h:h:h/x>: IPv6 prefix to match.
* <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: IPv6 range to match.
* !<h:h:h:h:h:h:h:h>: Match everything except the specified address.
* !<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix.
* !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: Match everything except the
specified range.
.. cfgcmd:: set policy route <name> rule <n> source group
<address-group|domain-group|mac-group|network-group|port-group> <text>
.. cfgcmd:: set policy route <name> rule <n> destination group .. cfgcmd:: set policy route <name> rule <n> destination group
<address-group|network-group|port-group> <text> <address-group|domain-group|mac-group|network-group|port-group> <text>
.. cfgcmd:: set policy route6 <name> rule <n> source group
<address-group|domain-group|mac-group|network-group|port-group> <text>
.. cfgcmd:: set policy route6 <name> rule <n> destination group
<address-group|domain-group|mac-group|network-group|port-group> <text>
Set destination match criteria based on groups, where <text> would be the Set match criteria based on source or destination groups, where <text>
group name/identifier. would be the group name/identifier. Prepend character '!' for inverted
matching criteria.
.. cfgcmd:: set policy route <name> rule <n> destination port .. cfgcmd:: set policy route <name> rule <n> destination port <match_criteria>
<match_criteria> .. cfgcmd:: set policy route6 <name> rule <n> destination port <match_criteria>
Set match criteria based on destination port, where <match_criteria> could Set match criteria based on destination port, where <match_criteria> could
be: be:
@ -66,216 +98,41 @@ Route
'!22,telnet,http,123,1001-1005' '!22,telnet,http,123,1001-1005'
.. cfgcmd:: set policy route <name> rule <n> disable .. cfgcmd:: set policy route <name> rule <n> disable
.. cfgcmd:: set policy route6 <name> rule <n> disable
Option to disable rule. Option to disable rule.
.. cfgcmd:: set policy route <name> rule <n> dscp <text>
.. cfgcmd:: set policy route6 <name> rule <n> dscp <text>
.. cfgcmd:: set policy route <name> rule <n> dscp-exclude <text>
.. cfgcmd:: set policy route6 <name> rule <n> dscp-exclude <text>
Match based on dscp value criteria. Multiple values from 0 to 63
and ranges are supported.
.. cfgcmd:: set policy route <name> rule <n> fragment .. cfgcmd:: set policy route <name> rule <n> fragment
<match-grag|match-non-frag> <match-grag|match-non-frag>
.. cfgcmd:: set policy route6 <name> rule <n> fragment
<match-grag|match-non-frag>
Set IP fragment match, where: Set IP fragment match, where:
* match-frag: Second and further fragments of fragmented packets. * match-frag: Second and further fragments of fragmented packets.
* match-non-frag: Head fragments or unfragmented packets. * match-non-frag: Head fragments or unfragmented packets.
.. cfgcmd:: set policy route <name> rule <n> icmp <code|type|type-name> .. cfgcmd:: set policy route <name> rule <n> icmp <code | type>
.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 <code | type>
Set ICMP match criterias, based on code and/or types. Types could be Match based on icmp|icmpv6 code and type.
referenced by number or by name.
.. cfgcmd:: set policy route <name> rule <n> icmp type-name <text>
.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 type-name <text>
Match based on icmp|icmpv6 type-name criteria. Use tab for information
about what type-name criteria are supported.
.. cfgcmd:: set policy route <name> rule <n> ipsec .. cfgcmd:: set policy route <name> rule <n> ipsec
<match-ipsec|match-none> <match-ipsec|match-none>
Set IPSec inbound match criterias, where:
* match-ipsec: match inbound IPsec packets.
* match-none: match inbound non-IPsec packets.
.. cfgcmd:: set policy route <name> rule <n> limit burst <0-4294967295>
Set maximum number of packets to alow in excess of rate
.. cfgcmd:: set policy route <name> rule <n> limit rate <text>
Set maximum average matching rate. Format for rate: integer/time_unit, where
time_unit could be any one of second, minute, hour or day.For example
1/second implies rule to be matched at an average of once per second.
.. cfgcmd:: set policy route <name> rule <n> log <enable|disable>
Option to enable or disable log matching rule.
.. cfgcmd:: set policy route <name> rule <n> log <text>
Option to log matching rule.
.. cfgcmd:: set policy route <name> rule <n> protocol
<text|0-255|tcp_udp|all|!protocol>
Set protocol to match. Protocol name in /etc/protocols or protocol number,
or "tcp_udp" or "all". Also, protocol could be denied by using !.
.. cfgcmd:: set policy route <name> rule <n> recent <count|time>
<1-255|0-4294967295>
Set parameters for matching recently seen sources. This match could be used
by seeting count (source address seen more than <1-255> times) and/or time
(source address seen in the last <0-4294967295> seconds).
.. cfgcmd:: set policy route <name> rule <n> set dscp <0-63>
Set packet modifications: Packet Differentiated Services Codepoint (DSCP)
.. cfgcmd:: set policy route <name> rule <n> set mark <1-2147483647>
Set packet modifications: Packet marking
.. cfgcmd:: set policy route <name> rule <n> set table <main|1-200>
Set packet modifications: Routing table to forward packet with.
.. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460>
Set packet modifications: Explicitly set TCP Maximum segment size value.
.. cfgcmd:: set policy route <name> rule <n> source address
<match_criteria>
Set match criteria based on source address, where <match_criteria> could be:
* <x.x.x.x>: IP address to match.
* <x.x.x.x/x>: Subnet to match.
* <x.x.x.x>-<x.x.x.x>: IP range to match.
* !<x.x.x.x>: Match everything except the specified address.
* !<x.x.x.x/x>: Match everything except the specified subnet.
* !<x.x.x.x>-<x.x.x.x>: Match everything except the specified range.
.. cfgcmd:: set policy route <name> rule <n> source group
<address-group|network-group|port-group> <text>
Set source match criteria based on groups, where <text> would be the group
name/identifier.
.. cfgcmd:: set policy route <name> rule <n> source port <match_criteria>
Set match criteria based on source port, where <match_criteria> could be:
* <port name>: Named port (any name in /etc/services, e.g., http).
* <1-65535>: Numbered port.
* <start>-<end>: Numbered port range (e.g., 1001-1005).
Multiple source ports can be specified as a comma-separated list. The whole
list can also be "negated" using '!'. For example:
'!22,telnet,http,123,1001-1005'
.. cfgcmd:: set policy route <name> rule <n> state
<established|invalid|new|related> <disable|enable>
Set match criteria based on session state.
.. cfgcmd:: set policy route <name> rule <n> tcp flags <text>
Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK
FIN RST URG PSH ALL. When specifying more than one flag, flags should be
comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match
packets with the SYN flag set, and the ACK, FIN and RST flags unset.
.. cfgcmd:: set policy route <name> rule <n> time monthdays <text>
Set monthdays to match rule on. Format for monthdays: 2,12,21.
To negate add ! at the front eg. !2,12,21
.. cfgcmd:: set policy route <name> rule <n> time startdate <text>
Set date to start matching rule. Format for date: yyyy-mm-dd. To specify
time of date with startdate, append 'T' to date followed by time in 24 hour
notation hh:mm:ss. For eg startdate value of 2009-01-21T13:30:00 refers to
21st Jan 2009 with time 13:30:00.
.. cfgcmd:: set policy route <name> rule <n> time starttime <text>
Set time of day to start matching rule. Format of time: hh:mm:ss using 24
hours notation.
.. cfgcmd:: set policy route <name> rule <n> time stopdate <text>
Set date to stop matching rule. Format for date: yyyy-mm-dd. To specify time
of date with stopdate, append 'T' to date followed by time in 24 hour
notation hh:mm:ss. For eg startdate value of 2009-01-21T13:30:00 refers to
21st Jan 2009 with time 13:30:00.
.. cfgcmd:: set policy route <name> rule <n> time stoptime <text>
Set time of day to stop matching rule. Format of time: hh:mm:ss using 24
hours notation.
.. cfgcmd:: set policy route <name> rule <n> time utc
Interpret times for startdate, stopdate, starttime and stoptime to be UTC.
.. cfgcmd:: set policy route <name> rule <n> time weekdays
Weekdays to match rule on. Format for weekdays: Mon,Thu,Sat. To negate add !
at the front eg. !Mon,Thu,Sat.
IPv6 Route
==========
.. cfgcmd:: set policy route6 <name>
This command creates a new IPv6 route policy, identified by <text>.
.. cfgcmd:: set policy route6 <name> description <text>
Set description for the IPv6 route policy.
.. cfgcmd:: set policy route6 <name> enable-default-log
Option to log packets hitting default-action.
.. cfgcmd:: set policy route6 <name> rule <n> action drop
Set rule action to drop.
.. cfgcmd:: set policy route6 <name> rule <n> description <text>
Set description for rule in IPv6 route policy.
.. cfgcmd:: set policy route6 <name> rule <n> destination address
<match_criteria>
Set match criteria based on destination IPv6 address, where <match_criteria>
could be:
* <h:h:h:h:h:h:h:h>: IPv6 address to match.
* <h:h:h:h:h:h:h:h/x>: IPv6 prefix to match.
* <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: IPv6 range to match.
* !<h:h:h:h:h:h:h:h>: Match everything except the specified address.
* !<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix.
* !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: Match everything except the
specified range.
.. cfgcmd:: set policy route6 <name> rule <n> destination port <match_criteria>
Set match criteria based on destination port, where <match_criteria> could
be:
* <port name>: Named port (any name in /etc/services, e.g., http).
* <1-65535>: Numbered port.
* <start>-<end>: Numbered port range (e.g., 1001-1005).
Multiple destination ports can be specified as a comma-separated list. The
whole list can also be "negated" using '!'. For example:
'!22,telnet,http,123,1001-1005'.
.. cfgcmd:: set policy route6 <name> rule <n> disable
Option to disable rule.
.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 type <icmpv6_typ>
Set ICMPv6 match criterias, based on ICMPv6 type/code name.
.. cfgcmd:: set policy route6 <name> rule <n> ipsec .. cfgcmd:: set policy route6 <name> rule <n> ipsec
<match-ipsec|match-none> <match-ipsec|match-none>
@ -284,96 +141,45 @@ IPv6 Route
* match-ipsec: match inbound IPsec packets. * match-ipsec: match inbound IPsec packets.
* match-none: match inbound non-IPsec packets. * match-none: match inbound non-IPsec packets.
.. cfgcmd:: set policy route6 <name> rule <n> limit burst .. cfgcmd:: set policy route <name> rule <n> limit burst <0-4294967295>
<0-4294967295> .. cfgcmd:: set policy route6 <name> rule <n> limit burst <0-4294967295>
Set maximum number of packets to alow in excess of rate Set maximum number of packets to alow in excess of rate.
.. cfgcmd:: set policy route <name> rule <n> limit rate <text>
.. cfgcmd:: set policy route6 <name> rule <n> limit rate <text> .. cfgcmd:: set policy route6 <name> rule <n> limit rate <text>
Set maximum average matching rate. Format for rate: integer/time_unit, where Set maximum average matching rate. Format for rate: integer/time_unit, where
time_unit could be any one of second, minute, hour or day.For example time_unit could be any one of second, minute, hour or day.For example
1/second implies rule to be matched at an average of once per second. 1/second implies rule to be matched at an average of once per second.
.. cfgcmd:: set policy route6 <name> rule <n> log <enable|disable> .. cfgcmd:: set policy route <name> rule <n> protocol
<text | 0-255 | tcp_udp | all >
Option to enable or disable log matching rule.
.. cfgcmd:: set policy route6 <name> rule <n> log <text>
Option to log matching rule.
.. cfgcmd:: set policy route6 <name> rule <n> protocol .. cfgcmd:: set policy route6 <name> rule <n> protocol
<text|0-255|tcp_udp|all|!protocol> <text | 0-255 | tcp_udp | all >
Set IPv6 protocol to match. IPv6 protocol name from /etc/protocols or Match a protocol criteria. A protocol number or a name which is defined in:
protocol number, or "tcp_udp" or "all". Also, protocol could be denied by ``/etc/protocols``. Special names are ``all`` for all protocols and
using !. ``tcp_udp`` for tcp and udp based packets. The ``!`` negates the selected
protocol.
.. cfgcmd:: set policy route6 <name> rule <n> recent <count|time> .. cfgcmd:: set policy route <name> rule <n> recent count <1-255>
<1-255|0-4294967295> .. cfgcmd:: set policy route6 <name> rule <n> recent count <1-255>
.. cfgcmd:: set policy route <name> rule <n> recent time <1-4294967295>
.. cfgcmd:: set policy route6 <name> rule <n> recent time <1-4294967295>
Set parameters for matching recently seen sources. This match could be used Set parameters for matching recently seen sources. This match could be used
by seeting count (source address seen more than <1-255> times) and/or time by seeting count (source address seen more than <1-255> times) and/or time
(source address seen in the last <0-4294967295> seconds). (source address seen in the last <0-4294967295> seconds).
.. cfgcmd:: set policy route6 <name> rule <n> set dscp <0-63> .. cfgcmd:: set policy route <name> rule <n> state
<established | invalid | new | related>
Set packet modifications: Packet Differentiated Services Codepoint (DSCP)
.. cfgcmd:: set policy route6 <name> rule <n> set mark <1-2147483647>
Set packet modifications: Packet marking.
.. cfgcmd:: set policy route6 <name> rule <n> set table <main|1-200>
Set packet modifications: Routing table to forward packet with.
.. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss
<pmtu|500-1460>
Set packet modifications: pmtu option automatically set to Path Maximum
Transfer Unit minus 60 bytes. Otherwise, expliicitly set TCP MSS value from
500 to 1460.
.. cfgcmd:: set policy route6 <name> rule <n> source address
<match_criteria>
Set match criteria based on IPv6 source address, where <match_criteria>
could be:
* <h:h:h:h:h:h:h:h>: IPv6 address to match
* <h:h:h:h:h:h:h:h/x>: IPv6 prefix to match
* <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: IPv6 range to match
* !<h:h:h:h:h:h:h:h>: Match everything except the specified address
* !<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix
* !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: Match everything except the
specified range
.. cfgcmd:: set policy route6 <name> rule <n> source mac-address
<MAC_address|!MAC_address>
Set source match criteria based on MAC address. Declare specific MAC address
to match, or match everything except the specified MAC.
.. cfgcmd:: set policy route6 <name> rule <n> source port
<match_criteria>
Set match criteria based on source port, where <match_criteria> could be:
* <port name>: Named port (any name in /etc/services, e.g., http).
* <1-65535>: Numbered port.
* <start>-<end>: Numbered port range (e.g., 1001-1005).
Multiple source ports can be specified as a comma-separated list. The whole
list can also be "negated" using '!'. For example:
'!22,telnet,http,123,1001-1005'.
.. cfgcmd:: set policy route6 <name> rule <n> state .. cfgcmd:: set policy route6 <name> rule <n> state
<established|invalid|new|related> <disable|enable> <established | invalid | new | related>
Set match criteria based on session state. Set match criteria based on session state.
.. cfgcmd:: set policy route <name> rule <n> tcp flags <text>
.. cfgcmd:: set policy route6 <name> rule <n> tcp flags <text> .. cfgcmd:: set policy route6 <name> rule <n> tcp flags <text>
Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK
@ -381,40 +187,61 @@ IPv6 Route
comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match
packets with the SYN flag set, and the ACK, FIN and RST flags unset. packets with the SYN flag set, and the ACK, FIN and RST flags unset.
.. cfgcmd:: set policy route <name> rule <n> time monthdays <text>
.. cfgcmd:: set policy route6 <name> rule <n> time monthdays <text> .. cfgcmd:: set policy route6 <name> rule <n> time monthdays <text>
.. cfgcmd:: set policy route <name> rule <n> time startdate <text>
Set monthdays to match rule on. Format for monthdays: 2,12,21.
To negate add ! at the front eg. !2,12,21
.. cfgcmd:: set policy route6 <name> rule <n> time startdate <text> .. cfgcmd:: set policy route6 <name> rule <n> time startdate <text>
.. cfgcmd:: set policy route <name> rule <n> time starttime <text>
Set date to start matching rule. Format for date: yyyy-mm-dd. To specify
time of date with startdate, append 'T' to date followed by time in 24 hour
notation hh:mm:ss. For eg startdate value of 2009-01-21T13:30:00 refers to
21st Jan 2009 with time 13:30:00.
.. cfgcmd:: set policy route6 <name> rule <n> time starttime <text> .. cfgcmd:: set policy route6 <name> rule <n> time starttime <text>
.. cfgcmd:: set policy route <name> rule <n> time stopdate <text>
Set time of day to start matching rule. Format of time: hh:mm:ss using 24
hours notation.
.. cfgcmd:: set policy route6 <name> rule <n> time stopdate <text> .. cfgcmd:: set policy route6 <name> rule <n> time stopdate <text>
.. cfgcmd:: set policy route <name> rule <n> time stoptime <text>
Set date to stop matching rule. Format for date: yyyy-mm-dd. To specify time
of date with stopdate, append 'T' to date followed by time in 24 hour
notation hh:mm:ss. For eg startdate value of 2009-01-21T13:30:00 refers to
21st Jan 2009 with time 13:30:00.
.. cfgcmd:: set policy route6 <name> rule <n> time stoptime <text> .. cfgcmd:: set policy route6 <name> rule <n> time stoptime <text>
.. cfgcmd:: set policy route <name> rule <n> time weekdays <text>
Set time of day to stop matching rule. Format of time: hh:mm:ss using 24 .. cfgcmd:: set policy route6 <name> rule <n> time weekdays <text>
hours notation. .. cfgcmd:: set policy route <name> rule <n> time utc
.. cfgcmd:: set policy route6 <name> rule <n> time utc .. cfgcmd:: set policy route6 <name> rule <n> time utc
Interpret times for startdate, stopdate, starttime and stoptime to be UTC. Time to match the defined rule.
.. cfgcmd:: set policy route6 <name> rule <n> time weekdays .. cfgcmd:: set policy route rule <n> ttl <eq | gt | lt> <0-255>
Weekdays to match rule on. Format for weekdays: Mon,Thu,Sat. To negate add ! Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for
at the front eg. !Mon,Thu,Sat. 'greater than', and 'lt' stands for 'less than'.
.. cfgcmd:: set policy route6 rule <n> hop-limit <eq | gt | lt> <0-255>
Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for
'greater than', and 'lt' stands for 'less than'.
Actions
=======
When mathcing all patterns defined in a rule, then different actions can
be made. This includes droping the packet, modifying certain data, or
setting a different routing table.
.. cfgcmd:: set policy route <name> rule <n> action drop
.. cfgcmd:: set policy route6 <name> rule <n> action drop
Set rule action to drop.
.. cfgcmd:: set policy route <name> rule <n> set dscp <0-63>
.. cfgcmd:: set policy route6 <name> rule <n> set dscp <0-63>
Set packet modifications: Packet Differentiated Services Codepoint (DSCP)
.. cfgcmd:: set policy route <name> rule <n> set mark <1-2147483647>
.. cfgcmd:: set policy route6 <name> rule <n> set mark <1-2147483647>
Set packet modifications: Packet marking
.. cfgcmd:: set policy route <name> rule <n> set table <main | 1-200>
.. cfgcmd:: set policy route6 <name> rule <n> set table <main | 1-200>
Set packet modifications: Routing table to forward packet with.
.. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460>
.. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss <500-1460>
Set packet modifications: Explicitly set TCP Maximum segment size value.