WeOS
5.29.0

# Policy-Based Routing (PBR)

## Introduction

Policy-Based Routing (PBR) allows for more specific routing decisions based on specified policies, defined by the administrator. Utilizing PBR can allow the user to route traffic throughout the network in a more precise manner, when the situation deem it necessary or advantageous.

Related Documentation

- Static Routing

Related Examples and Use-Cases

- Policy-Based Routing
- Multiple Upstream Failover

## Overview

When it comes to regular routing, whether it being statically configured routes or dynamically obtained, the routing decision is based on the destination address of the specific frame that is being routed. When performing policy-based routing, a routing decision can be based on additional criteria.

The system allows for configuration of multiple different PBR instances. Each of these instances consist of a next hop gateway address, along with a number of match options that are combined to create the policy that specify the conditions any given frame needs to fullfil in order to select the specified route.

### Policy Matching Options

Each PBR instance need to specify how the specific route can be selected. This is achieved by specifying a number of match rules that constitute the policy used for mapping routing bound frames towards the associated next hop address. When configuring a policy-based route, at least one match rule always needs to be provided.

In Table 1 below, the options that are currently available in the system for the policy definitions are presented. These values may be present in any frame that is bound for routing on the device. If a given frame matches a defined policy rule, an attempt will be made to route the frame towards the policy’s associated next hop address.

Match Type | Description
--- | ---
saddr | Match frames on the source IP address field in the IP header.
daddr | Match frames on the destination IP address field in the IP header.
sport | Match frames on the source port.
dport | Match frames on the destination port.

Table 1: The currently available match types that are useable for defining the match rule that will constitute the policy for any given policy-based route instance.

As an example, it is possible to perform a specific routing decision based on the originating source address. This would allow for different routing decisions for different hosts, even though the destination might still be the same.

Note

If multiple match types are used in the configuration of the same policy-based route instance, a single frame will need to correctly match all of the values provided, i.e. it is NOT sufficient to partially match a policy.

A unique match type can only be used once per PBR instance. If a specific rule needs to be applied more than one time for the same intended next hop gateway, a new PBR instance needs to be added to handle that case.

### Incoming Interface

In addition to specifying the match rules for a given PBR instance, an in-interface also needs to be selected. Hence, the match rules will only ever be checked for frames that ingress on the provided interface. Therefore, it is important that the administrator correctly selects the indented ingressing interfaces when configuring a PBR instance.

For each individual PBR instance it is possible to select one or multiple different interfaces. In addition to this, it is also possible to not specify a specific in-interface. In this case, all available and applicable interfaces will be selected for the PBR instance.

Note

A specific interface can be set as the in-interface for multiple different PBR instances.

#### Locally Originated Traffic

It is possible to have a PBR instance operate only on locally originated traffic. This can be done by specifying the `lo` interface as the in-interface. This can allow the user to direct traffic from the device itself towards a specific route when the matching criteria is fulfilled.

### Routing Selection and Interaction With Regular Routes

In order to have a better understanding how policy routes function in the system and how the selection works, it is good to mention how it works for regular routes. Normally each route that is added, whether statically or dynamically, will be inserted into the main default routing table. The selection of the table is based on a set of selection rules. By default there is an implicit rule that states from all lookup main, indicating that any frame will always utilise the main default routing table.

When a policy-based route is added, it will add another rule, that will be considered before the implicit default rule. The conditions of this rule will be based on the match options that were configured for the PBR instance. Hence, if a frame matches the rules added from a PBR definition, the frame will be instructed to use another routing table. It is in this specific table that the next hop route for the specific PBR instance have been inserted. If multiple different PBR instances specify the same next hop, they will refer to the same specific routing table.

    ip rules                            routing tables
    .----------------------.
    |                      |            .-------------------------.
    | PBR Instance 1 rules +----------> | PBR Instance 1 Next hop |
    |                      |            '-------------------------'
    |                      |
    |                      |            .-------------------------.
    | PBR Instance 2 rules +----------> | PBR Instance 2 Next hop |
    |                      |            '-------------------------'
    |                      |
    |                      |            .-------------------------.
    | from all lookup main |----------> | Static routes           |
    |                      |            | OSPF routes             |
    |                      |            | RIP routes              |
    |                      |            | etc...                  |
    '----------------------'            '-------------------------'

Figure 1: Simplified image on the relation between ip rules and table selection.

A policy-based route rule will always be considered before the implicit rule specifying the main default routing table. Therefore, any policy-based route will always be prioritised over any route located in the main routing table, if the routing bound frame in question matches the conditions for the specific policy-based route.

#### Policy-Based Route Preference

The ordering of the rules for each individual policy-based route definition can be adjusted using the preference value. Adjusting this value will affect the ordering of the rules that are added to the ip rules list. Utilisation of this option can allow the administrator to adjust the lookup order of the policies. Regardless of the the value of this setting, the policy-based routes will always come before the default ip rule.

If no specific preference value is provided, the preference value is considered automatic. Any policy-route definition with a preference specified will always be considered before those set to automatic.

For any policy-based route instance that have the same preference (Including if they are set to automatic), the ordering will be based on the instance id.

## Configuration

Policy-based routes are configured from the IP configuration context:

    example:/#> configure
    example:/config/#> ip
    example:/config/ip/#>

When creating a policy route a sub-context will be entered:

    example:/config/ip/#> policy-route
    example:/config/ip/policy-route-1/#>

If an existing policy route needs to be adjusted, the specific ID for the given route needs to be provided. This can also be done if you want a new route to be created with a specific ID:

    example:/config/ip/#> policy-route 5
    example:/config/ip/policy-route-5/#>

Tip

The priority of the policy-based routes are not just adjusted using the ID of the policy route itself, it can be adjusted with the `preference` command for each specific route. Hence, the ordering of IDs is not only what is used to dictate the priority, unless all routes `preference` are set to `auto`.

Note

It is also important to ensure the IP Forwarding is enabled, by default this should be the case.

`[no] enable`

  Enable or disable the policy-based route instance.

  no
    Disable the policy route instance.
`[no] next-hop [GATEWAY]`

  Specify the next hop IP address for frames matching the policy.

  Just like a regular static route, a policy route specifies a specific next hop address. This next hop will only be usable if a frame matches the policy defined by the `match` command, in addition to ingressing on the interface specified by the `in-iface` command.

  Example

      example:/config/ip/policy-route-1/#> next-hop 192.168.1.99

  no
    Remove the currently configured next-hop.
  GATEWAY
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] in-iface [IFACE [,IFACE ...]]`

  Specify the incoming interface(s) to consider for the route.

  The policy-based route will only be considered for frames that ingress on the provided interface(s). If a frame enters on another interface, even though it may match the configured `match` rule(s), it will not be able to resolve the specific policy-based route.

  A specific interface can be used in multiple different PBR instance definitions.

  Default: `no in-iface` (Any)

  Example

  Some examples on how one, multiple or no specific (Any) `in-iface` can be specified.

      example:/config/ip/policy-route-1/#> in-iface vlan1
      example:/config/ip/policy-route-1/#> in-iface vlan1,vlan2
      example:/config/ip/policy-route-1/#> no in-iface

  no
    Set no specific incoming interface, meaning that any applicable interface will be used for the policy route.
  IFACE
    Name of the interface, e.g. vlan1.
`[no] preference [1-64]`

  Set the preference value of the policy-based route instance.

  Each specific policy-based route match rule will be considered in order. For any rule that potentially can match several frames, this setting can be used to tune the ordering of how the rules are considered.

  The lower the number the higher the preference for the specific entry, i.e. 1 is the highest preference and will be considered first.

  If `no preference` is specified, the route will have a preference considered auto. The route will still have an internal order among all the other policy-based routes that are set to auto.

  Note

  A policy-based route with any preference value set will always be considered before any route that has its preference set to auto.

  Default: `no preference` (Auto)

  no
    Set no specific preference, meaning that the preference value will be auto.
`[no] match [saddr ADDR/LEN | daddr ADDR/LEN | sport PORT | dport PORT]`

  Set the match rule(s) specifying the policy how this route is selected.

  Each policy route needs at lest one match rule to be specified, otherwise there is no policy for frames bound for routing to match against.

  A unique match rule type can only be used one time per PBR instance. If a specific type of rule needs to be applied more than one time for the same target next hop, a new rule needs to be added to handle that situation.

  Example

  Some examples on how the various match options can be configured.

      example:/config/ip/policy-route-1/#> match saddr 192.168.30.1/32
      example:/config/ip/policy-route-1/#> match daddr 192.168.2.0/24
      example:/config/ip/policy-route-1/#> match sport 67
      example:/config/ip/policy-route-1/#> match dport 68
      example:/config/ip/policy-route-1/#> show match

      Match Rules
      SADDR            DADDR           SPORT  DPORT
      192.168.30.1/32  192.168.2.0/24  67     68

  no
    Remove the configured match rules.
  match

    A policy route definition can use the following conditions as match specifiers:

    saddr
      Match frames on the source IP address field in the IP header.
    daddr
      Match frames on the destination IP address field in the IP header.
    sport
      Match frames on the source port.
    dport
      Match frames on the destination port.
  ADDR/LEN
    IP address in standard quad-dotted notation including netmask in CIDR notation, e.g. 192.168.1.1/24.
  PORT
    Port number in range 1-65535.

## Status Overview

In order to see the active status of configured policy routes the following command can be used:

    example:/#> show ip policy-route
    PRIO  SADDR           DADDR           SPORT  DPORT  IN-IFACE  NEXT-HOP
    300   198.18.10.0/24  198.18.20.0/24  500    501    vlan1     10.0.0.1

Note

A policy-based route will not be shown using the regular `show ip route` command in the CLI. In order to check the status of any policy-based route, the `show ip policy-route` needs to be utilised.

Some additional advanced commands exist for troubleshooting any potential problems:

    example:/#> show ip policy-route interface
    show pbr interface
      vlan1(18) with pbr-policy vlan1-map

    example:/#> show ip policy-route map
      pbr-map vlan1-map valid: yes
        Seq: 1 rule: 300
            Installed: yes Reason: Valid
            SRC Match: 198.18.10.0/24
            DST Match: 198.18.20.0/24
            Nexthop-Group: group-0
              Installed: yes Tableid: 10000

    example:/#> show ip policy-route nexthop
    show pbr nexthop
    Nexthop-Group: group-0 Table: 10000 Valid: 1 Installed: 1
        Valid: 1 nexthop 10.0.0.1

« Previous Next »