]>
Commit | Line | Data |
---|---|---|
a6c93cb2 DS |
1 | .. _pbr: |
2 | ||
3 | *** | |
4 | PBR | |
5 | *** | |
6 | ||
6568993b QY |
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. | |
a6c93cb2 DS |
11 | |
12 | .. _starting-pbr: | |
13 | ||
6568993b | 14 | Starting PBR |
a6c93cb2 DS |
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 | ||
6568993b QY |
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. | |
a6c93cb2 DS |
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 | ||
6568993b | 30 | Nexthop Groups |
a6c93cb2 DS |
31 | ============== |
32 | ||
33 | Nexthop groups are a way to encapsulate ECMP information together. It's a | |
6568993b | 34 | listing of ECMP nexthops used to forward packets for when a pbr-map is matched. |
a6c93cb2 | 35 | |
a6c93cb2 DS |
36 | .. clicmd:: nexthop-group NAME |
37 | ||
6568993b QY |
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. | |
a6c93cb2 | 41 | |
54c6fa8e | 42 | .. clicmd:: nexthop [A.B.C.D|X:X::X:XX] [interface [onlink]] [nexthop-vrf NAME] [label LABELS] |
a6c93cb2 | 43 | |
6568993b QY |
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 | ||
03750f1e | 48 | .. clicmd:: pbr table range (10000-4294966272) (10000-4294966272) |
2e7c93ac QY |
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 | ||
010dd8ed | 59 | .. clicmd:: show pbr nexthop-groups [NAME] [json] |
2e7c93ac QY |
60 | |
61 | Display information on a PBR nexthop-group. If ``NAME`` is omitted, all | |
144fd50f WC |
62 | nexthop groups are shown. Setting ``json`` will provide the same |
63 | information in an array of objects which obey the schema below: | |
64 | ||
3e81618d WC |
65 | +-----------+----------------------------+---------+ |
66 | | Key | Description | Type | | |
67 | +===========+============================+=========+ | |
68 | | id | Unique ID | Integer | | |
69 | +-----------+----------------------------+---------+ | |
70 | | name | Name of this group | String | | |
71 | +-----------+----------------------------+---------+ | |
72 | | valid | Is this group well-formed? | Boolean | | |
73 | +-----------+----------------------------+---------+ | |
74 | | installed | ... and is it installed? | Boolean | | |
75 | +-----------+----------------------------+---------+ | |
76 | | nexthops | Nexthops within this group | Array | | |
77 | +-----------+----------------------------+---------+ | |
144fd50f WC |
78 | |
79 | Each element within ``nexthops`` describes a single target within this | |
80 | group, and its structure is described by the JSON below: | |
81 | ||
82 | +---------+------------------------------+---------+ | |
83 | | Key | Description | Type | | |
84 | +=========+==============================+=========+ | |
3e81618d | 85 | | nexthop | Name of this nexthop | String | |
144fd50f | 86 | +---------+------------------------------+---------+ |
3e81618d | 87 | | valid | Is this nexthop well-formed? | Boolean | |
144fd50f | 88 | +---------+------------------------------+---------+ |
2e7c93ac | 89 | |
a6c93cb2 DS |
90 | .. _pbr-maps: |
91 | ||
6568993b | 92 | PBR Maps |
a6c93cb2 DS |
93 | ======== |
94 | ||
2e7c93ac QY |
95 | PBR maps are a way to group policies that we would like to apply to individual |
96 | interfaces. These policies when applied are matched against incoming packets. | |
97 | If matched the nexthop-group or nexthop is used to forward the packets to the | |
98 | end destination. | |
a6c93cb2 | 99 | |
e5436163 | 100 | .. clicmd:: pbr-map NAME seq (1-700) |
a6c93cb2 | 101 | |
6568993b QY |
102 | Create a pbr-map with NAME and sequence number specified. This command puts |
103 | you into a new submode for pbr-map specification. To exit this mode type | |
104 | exit or end as per normal conventions for leaving a sub-mode. | |
a6c93cb2 | 105 | |
6568993b | 106 | .. clicmd:: match src-ip PREFIX |
a6c93cb2 | 107 | |
6568993b QY |
108 | When a incoming packet matches the source prefix specified, take the packet |
109 | and forward according to the nexthops specified. This command accepts both | |
110 | v4 and v6 prefixes. This command is used in conjunction of the | |
111 | :clicmd:`match dst-ip PREFIX` command for matching. | |
a6c93cb2 | 112 | |
6568993b | 113 | .. clicmd:: match dst-ip PREFIX |
a6c93cb2 | 114 | |
6568993b QY |
115 | When a incoming packet matches the destination prefix specified, take the |
116 | packet and forward according to the nexthops specified. This command accepts | |
56f0bea7 | 117 | both v4 and v6 prefixes. This command is used in conjunction of the |
6568993b | 118 | :clicmd:`match src-ip PREFIX` command for matching. |
a6c93cb2 | 119 | |
b7ece6e7 DS |
120 | .. clicmd:: match src-port (1-65535) |
121 | ||
122 | When a incoming packet matches the source port specified, take the | |
123 | packet and forward according to the nexthops specified. | |
124 | ||
125 | .. clicmd:: match dst-port (1-65535) | |
126 | ||
127 | When a incoming packet matches the destination port specified, take the | |
128 | packet and forward according to the nexthops specified. | |
129 | ||
99ed46d9 DS |
130 | .. clicmd:: match ip-protocol [tcp|udp] |
131 | ||
132 | When a incoming packet matches the specified ip protocol, take the | |
133 | packet and forward according to the nexthops specified. | |
134 | ||
a547ef39 DS |
135 | .. clicmd:: match mark (1-4294967295) |
136 | ||
137 | Select the mark to match. This is a linux only command and if attempted | |
138 | on another platform it will be denied. This mark translates to the | |
139 | underlying `ip rule .... fwmark XXXX` command. | |
140 | ||
116b86bd | 141 | .. clicmd:: match dscp (DSCP|0-63) |
01f23aff WC |
142 | |
143 | Match packets according to the specified differentiated services code point | |
144 | (DSCP) in the IP header; if this value matches then forward the packet | |
116b86bd WC |
145 | according to the nexthop(s) specified. The passed DSCP value may also be a |
146 | standard name for a differentiated service code point like cs0 or af11. | |
147 | ||
148 | You may only specify one dscp per route map sequence; to match on multiple | |
149 | dscp values you will need to create several sequences, one for each value. | |
01f23aff WC |
150 | |
151 | .. clicmd:: match ecn (0-3) | |
152 | ||
153 | Match packets according to the specified explicit congestion notification | |
154 | (ECN) field in the IP header; if this value matches then forward the packet | |
155 | according to the nexthop(s) specified. | |
156 | ||
d70a31a3 EB |
157 | |
158 | .. clicmd:: set queue-id (1-65535) | |
159 | ||
160 | Set the egress port queue identifier for matched packets. The Linux Kernel | |
161 | provider does not currently support packet mangling, so this field will be | |
162 | ignored unless another provider is used. | |
163 | ||
164 | .. clicmd:: set pcp (0-7) | |
165 | ||
166 | Set the 802.1Q priority code point (PCP) for matched packets. A PCP of zero | |
167 | is the defaul (nominally, "best effort"). The Linux Kernel provider does not | |
168 | currently support packet mangling, so this field will be ignored unless | |
169 | another provider is used. | |
170 | ||
171 | .. clicmd:: set vlan (1-4094) | |
172 | ||
173 | Set the VLAN tag for matched packets. Identifiers 0 and 4095 are reserved. | |
174 | The Linux Kernel provider does not currently support packet mangling, so | |
175 | this field will be ignored unless another provider is used. | |
176 | ||
177 | .. clicmd:: strip vlan | |
178 | ||
179 | Strip inner vlan tags from matched packets. The Linux Kernel provider does not currently support packet mangling, so this field will be ignored unless another provider is used. It is invalid to specify both a `strip` and `set | |
180 | vlan` action. | |
181 | ||
a6c93cb2 DS |
182 | .. clicmd:: set nexthop-group NAME |
183 | ||
6568993b QY |
184 | Use the nexthop-group NAME as the place to forward packets when the match |
185 | commands have matched a packet. | |
a6c93cb2 DS |
186 | |
187 | .. clicmd:: set nexthop [A.B.C.D|X:X::X:XX] [interface] [nexthop-vrf NAME] | |
188 | ||
6568993b QY |
189 | Use this individual nexthop as the place to forward packets when the match |
190 | commands have matched a packet. | |
a6c93cb2 | 191 | |
be3b67b5 SW |
192 | .. clicmd:: set vrf unchanged|NAME |
193 | ||
194 | If unchanged is set, the rule will use the vrf table the interface is in | |
195 | as its lookup. If NAME is specified, the rule will use that vrf table as | |
196 | its lookup. | |
197 | ||
198 | Not supported with NETNS VRF backend. | |
199 | ||
1a8cafe1 | 200 | .. clicmd:: show pbr map [NAME] [detail|json] |
b781c086 SW |
201 | |
202 | Display pbr maps either all or by ``NAME``. If ``detail`` is set, it will | |
203 | give information about the rules unique ID used internally and some extra | |
204 | debugging information about install state for the nexthop/nexthop group. | |
144fd50f WC |
205 | Setting ``json`` will provide the same information in an array of objects |
206 | which obey the schema below: | |
207 | ||
3e81618d WC |
208 | +----------+--------------------------------+---------+ |
209 | | Key | Description | Type | | |
210 | +==========+================================+=========+ | |
211 | | name | Map name | String | | |
212 | +----------+--------------------------------+---------+ | |
213 | | valid | Is the map well-formed? | Boolean | | |
214 | +----------+--------------------------------+---------+ | |
215 | | policies | Rules to match packets against | Array | | |
216 | +----------+--------------------------------+---------+ | |
144fd50f | 217 | |
f9368f89 | 218 | Each element of the ``policies`` array is composed of a handful of objects |
144fd50f WC |
219 | representing the policies associated with this map. Each policy is |
220 | described as below (not all fields are required): | |
221 | ||
222 | +-----------------+-------------------------------------------+---------+ | |
223 | | Key | Description | Type | | |
224 | +=================+===========================================+=========+ | |
225 | | id | Unique ID | Integer | | |
226 | +-----------------+-------------------------------------------+---------+ | |
227 | | sequenceNumber | Order of this policy within the map | Integer | | |
228 | +-----------------+-------------------------------------------+---------+ | |
229 | | ruleNumber | Rule number to install into | Integer | | |
230 | +-----------------+-------------------------------------------+---------+ | |
231 | | vrfUnchanged | Use interface's VRF | Boolean | | |
232 | +-----------------+-------------------------------------------+---------+ | |
3e81618d | 233 | | installed | Is this policy installed? | Boolean | |
144fd50f WC |
234 | +-----------------+-------------------------------------------+---------+ |
235 | | installedReason | Why (or why not?) | String | | |
236 | +-----------------+-------------------------------------------+---------+ | |
237 | | matchSrc | Match packets with this source address | String | | |
238 | +-----------------+-------------------------------------------+---------+ | |
239 | | matchDst | ... or with this destination address | String | | |
240 | +-----------------+-------------------------------------------+---------+ | |
241 | | matchMark | ... or with this marker | Integer | | |
242 | +-----------------+-------------------------------------------+---------+ | |
243 | | vrfName | Associated VRF (if relevant) | String | | |
244 | +-----------------+-------------------------------------------+---------+ | |
245 | | nexthopGroup | This policy's nexthop group (if relevant) | Object | | |
246 | +-----------------+-------------------------------------------+---------+ | |
247 | ||
248 | Finally, the ``nexthopGroup`` object above cotains information we know | |
249 | about the configured nexthop for this policy: | |
250 | ||
3e81618d WC |
251 | +---------------------+--------------------------------------+---------+ |
252 | | Key | Description | Type | | |
253 | +=====================+======================================+=========+ | |
254 | | tableId | Nexthop table ID | Integer | | |
255 | +---------------------+--------------------------------------+---------+ | |
256 | | name | Name of the nexthop group | String | | |
257 | +---------------------+--------------------------------------+---------+ | |
258 | | installed | Is this nexthop group installed? | Boolean | | |
259 | +---------------------+--------------------------------------+---------+ | |
260 | | installedInternally | Do we think this group is installed? | Integer | | |
261 | +---------------------+--------------------------------------+---------+ | |
b781c086 | 262 | |
8ed09fbf QY |
263 | |
264 | .. index:: | |
265 | pair: policy; PBR | |
266 | ||
a6c93cb2 DS |
267 | .. _pbr-policy: |
268 | ||
6568993b | 269 | PBR Policy |
a6c93cb2 DS |
270 | ========== |
271 | ||
6568993b QY |
272 | After you have specified a PBR map, in order for it to be turned on, you must |
273 | apply the PBR map to an interface. This policy application to an interface | |
274 | causes the policy to be installed into the kernel. | |
a6c93cb2 | 275 | |
a6c93cb2 DS |
276 | .. clicmd:: pbr-policy NAME |
277 | ||
6568993b QY |
278 | This command is available under interface sub-mode. This turns |
279 | on the PBR map NAME and allows it to work properly. | |
a6c93cb2 | 280 | |
5aad6a56 SW |
281 | .. note:: |
282 | This will not dynamically create PBR maps on sub-interfaces (i.e. vlans) | |
283 | even if one is on the master. Each must have the PBR map explicitly added | |
284 | to the interface. | |
285 | ||
9667c597 WC |
286 | .. clicmd:: show pbr interface [NAME] [json] |
287 | ||
288 | Enumerates all interfaces which ``pbrd`` is keeping track of. Passing | |
289 | ``json`` will return an array of interfaces; each returned interface will | |
290 | adhere to the JSON schema below: | |
291 | ||
3e81618d WC |
292 | +--------+----------------------------+---------+ |
293 | | Key | Description | Type | | |
294 | +========+============================+=========+ | |
295 | | name | Interface name | String | | |
296 | +--------+----------------------------+---------+ | |
297 | | index | Device Index | Integer | | |
f41ddc27 | 298 | +--------+----------------------------+---------+ |
3e81618d WC |
299 | | policy | PBR map for this interface | String | |
300 | +--------+----------------------------+---------+ | |
301 | | valid | Is the map well-formed? | Boolean | | |
302 | +--------+----------------------------+---------+ | |
9667c597 | 303 | |
e50f113b SW |
304 | .. _pbr-debugs: |
305 | ||
306 | PBR Debugs | |
307 | =========== | |
308 | ||
e50f113b SW |
309 | .. clicmd:: debug pbr events|map|nht|zebra |
310 | ||
311 | Debug pbr in pbrd daemon. You specify what types of debugs to turn on. | |
312 | ||
e50f113b SW |
313 | .. clicmd:: debug zebra pbr |
314 | ||
315 | Debug pbr in zebra daemon. | |
316 | ||
a6c93cb2 DS |
317 | .. _pbr-details: |
318 | ||
6568993b | 319 | PBR Details |
a6c93cb2 DS |
320 | =========== |
321 | ||
6568993b QY |
322 | Under the covers a PBR map is translated into two separate constructs in the |
323 | Linux kernel. | |
324 | ||
a6c93cb2 | 325 | |
6568993b QY |
326 | The PBR map specified creates a `ip rule ...` that is inserted into the Linux |
327 | kernel that points to a table to use for forwarding once the rule matches. | |
a6c93cb2 | 328 | |
a6c93cb2 | 329 | |
6568993b QY |
330 | The creation of a nexthop or nexthop-group is translated to a default route in a |
331 | table with the nexthops specified as the nexthops for the default route. | |
a6c93cb2 | 332 | |
b832909b QY |
333 | |
334 | Sample configuration | |
335 | ==================== | |
336 | ||
337 | .. code-block:: frr | |
338 | ||
339 | nexthop-group TEST | |
340 | nexthop 4.5.6.7 | |
341 | nexthop 5.6.7.8 | |
342 | ! | |
343 | pbr-map BLUE seq 100 | |
344 | match dst-ip 9.9.9.0/24 | |
345 | match src-ip 10.10.10.0/24 | |
346 | set nexthop-group TEST | |
347 | ! | |
348 | int swp1 | |
349 | pbr-policy BLUE | |
350 | ||
351 |