PBR

PBR is Policy Based Routing, which means forwarding based on packet fields other than solely the destination IP address. This implementation currently works only on Linux. Note that some functionality (VLAN matching, packet mangling) is not supported by the default Linux kernel dataplane provider.

Starting PBR

Configuration for the daemon should be saved in the FRR integrated configuration file located in /etc/frr/frr.conf, see Integrated Config File for more information on system configuration.

Prior versions of FRR supported reading and writing per-daemon config files; however, with the introduction of the centralized management daemon mgmtd this could no longer be supported.

In order to allow for an orderly transition from per-daemon config files to the integrated config file, FRR daemons will continue to try and read their specific per-daemon configuration file as before. Additionally the config can still be loaded directly using the -f or --config-file CLI options; however, these files will not be updated when the configuration is written (e.g., with the write mem command).

Warning

Per-daemon files will no longer be updated when the user issues a write memory command. Therefore these per-daemon config files should only be used as a mechanism for transitioning to the integrated config, and then removed.

PBR supports all the common FRR daemon start options, which are documented elsewhere.

PBR Nexthop Groups

A nexthop group is a list of ECMP nexthops used to forward packets when a pbr-map is matched. For details on specifying a nexthop group in the CLI, see the nexthop-groups section.

Showing Nexthop Group Information

show pbr nexthop-groups [NAME] [json]

Display information on a PBR nexthop-group. If NAME is omitted, all nexthop groups are shown. Setting json will provide the same information in an array of objects that adhere to the schema below:

Key	Description	Type
id	Unique ID	Integer
name	Name of this group	String
valid	Is this group well-formed?	Boolean
installed	… and is it installed?	Boolean
nexthops	Nexthops within this group	Array

Each element within nexthops describes a single target within this group, and its structure is described by the JSON below:

Key	Description	Type
nexthop	Name of this nexthop	String
valid	Is this nexthop well-formed?	Boolean

PBR Maps

PBR maps are a way to specify a set of rules that are applied to packets received on individual interfaces. If a received packet matches a rule, the rule’s nexthop-group or nexthop is used to forward it; any other actions specified in the rule are also applied to the packet.

pbr-map NAME seq (1-700)

Create a pbr-map rule with map NAME and specified sequence number. This command puts the CLI into a new submode for pbr-map rule specification. To exit this submode, type exit or end.

match src-ip PREFIX

Match the packet’s source IP address.

This command accepts both v4 and v6 prefixes.

match dst-ip PREFIX

Match the packet’s destination IP address.

This command accepts both v4 and v6 prefixes.

match src-port (1-65535)

Match the packet’s UDP or TCP source port.

match dst-port (1-65535)

Match the packet’s UDP or TCP destination port.

match ip-protocol PROTOCOL

Match the packet’s IP protocol.

Protocol names are queried from the protocols database (/etc/protocols; see man 5 protocols and man 3 getprotobyname).

match mark (1-4294967295)

Match the packet’s meta-information mark. The mark value is attached to the packet by the kernel/dataplane and is platform-specific. Currently, this field is supported only on linux and corresponds to the underlying ip rule …. fwmark XXXX command.

match dscp (DSCP|0-63)

Match the packet’s IP differentiated services code point (DSCP). The specified DSCP may also be a standard name for a differentiated service code point such as cs0 or af11.

You may only specify one dscp per route map rule; to match on multiple dscp values you will need to create several rules, one for each value.

match ecn (0-3)

Match the packet’s IP explicit congestion notification (ECN) field.

match pcp (0-7)

Match the packet’s 802.1Q Priority Code Point. Zero is the default (nominally, “best effort”). The Linux kernel dataplane provider does not currently support matching PCPs, so this field will be ignored unless other dataplane providers are used.

match vlan (1-4094)

Match the packet’s VLAN (802.1Q) identifier. Note that VLAN IDs 0 and 4095 are reserved. The Linux kernel dataplane provider does not currently support VLAN-matching facilities, so this field will be ignored unless other dataplane providers are used.

match vlan (tagged|untagged|untagged-or-zero)

Match packets according to whether or not they have a VLAN tag. Use untagged-or-zero to also match packets with either no VLAN tag or with the reserved VLAN ID of 0 (indicating an untagged frame that includes other 802.1Q fields). The Linux kernel dataplane provider does not currently support VLAN-matching facilities, so this field will be ignored unless other dataplane providers are used.

set nexthop-group NAME

Action: forward the packet using nexthop-group NAME.

set nexthop [A.B.C.D|X:X::X:XX|blackhole] [interface] [nexthop-vrf NAME]

Action: forward the packet using the specified single nexthop. If blackhole, packets will be sent to a blackhole route and dropped.

set vrf unchanged|NAME

Action: If set to unchanged, the rule will use the vrf table the interface is in as its lookup. If set to NAME, the rule will use that vrf table as its lookup.

Not supported with NETNS VRF backend.

set queue-id (1-65535)

Action: set the egress port queue identifier. The Linux Kernel dataplane provider does not currently support packet mangling, so this field will be ignored unless another dataplane provider is used.

set pcp (0-7)

Action: set the 802.1Q priority code point (PCP). A PCP of zero is the default (nominally, “best effort”). The Linux Kernel dataplane provider does not currently support packet mangling, so this field will be ignored unless another dataplane provider is used.

set vlan (1-4094)

Action: set the VLAN tag. Identifiers 0 and 4095 are reserved. The Linux Kernel dataplane provider does not currently support packet mangling, so this field will be ignored unless another dataplane provider is used.

strip vlan

Action: strip inner vlan tags. The Linux Kernel dataplane provider does not currently support packet mangling, so this field will be ignored unless another dataplane provider is used. It is invalid to specify both a strip and set vlan action.

set src-ip [A.B.C.D/M|X:X::X:X/M]

Action: Set the source IP address of matched packets, possibly using a mask M. The Linux Kernel dataplane provider does not currently support packet mangling, so this field will be ignored unless another dataplane provider is used.

set dst-ip [A.B.C.D/M|X:X::X:X/M]

Action: set the destination IP address of matched packets, possibly using a mask M. The Linux Kernel dataplane provider does not currently support packet mangling, so this field will be ignored unless another dataplane provider is used.

set src-port (1-65535)

Action: set the source port of matched packets. Note that this action only makes sense with layer 4 protocols that use ports, such as TCP, UDP, and SCTP. The Linux Kernel dataplane provider does not currently support packet mangling, so this field will be ignored unless another dataplane provider is used.

set dst-port (1-65535)

Action: set the destination port of matched packets. Note that this action only makes sense with layer 4 protocols that use ports, such as TCP, UDP, and SCTP. The Linux Kernel dataplane provider does not currently support packet mangling, so this field will be ignored unless another dataplane provider is used.

set dscp DSCP

Action: set the differentiated services code point (DSCP) of matched packets. The Linux Kernel dataplane provider does not currently support this action, so this field will be ignored unless another dataplane provider is used.

set ecn (0-3)

Action: set the explicit congestion notification (ECN) of matched packets. The Linux Kernel dataplane provider does not currently support this action, so this field will be ignored unless another dataplane provider is used.

show pbr map [NAME] [detail] [json]

Display pbr maps either all or by NAME. If detail is set, it will give information about each rule’s unique internal ID and some extra debugging information about install state for the nexthop/nexthop group. Setting json will provide the same information in an array of objects that adher to the schema below:

Key	Description	Type
name	Map name	String
valid	Is the map well-formed?	Boolean
policies	Rules to match packets against	Array

Each element of the policies array is composed of a set of objects representing the policies associated with this map. Each policy is described below (not all fields are required):

Key	Description	Type
id	Unique ID	Integer
sequenceNumber	Order of this policy within the map	Integer
ruleNumber	Rule number to install into	Integer
vrfUnchanged	Use interface’s VRF	Boolean
installed	Is this policy installed?	Boolean
installedReason	Why (or why not?)	String
matchSrc	Match packets with this source address	String
matchDst	… or with this destination address	String
matchMark	… or with this marker	Integer
vrfName	Associated VRF (if relevant)	String
nexthopGroup	This policy’s nexthop group (if relevant)	Object

Finally, the nexthopGroup object above contains information FRR knows about the configured nexthop for this policy:

Key	Description	Type
tableId	Nexthop table ID	Integer
name	Name of the nexthop group	String
installed	Is this nexthop group installed?	Boolean
installedInternally	Does FRR think NHG is installed?	Integer

PBR Policy

After you have specified a PBR map, in order for it to be enabled, it must be applied to an interface. This policy application to an interface causes the policy to be installed into the kernel.

pbr-policy NAME

This command is available under interface sub-mode. It enables the PBR map NAME on the interface.

Note

This command will not dynamically create PBR maps on sub-interfaces (i.e. vlans), even if one is on the master. Each sub-interface must have the PBR map enabled explicitly.

show pbr interface [NAME] [json]

Enumerates all interfaces which pbrd is keeping track of. Passing json will return an array of interfaces; each returned interface will adhere to the JSON schema below:

Key	Description	Type
name	Interface name	String
index	Device Index	Integer
policy	PBR map for this interface	String
valid	Is the map well-formed?	Boolean

pbr table range (10000-4294966272) (10000-4294966272)

Set or unset the range used to assign numeric table IDs to new nexthop-group tables. Existing tables will not be modified to fit in this range, so this range should be configured before adding nexthop groups.

See also

PBR Details

PBR Debugs

debug pbr events|map|nht|zebra

Debug pbr in pbrd daemon. You must specify what types of debugs to turn on.

PBR Details

Internally, a PBR map is translated into two separate constructs in the Linux kernel.

The PBR map creates an ip rule … that is inserted into the Linux kernel that points to a table to use for forwarding once the rule matches.

The creation of a nexthop or nexthop-group is translated to a table with a default route having the specified nexthop(s).

Sample configuration

nexthop-group TEST
  nexthop 4.5.6.7
  nexthop 5.6.7.8
!
pbr-map BLUE seq 100
  match dst-ip 9.9.9.0/24
  match src-ip 10.10.10.0/24
  set nexthop-group TEST
!
int swp1
  pbr-policy BLUE