# 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

Default configuration file for pbrd is `pbrd.conf`. The typical location of `pbrd.conf` is /etc/frr/pbrd.conf.

If FRR is using integrated config, then `pbrd.conf` need not be present and the `frr.conf` is read instead.

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