doc/user/pbr.rst

   1 .. _pbr:
   2
   3 ***
   4 PBR
   5 ***
   6
   7 :abbr:`PBR` is Policy Based Routing.  This implementation supports a very simple
   8 interface to allow admins to influence routing on their router.  At this time
   9 you can only match on destination and source prefixes for an incoming interface.
  10 At this point in time, this implementation will only work on Linux.
  11
  12 .. _starting-pbr:
  13
  14 Starting PBR
  15 ============
  16
  17 Default configuration file for *pbrd* is :file:`pbrd.conf`.  The typical
  18 location of :file:`pbrd.conf` is |INSTALL_PREFIX_ETC|/pbrd.conf.
  19
  20 If the user is using integrated config, then :file:`pbrd.conf` need not be
  21 present and the :file:`frr.conf` is read instead.
  22
  23 .. program:: pbrd
  24
  25 :abbr:`PBR` supports all the common FRR daemon start options which are
  26 documented elsewhere.
  27
  28 .. _nexthop-groups:
  29
  30 Nexthop Groups
  31 ==============
  32
  33 Nexthop groups are a way to encapsulate ECMP information together.  It's a
  34 listing of ECMP nexthops used to forward packets for when a pbr-map is matched.
  35
  36 .. clicmd:: nexthop-group NAME
  37
  38    Create a nexthop-group with an associated NAME.  This will put you into a
  39    sub-mode where you can specify individual nexthops.  To exit this mode type
  40    exit or end as per normal conventions for leaving a sub-mode.
  41
  42 .. clicmd:: nexthop [A.B.C.D|X:X::X:XX] [interface] [nexthop-vrf NAME]
  43
  44    Create a v4 or v6 nexthop.  All normal rules for creating nexthops that you
  45    are used to are allowed here.  The syntax was intentionally kept the same as
  46    creating nexthops as you would for static routes.
  47
  48 .. clicmd:: [no] pbr table range (10000-4294966272) (10000-4294966272)
  49
  50    Set or unset the range used to assign numeric table ID's to new
  51    nexthop-group tables. Existing tables will not be modified to fit in this
  52    range, so it is recommended to configure this before adding nexthop groups.
  53
  54    .. seealso:: :ref:`pbr-details`
  55
  56 Showing Nexthop Group Information
  57 ---------------------------------
  58
  59 .. clicmd:: show pbr nexthop-groups [NAME]
  60
  61    Display information on a PBR nexthop-group. If ``NAME`` is omitted, all
  62    nexthop groups are shown.
  63
  64 .. _pbr-maps:
  65
  66 PBR Maps
  67 ========
  68
  69 PBR maps are a way to group policies that we would like to apply to individual
  70 interfaces. These policies when applied are matched against incoming packets.
  71 If matched the nexthop-group or nexthop is used to forward the packets to the
  72 end destination.
  73
  74 .. clicmd:: pbr-map NAME seq (1-700)
  75
  76    Create a pbr-map with NAME and sequence number specified.  This command puts
  77    you into a new submode for pbr-map specification.  To exit this mode type
  78    exit or end as per normal conventions for leaving a sub-mode.
  79
  80 .. clicmd:: match src-ip PREFIX
  81
  82    When a incoming packet matches the source prefix specified, take the packet
  83    and forward according to the nexthops specified.  This command accepts both
  84    v4 and v6 prefixes.  This command is used in conjunction of the
  85    :clicmd:`match dst-ip PREFIX` command for matching.
  86
  87 .. clicmd:: match dst-ip PREFIX
  88
  89    When a incoming packet matches the destination prefix specified, take the
  90    packet and forward according to the nexthops specified.  This command accepts
  91    both v4 and v6 prefixes.  This command is used in conjuction of the
  92    :clicmd:`match src-ip PREFIX` command for matching.
  93
  94 .. clicmd:: set nexthop-group NAME
  95
  96    Use the nexthop-group NAME as the place to forward packets when the match
  97    commands have matched a packet.
  98
  99 .. clicmd:: set nexthop [A.B.C.D|X:X::X:XX] [interface] [nexthop-vrf NAME]
 100
 101    Use this individual nexthop as the place to forward packets when the match
 102    commands have matched a packet.
 103
 104 .. _pbr-policy:
 105
 106 PBR Policy
 107 ==========
 108
 109 After you have specified a PBR map, in order for it to be turned on, you must
 110 apply the PBR map to an interface.  This policy application to an interface
 111 causes the policy to be installed into the kernel.
 112
 113 .. index:: pbr-policy
 114 .. clicmd:: pbr-policy NAME
 115
 116    This command is available under interface sub-mode.  This turns
 117    on the PBR map NAME and allows it to work properly.
 118
 119 .. _pbr-details:
 120
 121 PBR Details
 122 ===========
 123
 124 Under the covers a PBR map is translated into two separate constructs in the
 125 Linux kernel.
 126
 127 .. index:: PBR Rules
 128
 129 The PBR map specified creates a `ip rule ...` that is inserted into the Linux
 130 kernel that points to a table to use for forwarding once the rule matches.
 131
 132 .. index:: PBR Tables
 133
 134 The creation of a nexthop or nexthop-group is translated to a default route in a
 135 table with the nexthops specified as the nexthops for the default route.
 136