]>
Commit | Line | Data |
---|---|---|
04a22949 | 1 | <!doctype birddoc system> |
d37f899b PM |
2 | |
3 | <!-- | |
3e52d112 | 4 | BIRD 2.0 documentation |
d37f899b | 5 | |
dad92c30 OZ |
6 | This documentation can have 4 forms: sgml (this is master copy), html, ASCII |
7 | text and dvi/postscript (generated from sgml using sgmltools). You should always | |
8 | edit master copy. | |
02357f96 | 9 | |
dad92c30 OZ |
10 | This is a slightly modified linuxdoc dtd. Anything in <descrip> tags is |
11 | considered definition of configuration primitives, <cf> is fragment of | |
12 | configuration within normal text, <m> is "meta" information within fragment of | |
13 | configuration - something in config which is not keyword. | |
d37f899b | 14 | |
dad92c30 | 15 | (set-fill-column 80) |
d37f899b | 16 | |
9b13fa4d | 17 | Copyright 1999 - 2022 CZ.NIC, z.s.p.o , distribute under GPL version 2 or later. |
d37f899b PM |
18 | |
19 | --> | |
20 | ||
371adba6 | 21 | <book> |
d37f899b | 22 | |
3e52d112 | 23 | <title>BIRD 2.0 User's Guide |
d37f899b | 24 | <author> |
aa185265 | 25 | Ondrej Filip <it/<feela@network.cz>/, |
5516a66d | 26 | Martin Mares <it/<mj@ucw.cz>/, |
82b74253 | 27 | Maria Matejka <it/<mq@jmq.cz>/, |
5516a66d | 28 | Ondrej Zajicek <it/<santiago@crfreenet.org>/ |
aa185265 | 29 | </author> |
d37f899b | 30 | |
d37f899b | 31 | <abstract> |
aa185265 | 32 | This document contains user documentation for the BIRD Internet Routing Daemon project. |
d37f899b PM |
33 | </abstract> |
34 | ||
35 | <!-- Table of contents --> | |
36 | <toc> | |
37 | ||
38 | <!-- Begin the document --> | |
39 | ||
dad92c30 | 40 | |
371adba6 | 41 | <chapt>Introduction |
b9864aa8 | 42 | <label id="intro"> |
d37f899b | 43 | |
371adba6 | 44 | <sect>What is BIRD |
b9864aa8 | 45 | <label id="what-is-bird"> |
d37f899b | 46 | |
b9864aa8 | 47 | <p>The name `BIRD' is actually an acronym standing for `BIRD Internet Routing |
dad92c30 OZ |
48 | Daemon'. Let's take a closer look at the meaning of the name: |
49 | ||
50 | <p><em/BIRD/: Well, we think we have already explained that. It's an acronym | |
51 | standing for `BIRD Internet Routing Daemon', you remember, don't you? :-) | |
52 | ||
53 | <p><em/Internet Routing/: It's a program (well, a daemon, as you are going to | |
54 | discover in a moment) which works as a dynamic router in an Internet type | |
55 | network (that is, in a network running either the IPv4 or the IPv6 protocol). | |
56 | Routers are devices which forward packets between interconnected networks in | |
57 | order to allow hosts not connected directly to the same local area network to | |
58 | communicate with each other. They also communicate with the other routers in the | |
59 | Internet to discover the topology of the network which allows them to find | |
60 | optimal (in terms of some metric) rules for forwarding of packets (which are | |
61 | called routing tables) and to adapt themselves to the changing conditions such | |
62 | as outages of network links, building of new connections and so on. Most of | |
63 | these routers are costly dedicated devices running obscure firmware which is | |
64 | hard to configure and not open to any changes (on the other hand, their special | |
65 | hardware design allows them to keep up with lots of high-speed network | |
66 | interfaces, better than general-purpose computer does). Fortunately, most | |
67 | operating systems of the UNIX family allow an ordinary computer to act as a | |
68 | router and forward packets belonging to the other hosts, but only according to a | |
69 | statically configured table. | |
70 | ||
71 | <p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program | |
72 | running on background which does the dynamic part of Internet routing, that is | |
73 | it communicates with the other routers, calculates routing tables and sends them | |
74 | to the OS kernel which does the actual packet forwarding. There already exist | |
75 | other such routing daemons: routed (RIP only), GateD (non-free), | |
7935b9d2 PT |
76 | <HTMLURL URL="http://www.zebra.org" name="Zebra"> and |
77 | <HTMLURL URL="http://sourceforge.net/projects/mrt" name="MRTD">, | |
dad92c30 OZ |
78 | but their capabilities are limited and they are relatively hard to configure |
79 | and maintain. | |
897cd7aa MM |
80 | |
81 | <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings, | |
dad92c30 OZ |
82 | to support all the routing technology used in the today's Internet or planned to |
83 | be used in near future and to have a clean extensible architecture allowing new | |
84 | routing protocols to be incorporated easily. Among other features, BIRD | |
85 | supports: | |
897cd7aa MM |
86 | |
87 | <itemize> | |
88 | <item>both IPv4 and IPv6 protocols | |
89 | <item>multiple routing tables | |
90 | <item>the Border Gateway Protocol (BGPv4) | |
3e52d112 | 91 | <item>the Routing Information Protocol (RIPv2, RIPng) |
0c75411b | 92 | <item>the Open Shortest Path First protocol (OSPFv2, OSPFv3) |
cf3e3845 | 93 | <item>the Babel Routing Protocol |
6bcef225 | 94 | <item>the Router Advertisements for IPv6 hosts |
dad92c30 OZ |
95 | <item>a virtual protocol for exchange of routes between different |
96 | routing tables on a single host | |
897cd7aa MM |
97 | <item>a command-line interface allowing on-line control and inspection |
98 | of status of the daemon | |
dad92c30 OZ |
99 | <item>soft reconfiguration (no need to use complex online commands to |
100 | change the configuration, just edit the configuration file and | |
101 | notify BIRD to re-read it and it will smoothly switch itself to | |
102 | the new configuration, not disturbing routing protocols unless | |
103 | they are affected by the configuration changes) | |
02357f96 | 104 | <item>a powerful language for route filtering |
897cd7aa MM |
105 | </itemize> |
106 | ||
dad92c30 OZ |
107 | <p>BIRD has been developed at the Faculty of Math and Physics, Charles |
108 | University, Prague, Czech Republic as a student project. It can be freely | |
109 | distributed under the terms of the GNU General Public License. | |
110 | ||
111 | <p>BIRD has been designed to work on all UNIX-like systems. It has been | |
112 | developed and tested under Linux 2.0 to 2.6, and then ported to FreeBSD, NetBSD | |
113 | and OpenBSD, porting to other systems (even non-UNIX ones) should be relatively | |
114 | easy due to its highly modular architecture. | |
897cd7aa | 115 | |
3e52d112 JMM |
116 | <p>BIRD 1.x supported either IPv4 or IPv6 protocol, but had to be compiled separately |
117 | for each one. BIRD~2 supports both of them with a possibility of further extension. | |
118 | BIRD~2 supports Linux at least 3.16, FreeBSD 10, NetBSD 7.0, and OpenBSD 5.8. | |
119 | Anyway, it will probably work well also on older systems. | |
d37f899b | 120 | |
371adba6 | 121 | <sect>Installing BIRD |
b9864aa8 | 122 | <label id="install"> |
440439e3 | 123 | |
dad92c30 OZ |
124 | <p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) |
125 | and Perl, installing BIRD should be as easy as: | |
440439e3 PM |
126 | |
127 | <code> | |
dad92c30 OZ |
128 | ./configure |
129 | make | |
130 | make install | |
131 | vi /usr/local/etc/bird.conf | |
c184d9d0 | 132 | bird |
440439e3 PM |
133 | </code> |
134 | ||
02357f96 | 135 | <p>You can use <tt>./configure --help</tt> to get a list of configure |
3e52d112 | 136 | options. The most important ones are: <tt/--with-protocols=/ to produce a slightly smaller |
dad92c30 OZ |
137 | BIRD executable by configuring out routing protocols you don't use, and |
138 | <tt/--prefix=/ to install BIRD to a place different from <file>/usr/local</file>. | |
139 | ||
b093c328 | 140 | |
02357f96 | 141 | <sect>Running BIRD |
b9864aa8 | 142 | <label id="argv"> |
36032ded | 143 | |
c184d9d0 | 144 | <p>You can pass several command-line options to bird: |
d26524fa | 145 | |
c184d9d0 | 146 | <descrip> |
b9864aa8 | 147 | <tag><label id="argv-config">-c <m/config name/</tag> |
66701947 | 148 | use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>. |
c184d9d0 | 149 | |
b9864aa8 | 150 | <tag><label id="argv-debug">-d</tag> |
3fda08e4 | 151 | enable debug messages to stderr, and run bird in foreground. |
c184d9d0 | 152 | |
3fda08e4 OZ |
153 | <tag><label id="argv-debug-file">-D <m/filename of debug log/</tag> |
154 | enable debug messages to given file. | |
a4644ed6 | 155 | |
f5952c73 PT |
156 | <tag><label id="argv-foreground">-f</tag> |
157 | run bird in foreground. | |
e8b89a61 | 158 | |
b9864aa8 | 159 | <tag><label id="argv-group">-g <m/group/</tag> |
e8b89a61 | 160 | use that group ID, see the next section for details. |
1cd198cf | 161 | |
f5952c73 PT |
162 | <tag><label id="argv-help">-h, --help</tag> |
163 | display command-line options to bird. | |
6eda3f13 | 164 | |
b9864aa8 | 165 | <tag><label id="argv-local">-l</tag> |
f2ae2bad | 166 | look for a configuration file and a communication socket in the current |
43fc6bb0 | 167 | working directory instead of in default system locations. However, paths |
f2ae2bad OZ |
168 | specified by options <cf/-c/, <cf/-s/ have higher priority. |
169 | ||
f5952c73 PT |
170 | <tag><label id="argv-parse">-p</tag> |
171 | just parse the config file and exit. Return value is zero if the config | |
172 | file is valid, nonzero if there are some errors. | |
173 | ||
174 | <tag><label id="argv-pid">-P <m/name of PID file/</tag> | |
175 | create a PID file with given filename. | |
176 | ||
b9864aa8 | 177 | <tag><label id="argv-recovery">-R</tag> |
6eda3f13 | 178 | apply graceful restart recovery after start. |
22558357 | 179 | |
f5952c73 PT |
180 | <tag><label id="argv-socket">-s <m/name of communication socket/</tag> |
181 | use given filename for a socket for communications with the client, | |
182 | default is <it/prefix/<file>/var/run/bird.ctl</file>. | |
183 | ||
184 | <tag><label id="argv-user">-u <m/user/</tag> | |
185 | drop privileges and use that user ID, see the next section for details. | |
186 | ||
22558357 PT |
187 | <tag><label id="argv-version">--version</tag> |
188 | display bird version. | |
c184d9d0 | 189 | </descrip> |
d26524fa | 190 | |
02357f96 PM |
191 | <p>BIRD writes messages about its work to log files or syslog (according to config). |
192 | ||
dad92c30 | 193 | |
e8b89a61 | 194 | <sect>Privileges |
b9864aa8 | 195 | <label id="privileges"> |
e8b89a61 | 196 | |
dad92c30 OZ |
197 | <p>BIRD, as a routing daemon, uses several privileged operations (like setting |
198 | routing table and using raw sockets). Traditionally, BIRD is executed and runs | |
199 | with root privileges, which may be prone to security problems. The recommended | |
200 | way is to use a privilege restriction (options <cf/-u/, <cf/-g/). In that case | |
201 | BIRD is executed with root privileges, but it changes its user and group ID to | |
202 | an unprivileged ones, while using Linux capabilities to retain just required | |
203 | privileges (capabilities CAP_NET_*). Note that the control socket is created | |
204 | before the privileges are dropped, but the config file is read after that. The | |
205 | privilege restriction is not implemented in BSD port of BIRD. | |
206 | ||
fff7498d | 207 | <p>An unprivileged user (as an argument to <cf/-u/ options) may be the user |
dad92c30 OZ |
208 | <cf/nobody/, but it is suggested to use a new dedicated user account (like |
209 | <cf/bird/). The similar considerations apply for the group option, but there is | |
210 | one more condition -- the users in the same group can use <file/birdc/ to | |
211 | control BIRD. | |
212 | ||
213 | <p>Finally, there is a possibility to use external tools to run BIRD in an | |
214 | environment with restricted privileges. This may need some configuration, but it | |
215 | is generally easy -- BIRD needs just the standard library, privileges to read | |
216 | the config file and create the control socket and the CAP_NET_* capabilities. | |
e8b89a61 | 217 | |
6eda3f13 | 218 | |
3e52d112 JMM |
219 | <chapt>Architecture |
220 | <label id="architecture"> | |
221 | ||
222 | <sect>Routing tables | |
b9864aa8 | 223 | <label id="routing-tables"> |
a852c139 | 224 | |
3e52d112 JMM |
225 | <p>The heart of BIRD is a routing table. BIRD has several independent routing tables; |
226 | each of them contains routes of exactly one <m/nettype/ (see below). There are two | |
227 | default tables -- <cf/master4/ for IPv4 routes and <cf/master6/ for IPv6 routes. | |
228 | Other tables must be explicitly configured. | |
229 | ||
230 | <p> | |
cf3e3845 OZ |
231 | These routing tables are not kernel forwarding tables. No forwarding is done by |
232 | BIRD. If you want to forward packets using the routes in BIRD tables, you may | |
233 | use the Kernel protocol (see below) to synchronize them with kernel FIBs. | |
3e52d112 JMM |
234 | |
235 | <p> | |
cf3e3845 OZ |
236 | Every nettype defines a (kind of) primary key on routes. Every route source can |
237 | supply one route for every possible primary key; new route announcement replaces | |
238 | the old route from the same source, keeping other routes intact. BIRD always | |
239 | chooses the best route for each primary key among the known routes and keeps the | |
240 | others as suboptimal. When the best route is retracted, BIRD re-runs the best | |
241 | route selection algorithm to find the current best route. | |
3e52d112 JMM |
242 | |
243 | <p> | |
244 | The global best route selection algorithm is (roughly) as follows: | |
a852c139 PM |
245 | |
246 | <itemize> | |
3e52d112 JMM |
247 | <item>Preferences of the routes are compared. |
248 | <item>Source protocol instance preferences are compared. | |
3e52d112 | 249 | <item>If source protocols are the same (e.g. BGP vs. BGP), the protocol's route selection algorithm is invoked. |
cf3e3845 | 250 | <item>If source protocols are different (e.g. BGP vs. OSPF), result of the algorithm is undefined. |
a852c139 PM |
251 | </itemize> |
252 | ||
cf3e3845 | 253 | <p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected |
d0f9a77f OZ |
254 | route from a list of entries for one network. Optionally, these lists of entries |
255 | are kept completely sorted (according to preference or some protocol-dependent | |
256 | metric). See <ref id="rtable-sorted" name="sorted"> table option for details. | |
dad92c30 | 257 | |
3e52d112 JMM |
258 | <sect>Routes and network types |
259 | <label id="routes"> | |
260 | ||
261 | <p>BIRD works with several types of routes. Some of them are typical IP routes, | |
262 | others are better described as forwarding rules. We call them all routes, | |
cf3e3845 | 263 | regardless of this difference. |
3e52d112 | 264 | |
cf3e3845 OZ |
265 | <p>Every route consists of several attributes (read more about them in the |
266 | <ref id="route-attributes" name="Route attributes"> section); the common for all | |
267 | routes are: | |
3e52d112 JMM |
268 | |
269 | <itemize> | |
270 | <item>IP address of router which told us about this route | |
271 | <item>Source protocol instance | |
272 | <item>Route preference | |
273 | <item>Optional attributes defined by protocols | |
274 | </itemize> | |
275 | ||
276 | <p>Other attributes depend on nettypes. Some of them are part of the primary key, these are marked (PK). | |
277 | ||
278 | <sect1>IPv4 and IPv6 routes | |
cf3e3845 | 279 | <label id="ip-routes"> |
3e52d112 JMM |
280 | |
281 | <p>The traditional routes. Configuration keywords are <cf/ipv4/ and <cf/ipv6/. | |
282 | ||
283 | <itemize> | |
284 | <item>(PK) Route destination (IP prefix together with its length) | |
285 | <item>Route next hops (see below) | |
286 | </itemize> | |
287 | ||
159d619c OZ |
288 | <sect1>IPv6 source-specific routes |
289 | <label id="ip-sadr-routes"> | |
290 | ||
291 | <p>The IPv6 routes containing both destination and source prefix. They are used | |
292 | for source-specific routing (SSR), also called source-address dependent routing | |
293 | (SADR), see <rfc id="8043">. Currently limited mostly to the Babel protocol. | |
294 | Configuration keyword is <cf/ipv6 sadr/. | |
295 | ||
296 | <itemize> | |
297 | <item>(PK) Route destination (IP prefix together with its length) | |
298 | <item>(PK) Route source (IP prefix together with its length) | |
299 | <item>Route next hops (see below) | |
300 | </itemize> | |
301 | ||
3e52d112 | 302 | <sect1>VPN IPv4 and IPv6 routes |
cf3e3845 | 303 | <label id="vpn-routes"> |
3e52d112 JMM |
304 | |
305 | <p>Routes for IPv4 and IPv6 with VPN Route Distinguisher (<rfc id="4364">). | |
306 | Configuration keywords are <cf/vpn4/ and <cf/vpn6/. | |
307 | ||
308 | <itemize> | |
309 | <item>(PK) Route destination (IP prefix together with its length) | |
310 | <item>(PK) Route distinguisher (according to <rfc id="4364">) | |
311 | <item>Route next hops | |
312 | </itemize> | |
313 | ||
314 | <sect1>Route Origin Authorization for IPv4 and IPv6 | |
cf3e3845 | 315 | <label id="roa-routes"> |
3e52d112 JMM |
316 | |
317 | <p>These entries can be used to validate route origination of BGP routes. | |
cf3e3845 | 318 | A ROA entry specifies prefixes which could be originated by an AS number. |
3e52d112 JMM |
319 | Their keywords are <cf/roa4/ and <cf/roa6/. |
320 | ||
321 | <itemize> | |
322 | <item>(PK) IP prefix together with its length | |
323 | <item>(PK) Matching prefix maximal length | |
324 | <item>(PK) AS number | |
325 | </itemize> | |
326 | ||
327 | <sect1>Flowspec for IPv4 and IPv6 | |
cf3e3845 | 328 | <label id="flow-routes"> |
3e52d112 JMM |
329 | |
330 | <p>Flowspec rules are a form of firewall and traffic flow control rules | |
331 | distributed mostly via BGP. These rules may help the operators stop various | |
332 | network attacks in the beginning before eating up the whole bandwidth. | |
333 | Configuration keywords are <cf/flow4/ and <cf/flow6/. | |
334 | ||
335 | <itemize> | |
336 | <item>(PK) IP prefix together with its length | |
337 | <item>(PK) Flow definition data | |
338 | <item>Flow action (encoded internally as BGP communities according to <rfc id="5575">) | |
339 | </itemize> | |
340 | ||
341 | <sect1>MPLS switching rules | |
342 | <label id="mpls-routes"> | |
343 | ||
8a708856 OZ |
344 | <p>MPLS routes control MPLS forwarding in the same way as IP routes control IP |
345 | forwarding. MPLS-aware routing protocols produce both labeled IP routes and | |
346 | corresponding MPLS routes. Configuration keyword is <cf/mpls/. | |
3e52d112 JMM |
347 | |
348 | <itemize> | |
349 | <item>(PK) MPLS label | |
350 | <item>Route next hops | |
351 | </itemize> | |
352 | ||
353 | <sect1>Route next hops | |
354 | <label id="route-next-hop"> | |
355 | ||
356 | <p>This is not a nettype. The route next hop is a complex attribute common for many | |
357 | nettypes as you can see before. Every next hop has its assigned device | |
358 | (either assumed from its IP address or set explicitly). It may have also | |
359 | an IP address and an MPLS stack (one or both independently). | |
360 | Maximal MPLS stack depth is set (in compile time) to 8 labels. | |
361 | ||
362 | <p>Every route (when eligible to have a next hop) can have more than one next hop. | |
363 | In that case, every next hop has also its weight. | |
364 | ||
365 | <sect>Protocols and channels | |
366 | <label id="protocols-concept"> | |
367 | ||
cf3e3845 | 368 | <p>BIRD protocol is an abstract class of producers and consumers of the routes. |
3e52d112 JMM |
369 | Each protocol may run in multiple instances and bind on one side to route |
370 | tables via channels, on the other side to specified listen sockets (BGP), | |
371 | interfaces (Babel, OSPF, RIP), APIs (Kernel, Direct), or nothing (Static, Pipe). | |
372 | ||
cf3e3845 | 373 | <p>There are also two protocols that do not have any channels -- BFD and Device. |
3e52d112 JMM |
374 | Both of them are kind of service for other protocols. |
375 | ||
376 | <p>Each protocol is connected to a routing table through a channel. Some protocols | |
377 | support only one channel (OSPF, RIP), some protocols support more channels (BGP, Direct). | |
378 | Each channel has two filters which can accept, reject and modify the routes. | |
379 | An <it/export/ filter is applied to routes passed from the routing table to the protocol, | |
380 | an <it/import/ filter is applied to routes in the opposite direction. | |
48cf5e84 | 381 | |
6eda3f13 | 382 | <sect>Graceful restart |
b9864aa8 | 383 | <label id="graceful-restart"> |
6eda3f13 OZ |
384 | |
385 | <p>When BIRD is started after restart or crash, it repopulates routing tables in | |
386 | an uncoordinated manner, like after clean start. This may be impractical in some | |
387 | cases, because if the forwarding plane (i.e. kernel routing tables) remains | |
388 | intact, then its synchronization with BIRD would temporarily disrupt packet | |
389 | forwarding until protocols converge. Graceful restart is a mechanism that could | |
390 | help with this issue. Generally, it works by starting protocols and letting them | |
391 | repopulate routing tables while deferring route propagation until protocols | |
392 | acknowledge their convergence. Note that graceful restart behavior have to be | |
393 | configured for all relevant protocols and requires protocol-specific support | |
394 | (currently implemented for Kernel and BGP protocols), it is activated for | |
395 | particular boot by option <cf/-R/. | |
396 | ||
96e4d096 OZ |
397 | <p>Some protocols (e.g. BGP) could be restarted gracefully after both |
398 | intentional outage and crash, while others (e.g. OSPF) after intentional outage | |
399 | only. For planned graceful restart, BIRD must be shut down by | |
400 | <ref id="cli-graceful-restart" name="graceful restart"> command instead of | |
401 | regular <ref id="cli-down" name="down"> command. In this way routing neighbors | |
402 | are notified about planned graceful restart and routes are kept in kernel table | |
403 | after shutdown. | |
404 | ||
8a708856 OZ |
405 | <sect>MPLS |
406 | <label id="mpls"> | |
407 | ||
408 | <p>Multiprotocol Label Switching (MPLS) is a networking technology which works | |
409 | below IP routing but above the link (e.g. ethernet) layer. It is described in | |
410 | <rfc id="3031">. | |
411 | ||
412 | In regular IP forwarding, the destination address of a packet is independently | |
413 | examined in each hop, a route with longest prefix match is selected from the | |
414 | routing table, and packet is processed accordingly. In general, there is no | |
415 | difference between border routers and internal routers w.r.t. IP forwarding. | |
416 | ||
417 | In MPLS forwarding, when a packet enters the network, it is classified (based on | |
418 | destination address, ingress interface and other factors) into one of forwarding | |
419 | equivalence classes (FECs), then a header with a MPLS label identifying the FEC | |
420 | is attached to it, and the packet is forwarded. In internal routers, only the | |
421 | MPLS label is examined, the matching MPLS route is selected from the MPLS | |
422 | routing table, and the packet is processed accordingly. The specific value of | |
423 | MPLS label has local meaning only and may change between hops (that is why it is | |
424 | called label switching). When the packet leaves the network, the MPLS header is | |
425 | removed. | |
426 | ||
427 | The advantage of the MPLS approach is that other factors than the destination | |
428 | address can be considered and used consistently in the whole network, for | |
429 | example IP traffic with multiple overlapping private address ranges could be | |
430 | mixed together, or particular paths for specific flows could be defined. Another | |
431 | advantage is that MPLS forwarding by internal routers can be much simpler than | |
432 | IP forwarding, as instead of the longest prefix match algorithm it uses simpler | |
433 | exact match for MPLS route selection. The disadvantage is additional complexity | |
cab5fce2 | 434 | in signaling. For further details, see <rfc id="3031">. |
8a708856 OZ |
435 | |
436 | MPLS-aware routing protocols not only distribute IP routing information, but | |
437 | they also distribute labels. Therefore, they produce labeled routes - routes | |
438 | representing label switched paths (LSPs) through the MPLS domain. Such routes | |
439 | have IP prefix and next hop address like regular (non-labeled) routes, but they | |
440 | also have local MPLS label (in route attribute <ref id="rta-mpls-label" | |
441 | name="mpls_label">) and outgoing MPLS label (as a part of the next hop). They | |
442 | are stored in regular IP routing tables. | |
443 | ||
444 | Labeled routes are used for exchange of routing information between routing | |
445 | protocols and for ingress (IP -> MPLS) forwarding, but they are not directly | |
446 | used for MPLS forwarding. For that purpose <ref id="mpls-routes" name="MPLS | |
447 | routes"> are used. These are routes that have local MPLS label as a primary key | |
448 | and they are stored in the MPLS routing table. | |
449 | ||
450 | In BIRD, the whole process generally works this way: A MPLS-aware routing | |
451 | protocol (say BGP) receives routing information including remote label. It | |
452 | produces a route with attribute <ref id="rta-mpls-policy" name="mpls_policy"> | |
453 | specifying desired <ref id="mpls-channel-label-policy" name="MPLS label policy">. | |
454 | Such route then passes the import filter (which could modify the MPLS label | |
455 | policy or perhaps assign a static label) and when it is accepted, a local MPLS | |
456 | label is selected (according to the label policy) and attached to the route, | |
457 | producing labeled route. When a new MPLS label is allocated, the MPLS-aware | |
458 | protocol automatically produces corresponding MPLS route. When all labeled | |
459 | routes that use specific local MPLS label are retracted, the corresponding MPLS | |
460 | route is retracted too. | |
461 | ||
462 | There are three important concepts for MPLS in BIRD: MPLS domains, MPLS tables | |
463 | and MPLS channels. MPLS domain represents an independent label space, all | |
464 | MPLS-aware protocols are associated with some MPLS domain. It is responsible for | |
465 | label management, handling label allocation requests from MPLS-aware protocols. | |
466 | MPLS table is just a routing table for MPLS routes. Routers usually have one | |
467 | MPLS domain and one MPLS table, with Kernel protocol to export MPLS routes into | |
468 | kernel FIB. | |
469 | ||
470 | MPLS channels make protocols MPLS-aware, they are responsible for keeping track | |
471 | of active FECs (and corresponding allocated labels), selecting FECs / local | |
472 | labels for labeled routes, and maintaining correspondence between labeled routes | |
473 | and MPLS routes. | |
474 | ||
475 | Note that local labels are allocated to individual MPLS-aware protocols and | |
476 | therefore it is not possible to share local labels between different protocols. | |
477 | ||
a852c139 | 478 | |
371adba6 | 479 | <chapt>Configuration |
b9864aa8 | 480 | <label id="config"> |
af0b25d2 | 481 | |
371adba6 | 482 | <sect>Introduction |
b9864aa8 | 483 | <label id="config-intro"> |
d37f899b | 484 | |
dad92c30 OZ |
485 | <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads |
486 | <it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option | |
487 | is given). Configuration may be changed at user's request: if you modify the | |
488 | config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new | |
489 | config. Then there's the client which allows you to talk with BIRD in an | |
490 | extensive way. | |
491 | ||
492 | <p>In the config, everything on a line after <cf/#/ or inside <cf>/* */</cf> is | |
493 | a comment, whitespace characters are treated as a single space. If there's a | |
494 | variable number of options, they are grouped using the <cf/{ }/ brackets. Each | |
495 | option is terminated by a <cf/;/. Configuration is case sensitive. There are two | |
72163bd5 | 496 | ways how to name symbols (like protocol names, filter names, constants etc.). |
eeb2c616 OZ |
497 | You can either use a simple string starting with a letter (or underscore) |
498 | followed by any combination of letters, numbers and underscores (e.g. <cf/R123/, | |
499 | <cf/my_filter/, <cf/bgp5/) or you can enclose the name into apostrophes (<cf/'/) | |
500 | and than you can use any combination of numbers, letters, underscores, hyphens, | |
501 | dots and colons (e.g. <cf/'1:strange-name'/, <cf/'-NAME-'/, <cf/'cool::name'/). | |
dad92c30 OZ |
502 | |
503 | <p>Here is an example of a simple config file. It enables synchronization of | |
72163bd5 OZ |
504 | routing tables with OS kernel, learns network interfaces and runs RIP on all |
505 | network interfaces found. | |
d37f899b | 506 | |
a0dd1c74 | 507 | <code> |
d37f899b | 508 | protocol kernel { |
72163bd5 OZ |
509 | ipv4 { |
510 | export all; # Default is export none | |
511 | }; | |
d150c637 | 512 | persist; # Don't remove routes on BIRD shutdown |
d37f899b PM |
513 | } |
514 | ||
515 | protocol device { | |
d37f899b PM |
516 | } |
517 | ||
518 | protocol rip { | |
72163bd5 OZ |
519 | ipv4 { |
520 | import all; | |
521 | export all; | |
522 | }; | |
f434d191 | 523 | interface "*"; |
d37f899b | 524 | } |
a0dd1c74 | 525 | </code> |
d37f899b | 526 | |
326e33f5 | 527 | |
371adba6 | 528 | <sect>Global options |
b9864aa8 | 529 | <label id="global-opts"> |
af0b25d2 | 530 | |
a0dd1c74 | 531 | <p><descrip> |
3e52d112 | 532 | <tag><label id="opt-include">include "<m/filename/";</tag> |
cf3e3845 OZ |
533 | This statement causes inclusion of a new file. The <m/filename/ could |
534 | also be a wildcard, in that case matching files are included in | |
535 | alphabetic order. The maximal depth is 8. Note that this statement can | |
536 | be used anywhere in the config file, even inside other options, but | |
537 | always on the beginning of line. In the following example, the first | |
538 | semicolon belongs to the <cf/include/, the second to <cf/ipv6 table/. | |
539 | If the <file/tablename.conf/ contains exactly one token (the name of the | |
540 | table), this construction is correct: | |
3e52d112 JMM |
541 | <code> |
542 | ipv6 table | |
543 | include "tablename.conf";; | |
544 | </code> | |
48ec367a | 545 | |
2c7555cf | 546 | <tag><label id="opt-log">log "<m/filename/" [<m/limit/ "<m/backup/"] | syslog [name <m/name/] | stderr | udp <m/address/ [port <m/port/] all|{ <m/list of classes/ }</tag> |
6b5ad206 OZ |
547 | Set logging of messages having the given class (either <cf/all/ or <cf>{ |
548 | error|trace [, <m/.../] }</cf> etc.) into selected destination - a file | |
549 | specified as a filename string (with optional log rotation information), | |
2c7555cf OZ |
550 | syslog (with optional name argument), the stderr output, or as a UDP |
551 | message (in <rfc id="3164"> syslog format). | |
6b5ad206 OZ |
552 | |
553 | Classes are: | |
1632f1fe | 554 | <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems, |
523f020b OZ |
555 | <cf/debug/ for debugging messages, |
556 | <cf/trace/ when you want to know what happens in the network, | |
557 | <cf/remote/ for messages about misbehavior of remote machines, | |
02357f96 | 558 | <cf/auth/ about authentication failures, |
dad92c30 | 559 | <cf/bug/ for internal BIRD bugs. |
6b5ad206 OZ |
560 | |
561 | Logging directly to file supports basic log rotation -- there is an | |
562 | optional log file limit and a backup filename, when log file reaches the | |
563 | limit, the current log file is renamed to the backup filename and a new | |
564 | log file is created. | |
565 | ||
dad92c30 | 566 | You may specify more than one <cf/log/ line to establish logging to |
3fda08e4 OZ |
567 | multiple destinations. Default: log everything to the system log, or |
568 | to the debug output if debugging is enabled by <cf/-d//<cf/-D/ | |
569 | command-line option. | |
02357f96 | 570 | |
9df52a98 | 571 | <tag><label id="opt-debug-protocols">debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag> |
6489a245 OZ |
572 | Set global defaults of protocol debugging options. |
573 | See <ref id="proto-debug" name="debug"> in the following section. | |
574 | Default: off. | |
575 | ||
576 | <tag><label id="opt-debug-channels">debug channels all|off|{ states|routes|filters|events [, <m/.../] }</tag> | |
577 | Set global defaults of channel debugging options. | |
578 | See <ref id="channel-debug" name="debug"> in the channel section. | |
579 | Default: off. | |
5a203dac | 580 | |
54ddf90f MM |
581 | <tag><label id="opt-debug-tables">debug tables all|off|{ states|routes|filters|events [, <m/.../] }</tag> |
582 | Set global defaults of table debugging options. | |
583 | See <ref id="table-debug" name="debug"> in the table section. | |
584 | Default: off. | |
585 | ||
b9864aa8 | 586 | <tag><label id="opt-debug-commands">debug commands <m/number/</tag> |
dad92c30 OZ |
587 | Control logging of client connections (0 for no logging, 1 for logging |
588 | of connects and disconnects, 2 and higher for logging of all client | |
589 | commands). Default: 0. | |
249d238c | 590 | |
b9864aa8 | 591 | <tag><label id="opt-debug-latency">debug latency <m/switch/</tag> |
8bcb5fb1 OZ |
592 | Activate tracking of elapsed time for internal events. Recent events |
593 | could be examined using <cf/dump events/ command. Default: off. | |
594 | ||
b9864aa8 | 595 | <tag><label id="opt-debug-latency-limit">debug latency limit <m/time/</tag> |
8bcb5fb1 OZ |
596 | If <cf/debug latency/ is enabled, this option allows to specify a limit |
597 | for elapsed time. Events exceeding the limit are logged. Default: 1 s. | |
598 | ||
b9864aa8 | 599 | <tag><label id="opt-watchdog-warn">watchdog warning <m/time/</tag> |
8bcb5fb1 OZ |
600 | Set time limit for I/O loop cycle. If one iteration took more time to |
601 | complete, a warning is logged. Default: 5 s. | |
602 | ||
b9864aa8 | 603 | <tag><label id="opt-watchdog-timeout">watchdog timeout <m/time/</tag> |
8bcb5fb1 OZ |
604 | Set time limit for I/O loop cycle. If the limit is breached, BIRD is |
605 | killed by abort signal. The timeout has effective granularity of | |
606 | seconds, zero means disabled. Default: disabled (0). | |
607 | ||
b9864aa8 | 608 | <tag><label id="opt-mrtdump">mrtdump "<m/filename/"</tag> |
dad92c30 OZ |
609 | Set MRTdump file name. This option must be specified to allow MRTdump |
610 | feature. Default: no dump file. | |
cf31112f | 611 | |
9df52a98 | 612 | <tag><label id="opt-mrtdump-protocols">mrtdump protocols all|off|{ states|messages [, <m/.../] }</tag> |
dad92c30 OZ |
613 | Set global defaults of MRTdump options. See <cf/mrtdump/ in the |
614 | following section. Default: off. | |
cf31112f | 615 | |
b9864aa8 | 616 | <tag><label id="opt-filter">filter <m/name local variables/{ <m/commands/ }</tag> |
dad92c30 OZ |
617 | Define a filter. You can learn more about filters in the following |
618 | chapter. | |
326e33f5 | 619 | |
fc4398b4 | 620 | <tag><label id="opt-function">function <m/name/ (<m/parameters/) [ -> <m/return type/ ] <m/local variables/ { <m/commands/ }</tag> |
dad92c30 | 621 | Define a function. You can learn more about functions in the following chapter. |
523f020b | 622 | |
cf3e3845 | 623 | <tag><label id="opt-protocol">protocol rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag> |
dad92c30 OZ |
624 | Define a protocol instance called <cf><m/name/</cf> (or with a name like |
625 | "rip5" generated automatically if you don't specify any | |
626 | <cf><m/name/</cf>). You can learn more about configuring protocols in | |
627 | their own chapters. When <cf>from <m/name2/</cf> expression is used, | |
628 | initial protocol options are taken from protocol or template | |
629 | <cf><m/name2/</cf> You can run more than one instance of most protocols | |
630 | (like RIP or BGP). By default, no instances are configured. | |
a7f23f58 | 631 | |
cf3e3845 | 632 | <tag><label id="opt-template">template rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag> |
dad92c30 OZ |
633 | Define a protocol template instance called <m/name/ (or with a name like |
634 | "bgp1" generated automatically if you don't specify any <m/name/). | |
635 | Protocol templates can be used to group common options when many | |
636 | similarly configured protocol instances are to be defined. Protocol | |
637 | instances (and other templates) can use templates by using <cf/from/ | |
638 | expression and the name of the template. At the moment templates (and | |
639 | <cf/from/ expression) are not implemented for OSPF protocol. | |
249d238c | 640 | |
b9864aa8 | 641 | <tag><label id="opt-define">define <m/constant/ = <m/expression/</tag> |
dad92c30 OZ |
642 | Define a constant. You can use it later in every place you could use a |
643 | value of the same type. Besides, there are some predefined numeric | |
644 | constants based on /etc/iproute2/rt_* files. A list of defined constants | |
645 | can be seen (together with other symbols) using 'show symbols' command. | |
249d238c | 646 | |
265419a3 | 647 | <tag><label id="opt-attribute">attribute <m/type/ <m/name/</tag> |
3a22a6e8 | 648 | Declare a custom route attribute. You can set and get it in filters like |
eeb2c616 | 649 | any other route attribute. This feature is intended for marking routes |
265419a3 MM |
650 | in import filters for export filtering purposes instead of locally |
651 | assigned BGP communities which have to be deleted in export filters. | |
652 | ||
b9864aa8 PT |
653 | <tag><label id="opt-router-id">router id <m/IPv4 address/</tag> |
654 | Set BIRD's router ID. It's a world-wide unique identification of your | |
3e52d112 JMM |
655 | router, usually one of router's IPv4 addresses. Default: the lowest |
656 | IPv4 address of a non-loopback interface. | |
79b4e12e | 657 | |
9df52a98 | 658 | <tag><label id="opt-router-id-from">router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../]</tag> |
3e52d112 JMM |
659 | Set BIRD's router ID based on an IPv4 address of an interface specified by |
660 | an interface pattern. | |
b9864aa8 | 661 | See <ref id="proto-iface" name="interface"> section for detailed |
d7c06285 | 662 | description of interface patterns with extended clauses. |
249d238c | 663 | |
71423871 VB |
664 | <tag><label id="opt-hostname">hostname "<m/name/"</tag> |
665 | Set hostname. Default: node name as returned by `uname -n'. | |
666 | ||
b9864aa8 | 667 | <tag><label id="opt-graceful-restart">graceful restart wait <m/number/</tag> |
6eda3f13 OZ |
668 | During graceful restart recovery, BIRD waits for convergence of routing |
669 | protocols. This option allows to specify a timeout for the recovery to | |
670 | prevent waiting indefinitely if some protocols cannot converge. Default: | |
671 | 240 seconds. | |
672 | ||
b9864aa8 | 673 | <tag><label id="opt-timeformat">timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag> |
dad92c30 OZ |
674 | This option allows to specify a format of date/time used by BIRD. The |
675 | first argument specifies for which purpose such format is used. | |
676 | <cf/route/ is a format used in 'show route' command output, | |
677 | <cf/protocol/ is used in 'show protocols' command output, <cf/base/ is | |
678 | used for other commands and <cf/log/ is used in a log file. | |
679 | ||
680 | "<m/format1/" is a format string using <it/strftime(3)/ notation (see | |
f047271c OZ |
681 | <it/man strftime/ for details). It is extended to support sub-second |
682 | time part with variable precision (up to microseconds) using "%f" | |
683 | conversion code (e.g., "%T.%3f" is hh:mm:ss.sss time). <m/limit/ and | |
684 | "<m/format2/" allow to specify the second format string for times in | |
685 | past deeper than <m/limit/ seconds. | |
686 | ||
687 | There are several shorthands: <cf/iso long/ is a ISO 8601 date/time | |
688 | format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F | |
689 | %T"/. Similarly, <cf/iso long ms/ and <cf/iso long us/ are ISO 8601 | |
690 | date/time formats with millisecond or microsecond precision. | |
dad92c30 OZ |
691 | <cf/iso short/ is a variant of ISO 8601 that uses just the time format |
692 | (hh:mm:ss) for near times (up to 20 hours in the past) and the date | |
f047271c OZ |
693 | format (YYYY-MM-DD) for far times. This is a shorthand for <cf/"%T" |
694 | 72000 "%F"/. And there are also <cf/iso short ms/ and <cf/iso short us/ | |
695 | high-precision variants of that. | |
c37e7851 | 696 | |
f047271c OZ |
697 | By default, BIRD uses the <cf/iso short ms/ format for <cf/route/ and |
698 | <cf/protocol/ times, and the <cf/iso long ms/ format for <cf/base/ and | |
90eb5e7a OZ |
699 | <cf/log/ times. |
700 | ||
d0f9a77f OZ |
701 | <tag><label id="opt-table"><m/nettype/ table <m/name/ [ { <m/option/; [<m/.../] } ]</tag> |
702 | Define a new routing table. The default routing tables <cf/master4/ and | |
703 | <cf/master6/ are defined implicitly, other routing tables have to be | |
704 | defined by this option. See the <ref id="rtable-opts" | |
705 | name="routing table configuration section"> for routing table options. | |
af582c48 | 706 | |
8a708856 OZ |
707 | <tag><label id="opt-mpls-domain">mpls domain <m/name/ [ { <m/option/; [<m/.../] } ]</tag> |
708 | Define a new MPLS domain. MPLS domains represent independent label | |
709 | spaces and are responsible for MPLS label management. All MPLS-aware | |
710 | protocols are associated with some MPLS domain. See the <ref id="mpls-opts" | |
711 | name="MPLS configuration section"> for MPLS domain options. | |
712 | ||
b9864aa8 | 713 | <tag><label id="opt-eval">eval <m/expr/</tag> |
3e52d112 | 714 | Evaluates given filter expression. It is used by the developers for testing of filters. |
249d238c PM |
715 | </descrip> |
716 | ||
cf3e3845 | 717 | |
d0f9a77f OZ |
718 | <sect>Routing table options |
719 | <label id="rtable-opts"> | |
720 | ||
721 | <p>Most routing tables do not need any options and are defined without an option | |
722 | block, but there are still some options to tweak routing table behavior. Note | |
723 | that implicit tables (<cf/master4/ and <cf/master6/) can be redefined in order | |
724 | to set options. | |
725 | ||
726 | <descrip> | |
54ddf90f MM |
727 | <tag><label id="table-debug">debug all|off|{ states|routes|filters [, <m/.../] }</tag> |
728 | Set table debugging options. Like in <ref id="proto-debug" | |
729 | name="protocol debugging">, tables are capable of writing trace | |
730 | messages about its work to the log (with category <cf/trace/). | |
731 | For now, this does nothing, but in version 3, it is used. Default: off. | |
732 | ||
d0f9a77f OZ |
733 | <tag><label id="rtable-sorted">sorted <m/switch/</tag> |
734 | Usually, a routing table just chooses the selected (best) route from a | |
735 | list of routes for each network, while keeping remaining routes unsorted. | |
736 | If enabled, these lists of routes are kept completely sorted (according | |
737 | to preference or some protocol-dependent metric). | |
738 | ||
739 | This is needed for some protocol features (e.g. <cf/secondary/ option of | |
740 | BGP protocol, which allows to accept not just a selected route, but the | |
741 | first route (in the sorted list) that is accepted by filters), but it is | |
742 | incompatible with some other features (e.g. <cf/deterministic med/ | |
743 | option of BGP protocol, which activates a way of choosing selected route | |
744 | that cannot be described using comparison and ordering). Minor advantage | |
745 | is that routes are shown sorted in <cf/show route/, minor disadvantage | |
746 | is that it is slightly more computationally expensive. Default: off. | |
747 | ||
748 | <tag><label id="rtable-trie">trie <m/switch/</tag> | |
749 | BIRD routing tables are implemented with hash tables, which is efficient | |
750 | for exact-match lookups, but inconvenient for longest-match lookups or | |
751 | interval lookups (finding superprefix or subprefixes). This option | |
752 | activates additional trie structure that is used to accelerate these | |
753 | lookups, while using the hash table for exact-match lookups. | |
754 | ||
755 | This has advantage for <ref id="rpki" name="RPKI"> (on ROA tables), | |
756 | for <ref id="bgp-gateway" name="recursive next-hops"> (on IGP tables), | |
757 | and is required for <ref id="bgp-validate" name="flowspec validation"> | |
758 | (on base IP tables). Another advantage is that interval results (like | |
759 | from <cf/show route in .../ command) are lexicographically sorted. The | |
760 | disadvantage is that trie-enabled routing tables require more memory, | |
761 | which may be an issue especially in multi-table setups. Default: off. | |
762 | ||
763 | <tag><label id="rtable-min-settle-time">min settle time <m/time/</tag> | |
764 | Specify a minimum value of the settle time. When a ROA table changes, | |
765 | automatic <ref id="proto-rpki-reload" name="RPKI reload"> may be | |
766 | triggered, after a short settle time. Minimum settle time is a delay | |
767 | from the last ROA table change to wait for more updates. Default: 1 s. | |
768 | ||
769 | ||
770 | <tag><label id="rtable-max-settle-time">max settle time <m/time/</tag> | |
771 | Specify a maximum value of the settle time. When a ROA table changes, | |
772 | automatic <ref id="proto-rpki-reload" name="RPKI reload"> may be | |
773 | triggered, after a short settle time. Maximum settle time is an upper | |
774 | limit to the settle time from the initial ROA table change even if | |
775 | there are consecutive updates gradually renewing the settle time. | |
776 | Default: 20 s. | |
a8a3d95b OZ |
777 | |
778 | <tag><label id="rtable-gc-threshold">gc threshold <m/number/</tag> | |
779 | Specify a minimum amount of removed networks that triggers a garbage | |
780 | collection (GC) cycle. Default: 1000. | |
781 | ||
782 | <tag><label id="rtable-gc-period">gc period <m/time/</tag> | |
783 | Specify a period of time between consecutive GC cycles. When there is a | |
784 | significant amount of route withdraws, GC cycles are executed repeatedly | |
785 | with given period time (with some random factor). When there is just | |
786 | small amount of changes, GC cycles are not executed. In extensive route | |
787 | server setups, running GC on hundreds of full BGP routing tables can | |
788 | take significant amount of time, therefore they should use higher GC | |
789 | periods. Default: adaptive, based on number of routing tables in the | |
790 | configuration. From 10 s (with <= 25 routing tables) up to 600 s (with | |
791 | >= 1500 routing tables). | |
d0f9a77f OZ |
792 | </descrip> |
793 | ||
794 | ||
371adba6 | 795 | <sect>Protocol options |
b9864aa8 | 796 | <label id="protocol-opts"> |
bfd71178 | 797 | |
dad92c30 OZ |
798 | <p>For each protocol instance, you can configure a bunch of options. Some of |
799 | them (those described in this section) are generic, some are specific to the | |
800 | protocol (see sections talking about the protocols). | |
7581b81b | 801 | |
dad92c30 OZ |
802 | <p>Several options use a <m/switch/ argument. It can be either <cf/on/, |
803 | <cf/yes/ or a numeric expression with a non-zero value for the option to be | |
804 | enabled or <cf/off/, <cf/no/ or a numeric expression evaluating to zero to | |
805 | disable it. An empty <m/switch/ is equivalent to <cf/on/ ("silence means | |
806 | agreement"). | |
7581b81b | 807 | |
5a203dac | 808 | <descrip> |
b9864aa8 | 809 | <tag><label id="proto-disabled">disabled <m/switch/</tag> |
dad92c30 OZ |
810 | Disables the protocol. You can change the disable/enable status from the |
811 | command line interface without needing to touch the configuration. | |
812 | Disabled protocols are not activated. Default: protocol is enabled. | |
5a203dac | 813 | |
9df52a98 | 814 | <tag><label id="proto-debug">debug all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag> |
5a203dac PM |
815 | Set protocol debugging options. If asked, each protocol is capable of |
816 | writing trace messages about its work to the log (with category | |
817 | <cf/trace/). You can either request printing of <cf/all/ trace messages | |
6489a245 | 818 | or only of the selected types: <cf/states/ for protocol state changes |
dad92c30 OZ |
819 | (protocol going up, down, starting, stopping etc.), <cf/routes/ for |
820 | routes exchanged with the routing table, <cf/filters/ for details on | |
6489a245 OZ |
821 | route filtering, <cf/interfaces/ for interface change events sent to |
822 | the protocol, <cf/events/ for events internal to the protocol and | |
823 | <cf/packets/ for packets sent and received by the protocol. Classes | |
824 | <cf/routes/ and <cf/filters/ can be also set per-channel using | |
825 | <ref id="channel-debug" name="channel debugging option">) Default: off. | |
5a203dac | 826 | |
9df52a98 | 827 | <tag><label id="proto-mrtdump">mrtdump all|off|{ states|messages [, <m/.../] }</tag> |
dad92c30 OZ |
828 | Set protocol MRTdump flags. MRTdump is a standard binary format for |
829 | logging information from routing protocols and daemons. These flags | |
830 | control what kind of information is logged from the protocol to the | |
831 | MRTdump file (which must be specified by global <cf/mrtdump/ option, see | |
832 | the previous section). Although these flags are similar to flags of | |
833 | <cf/debug/ option, their meaning is different and protocol-specific. For | |
834 | BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs | |
835 | received BGP messages. Other protocols does not support MRTdump yet. | |
cf31112f | 836 | |
b9864aa8 | 837 | <tag><label id="proto-router-id">router id <m/IPv4 address/</tag> |
dad92c30 OZ |
838 | This option can be used to override global router id for a given |
839 | protocol. Default: uses global router id. | |
4cdd0784 | 840 | |
b9864aa8 | 841 | <tag><label id="proto-description">description "<m/text/"</tag> |
dad92c30 | 842 | This is an optional description of the protocol. It is displayed as a |
a043f2d7 | 843 | part of the output of 'show protocols all' command. |
62aa96ca | 844 | |
8c703ecf | 845 | <tag><label id="proto-vrf">vrf "<m/text/"|default</tag> |
943478b0 OZ |
846 | Associate the protocol with specific VRF. The protocol will be |
847 | restricted to interfaces assigned to the VRF and will use sockets bound | |
8c703ecf OZ |
848 | to the VRF. A corresponding VRF interface must exist on OS level. For |
849 | kernel protocol, an appropriate table still must be explicitly selected | |
850 | by <cf/table/ option. | |
851 | ||
852 | By selecting <cf/default/, the protocol is associated with the default | |
853 | VRF; i.e., it will be restricted to interfaces not assigned to any | |
854 | regular VRF. That is different from not specifying <cf/vrf/ at all, in | |
855 | which case the protocol may use any interface regardless of its VRF | |
856 | status. | |
857 | ||
858 | Note that for proper VRF support it is necessary to use Linux kernel | |
859 | version at least 4.14, older versions have limited VRF implementation. | |
860 | Before Linux kernel 5.0, a socket bound to a port in default VRF collide | |
861 | with others in regular VRFs. In BGP, this can be avoided by using | |
862 | <ref id="bgp-strict-bind" name="strict bind"> option. | |
3e52d112 JMM |
863 | |
864 | <tag><label id="proto-channel"><m/channel name/ [{<m/channel config/}]</tag> | |
cf3e3845 OZ |
865 | Every channel must be explicitly stated. See the protocol-specific |
866 | configuration for the list of supported channel names. See the | |
867 | <ref id="channel-opts" name="channel configuration section"> for channel | |
868 | definition. | |
7581b81b PM |
869 | </descrip> |
870 | ||
a7c9f7c0 | 871 | <p>There are several options that give sense only with certain protocols: |
7581b81b PM |
872 | |
873 | <descrip> | |
9df52a98 | 874 | <tag><label id="proto-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../] [ { <m/option/; [<m/.../] } ]</tag> |
f434d191 OZ |
875 | Specifies a set of interfaces on which the protocol is activated with |
876 | given interface-specific options. A set of interfaces specified by one | |
dad92c30 OZ |
877 | interface option is described using an interface pattern. The interface |
878 | pattern consists of a sequence of clauses (separated by commas), each | |
d7c06285 OZ |
879 | clause is a mask specified as a shell-like pattern. Interfaces are |
880 | matched by their name. | |
dad92c30 OZ |
881 | |
882 | An interface matches the pattern if it matches any of its clauses. If | |
883 | the clause begins with <cf/-/, matching interfaces are excluded. Patterns | |
d7c06285 | 884 | are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/ |
dad92c30 OZ |
885 | means eth0 and all non-ethernets. |
886 | ||
d7c06285 OZ |
887 | Some protocols (namely OSPFv2 and Direct) support extended clauses that |
888 | may contain a mask, a prefix, or both of them. An interface matches such | |
889 | clause if its name matches the mask (if specified) and its address | |
890 | matches the prefix (if specified). Extended clauses are used when the | |
891 | protocol handles multiple addresses on an interface independently. | |
892 | ||
dad92c30 OZ |
893 | An interface option can be used more times with different interface-specific |
894 | options, in that case for given interface the first matching interface | |
895 | option is used. | |
523f020b | 896 | |
cf3e3845 | 897 | This option is allowed in Babel, BFD, Device, Direct, OSPF, RAdv and RIP |
3e52d112 | 898 | protocols. In OSPF protocol it is used in the <cf/area/ subsection. |
f434d191 OZ |
899 | |
900 | Default: none. | |
901 | ||
902 | Examples: | |
903 | ||
dad92c30 OZ |
904 | <cf>interface "*" { type broadcast; };</cf> - start the protocol on all |
905 | interfaces with <cf>type broadcast</cf> option. | |
f434d191 | 906 | |
dad92c30 OZ |
907 | <cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the |
908 | protocol on enumerated interfaces with <cf>type ptp</cf> option. | |
523f020b | 909 | |
dad92c30 OZ |
910 | <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol |
911 | on all interfaces that have address from 192.168.0.0/16, but not from | |
912 | 192.168.1.0/24. | |
f434d191 | 913 | |
f434d191 OZ |
914 | <cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all |
915 | ethernet interfaces that have address from 192.168.1.0/24. | |
916 | ||
b9864aa8 | 917 | <tag><label id="proto-tx-class">tx class|dscp <m/num/</tag> |
dad92c30 OZ |
918 | This option specifies the value of ToS/DS/Class field in IP headers of |
919 | the outgoing protocol packets. This may affect how the protocol packets | |
920 | are processed by the network relative to the other network traffic. With | |
921 | <cf/class/ keyword, the value (0-255) is used for the whole ToS/Class | |
922 | octet (but two bits reserved for ECN are ignored). With <cf/dscp/ | |
923 | keyword, the value (0-63) is used just for the DS field in the octet. | |
924 | Default value is 0xc0 (DSCP 0x30 - CS6). | |
ef4a50be | 925 | |
b9864aa8 | 926 | <tag><label id="proto-tx-priority">tx priority <m/num/</tag> |
dad92c30 OZ |
927 | This option specifies the local packet priority. This may affect how the |
928 | protocol packets are processed in the local TX queues. This option is | |
929 | Linux specific. Default value is 7 (highest priority, privileged traffic). | |
ef4a50be | 930 | |
9d8e4b01 | 931 | <tag><label id="proto-pass">password "<m/password/" | <m/bytestring/ [ { <m>password options</m> } ] </tag> |
64385aee PT |
932 | Specifies a password that can be used by the protocol as a shared secret |
933 | key. Password option can be used more times to specify more passwords. | |
934 | If more passwords are specified, it is a protocol-dependent decision | |
935 | which one is really used. Specifying passwords does not mean that | |
936 | authentication is enabled, authentication can be enabled by separate, | |
937 | protocol-dependent <cf/authentication/ option. | |
523f020b | 938 | |
9d8e4b01 AZ |
939 | A password can be specified as a string or as a sequence of hexadecimal |
940 | digit pairs (<ref id="type-bytestring" name="bytestring">). | |
35f88b30 | 941 | |
596f2e32 OZ |
942 | This option is allowed in BFD, OSPF, RIP, and Babel protocols. BGP has |
943 | also <cf/password/ option, but it is slightly different and described | |
944 | separately. Default: none. | |
f434d191 OZ |
945 | </descrip> |
946 | ||
947 | <p>Password option can contain section with some (not necessary all) password sub-options: | |
948 | ||
949 | <descrip> | |
b9864aa8 | 950 | <tag><label id="proto-pass-id">id <M>num</M></tag> |
1ca7665f OZ |
951 | ID of the password, (0-255). If it is not specified, BIRD will choose ID |
952 | based on an order of the password item in the interface, starting from | |
953 | 1. For example, second password item in one interface will have default | |
954 | ID 2. ID 0 is allowed by BIRD, but some other implementations may not | |
955 | allow it. ID is used by some routing protocols to identify which | |
956 | password was used to authenticate protocol packets. | |
f434d191 | 957 | |
b9864aa8 | 958 | <tag><label id="proto-pass-gen-from">generate from "<m/time/"</tag> |
dad92c30 | 959 | The start time of the usage of the password for packet signing. |
13c10ee0 | 960 | The format of <cf><m/time/</cf> is <tt>YYYY-MM-DD [hh:mm:ss[.sss]]</tt>. |
f434d191 | 961 | |
b9864aa8 | 962 | <tag><label id="proto-pass-gen-to">generate to "<m/time/"</tag> |
dad92c30 | 963 | The last time of the usage of the password for packet signing. |
f434d191 | 964 | |
b9864aa8 | 965 | <tag><label id="proto-pass-accept-from">accept from "<m/time/"</tag> |
dad92c30 | 966 | The start time of the usage of the password for packet verification. |
5a203dac | 967 | |
b9864aa8 | 968 | <tag><label id="proto-pass-accept-to">accept to "<m/time/"</tag> |
dad92c30 | 969 | The last time of the usage of the password for packet verification. |
64385aee PT |
970 | |
971 | <tag><label id="proto-pass-from">from "<m/time/"</tag> | |
972 | Shorthand for setting both <cf/generate from/ and <cf/accept from/. | |
973 | ||
974 | <tag><label id="proto-pass-to">to "<m/time/"</tag> | |
975 | Shorthand for setting both <cf/generate to/ and <cf/accept to/. | |
976 | ||
725d9af9 | 977 | <tag><label id="proto-pass-algorithm">algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 | blake2s128 | blake2s256 | blake2b256 | blake2b512 )</tag> |
64385aee PT |
978 | The message authentication algorithm for the password when cryptographic |
979 | authentication is enabled. The default value depends on the protocol. | |
b218a28f THJ |
980 | For RIP and OSPFv2 it is Keyed-MD5 (for compatibility), for OSPFv3 and |
981 | Babel it is HMAC-SHA-256. | |
64385aee | 982 | |
7581b81b | 983 | </descrip> |
d37f899b | 984 | |
cf3e3845 | 985 | |
3e52d112 JMM |
986 | <sect>Channel options |
987 | <label id="channel-opts"> | |
77234bbb | 988 | |
3e52d112 | 989 | <p>Every channel belongs to a protocol and is configured inside its block. The |
72163bd5 OZ |
990 | minimal channel config is empty, then it uses default values. The name of the |
991 | channel implies its nettype. Channel definitions can be inherited from protocol | |
992 | templates. Multiple definitions of the same channel are forbidden, but channels | |
993 | inherited from templates can be updated by new definitions. | |
77234bbb | 994 | |
3e52d112 | 995 | <descrip> |
6489a245 OZ |
996 | <tag><label id="channel-debug">debug all|off|{ states|routes|filters [, <m/.../] }</tag> |
997 | Set channel debugging options. Like in <ref id="proto-debug" | |
998 | name="protocol debugging">, channels are capable of writing trace | |
999 | messages about its work to the log (with category <cf/trace/). You can | |
1000 | either request printing of <cf/all/ trace messages or only of the | |
1001 | selected types: <cf/states/ for channel state changes (channel going up, | |
1002 | down, feeding, reloading etc.), <cf/routes/ for routes propagated | |
1003 | through the channel, <cf/filters/ for details on route filtering, | |
1004 | remaining debug flags are not used in channel debug. Default: off. | |
1005 | ||
3e52d112 | 1006 | <tag><label id="proto-table">table <m/name/</tag> |
cf3e3845 OZ |
1007 | Specify a table to which the channel is connected. Default: the first |
1008 | table of given nettype. | |
1009 | ||
1010 | <tag><label id="proto-preference">preference <m/expr/</tag> | |
1011 | Sets the preference of routes generated by the protocol and imported | |
1012 | through this channel. Default: protocol dependent. | |
77234bbb | 1013 | |
3e52d112 JMM |
1014 | <tag><label id="proto-import">import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/boolean filter expression/</tag> |
1015 | Specify a filter to be used for filtering routes coming from the | |
1016 | protocol to the routing table. <cf/all/ is for keeping all routes, | |
3831b619 OZ |
1017 | <cf/none/ is for dropping all routes. Default: <cf/all/ (except for |
1018 | EBGP). | |
77234bbb | 1019 | |
3e52d112 JMM |
1020 | <tag><label id="proto-export">export <m/filter/</tag> |
1021 | This is similar to the <cf>import</cf> keyword, except that it works in | |
3831b619 | 1022 | the direction from the routing table to the protocol. Default: <cf/none/ |
cab5fce2 | 1023 | (except for EBGP and L3VPN). |
77234bbb | 1024 | |
3e52d112 JMM |
1025 | <tag><label id="proto-import-keep-filtered">import keep filtered <m/switch/</tag> |
1026 | Usually, if an import filter rejects a route, the route is forgotten. | |
1027 | When this option is active, these routes are kept in the routing table, | |
1028 | but they are hidden and not propagated to other protocols. But it is | |
1029 | possible to show them using <cf/show route filtered/. Note that this | |
1030 | option does not work for the pipe protocol. Default: off. | |
77234bbb | 1031 | |
0d1a11cc OZ |
1032 | <tag><label id="proto-rpki-reload">rpki reload <m/switch/</tag> |
1033 | Import or export filters may depend on route RPKI status (using | |
1034 | <cf/roa_check()/ operator). In contrast to to other filter operators, | |
1035 | this status for the same route may change as the content of ROA tables | |
1036 | changes. When this option is active, BIRD activates automatic reload of | |
1037 | affected channels whenever ROA tables are updated (after a short settle | |
1038 | time). When disabled, route reloads have to be requested manually. The | |
1039 | option is ignored if <cf/roa_check()/ is not used in channel filters. | |
1040 | Note that for BGP channels, automatic reload requires | |
1041 | <ref id="bgp-import-table" name="import table"> or | |
1042 | <ref id="bgp-export-table" name="export table"> (for respective | |
1043 | direction). Default: on. | |
1044 | ||
3e52d112 JMM |
1045 | <tag><label id="proto-import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag> |
1046 | Specify an import route limit (a maximum number of routes imported from | |
1047 | the protocol) and optionally the action to be taken when the limit is | |
1048 | hit. Warn action just prints warning log message. Block action discards | |
1049 | new routes coming from the protocol. Restart and disable actions shut | |
1050 | the protocol down like appropriate commands. Disable is the default | |
1051 | action if an action is not explicitly specified. Note that limits are | |
1052 | reset during protocol reconfigure, reload or restart. Default: <cf/off/. | |
77234bbb | 1053 | |
3e52d112 JMM |
1054 | <tag><label id="proto-receive-limit">receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag> |
1055 | Specify an receive route limit (a maximum number of routes received from | |
1056 | the protocol and remembered). It works almost identically to <cf>import | |
1057 | limit</cf> option, the only difference is that if <cf/import keep | |
1058 | filtered/ option is active, filtered routes are counted towards the | |
1059 | limit and blocked routes are forgotten, as the main purpose of the | |
1060 | receive limit is to protect routing tables from overflow. Import limit, | |
1061 | on the contrary, counts accepted routes only and routes blocked by the | |
1062 | limit are handled like filtered routes. Default: <cf/off/. | |
77234bbb | 1063 | |
3e52d112 JMM |
1064 | <tag><label id="proto-export-limit">export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag> |
1065 | Specify an export route limit, works similarly to the <cf>import | |
1066 | limit</cf> option, but for the routes exported to the protocol. This | |
1067 | option is experimental, there are some problems in details of its | |
1068 | behavior -- the number of exported routes can temporarily exceed the | |
1069 | limit without triggering it during protocol reload, exported routes | |
1070 | counter ignores route blocking and block action also blocks route | |
1071 | updates of already accepted routes -- and these details will probably | |
1072 | change in the future. Default: <cf/off/. | |
77234bbb OZ |
1073 | </descrip> |
1074 | ||
3e52d112 JMM |
1075 | <p>This is a trivial example of RIP configured for IPv6 on all interfaces: |
1076 | <code> | |
1077 | protocol rip ng { | |
1078 | ipv6; | |
1079 | interface "*"; | |
77234bbb OZ |
1080 | } |
1081 | </code> | |
1082 | ||
72163bd5 | 1083 | <p>This is a non-trivial example. |
3e52d112 JMM |
1084 | <code> |
1085 | protocol rip ng { | |
1086 | ipv6 { | |
1087 | table mytable6; | |
1088 | import filter { ... }; | |
1089 | export filter { ... }; | |
1090 | import limit 50; | |
1091 | }; | |
1092 | interface "*"; | |
77234bbb OZ |
1093 | } |
1094 | </code> | |
1095 | ||
72163bd5 OZ |
1096 | <p>And this is even more complicated example using templates. |
1097 | <code> | |
1098 | template bgp { | |
1099 | local 198.51.100.14 as 65000; | |
1100 | ||
1101 | ipv4 { | |
1102 | table mytable4; | |
1103 | import filter { ... }; | |
3831b619 | 1104 | export none; |
72163bd5 OZ |
1105 | }; |
1106 | ipv6 { | |
1107 | table mytable6; | |
1108 | import filter { ... }; | |
3831b619 | 1109 | export none; |
72163bd5 OZ |
1110 | }; |
1111 | } | |
1112 | ||
1113 | protocol bgp from { | |
1114 | neighbor 198.51.100.130 as 64496; | |
1115 | ||
1116 | # IPv4 channel is inherited as-is, while IPv6 | |
1117 | # channel is adjusted by export filter option | |
1118 | ipv6 { | |
1119 | export filter { ... }; | |
1120 | }; | |
1121 | } | |
1122 | </code> | |
1123 | ||
1124 | ||
8a708856 OZ |
1125 | <sect>MPLS options |
1126 | <label id="mpls-opts"> | |
1127 | ||
1128 | <p>The MPLS domain definition is mandatory for a MPLS router. All MPLS channels | |
1129 | and MPLS-aware protocols are associated with some MPLS domain (although usually | |
1130 | implicitly with the sole one). In the MPLS domain definition you can configure | |
23f94b13 OZ |
1131 | details of MPLS label allocation. Currently, there is just one option, |
1132 | <cf/label range/. | |
1133 | ||
1134 | <p>Note that the MPLS subsystem is experimental, it is likely that there will be | |
1135 | some backward-incompatible changes in the future. | |
8a708856 OZ |
1136 | |
1137 | <descrip> | |
1138 | <tag><label id="mpls-domain-label-range">label range <m/name/ { start <m/number/; length <m/number/; [<m/.../] }</tag> | |
1139 | Define a new label range, or redefine implicit label ranges <cf/static/ | |
1140 | and <cf/dynamic/. MPLS channels use configured label ranges for dynamic | |
1141 | label allocation, while <cf/static/ label range is used for static label | |
1142 | allocation. The label range definition must specify the extent of the | |
1143 | range. By default, the range <cf/static/ is 16-1000, while the range | |
1144 | <cf/dynamic/ is 1000-10000. | |
1145 | </descrip> | |
1146 | ||
1147 | <p>MPLS channel should be defined in each MPLS-aware protocol in addition to its | |
1148 | regular channels. It is responsible for label allocation and for announcing MPLS | |
1149 | routes to the MPLS routing table. Besides common <ref id="channel-opts" | |
1150 | name="channel options">, MPLS channels have some specific options: | |
1151 | ||
1152 | <descrip> | |
1153 | <tag><label id="mpls-channel-domain">domain <m/name/</tag> | |
1154 | Specify a MPLS domain to which this channel and protocol belongs. | |
1155 | Default: The first defined MPLS domain. | |
1156 | ||
1157 | <tag><label id="mpls-channel-label-range">label range <m/name/</tag> | |
1158 | Use specific label range for dynamic label allocation. Note that static | |
1159 | labels always use the range <cf/static/. Default: the range <cf/dynamic/. | |
1160 | ||
1161 | <tag><label id="mpls-channel-label-policy">label policy static|prefix|aggregate|vrf</tag> | |
1162 | Label policy specifies how routes are grouped to forwarding equivalence | |
1163 | classes (FECs) and how labels are assigned to them. | |
1164 | ||
1165 | The policy <cf/static/ means no dynamic label allocation is done, and | |
1166 | static labels must be set in import filters using the route attribute | |
1167 | <ref id="rta-mpls-label" name="mpls_label">. | |
1168 | ||
1169 | The policy <cf/prefix/ means each prefix uses separate label associated | |
1170 | with that prefix. When a labeled route is updated, it keeps the label. | |
1171 | This policy is appropriate for IGPs. | |
1172 | ||
1173 | The policy <cf/aggregate/ means routes are grouped to FECs according to | |
1174 | their next hops (including next hop labels), and one label is used for | |
1175 | all routes in the same FEC. When a labeled route is updated, it may | |
1176 | change next hop, change FEC and therefore change label. This policy is | |
1177 | appropriate for BGP. | |
1178 | ||
1179 | The policy <cf/vrf/ is only valid in L3VPN protocols. It uses one label | |
1180 | for all routes from a VRF, while replacing the original next hop with | |
1181 | lookup in the VRF. | |
1182 | ||
1183 | Default: <cf/prefix/. | |
1184 | </descrip> | |
1185 | ||
1186 | <p>This is a trivial example of MPLS setup: | |
1187 | <code> | |
1188 | mpls domain mdom { | |
1189 | label range bgprange { start 2000; length 1000; }; | |
1190 | } | |
1191 | ||
1192 | mpls table mtab; | |
1193 | ||
1194 | protocol static { | |
1195 | ipv6; | |
1196 | mpls; | |
1197 | ||
1198 | route 2001:db8:1:1/64 mpls 100 via 2001:db8:1:2::1/64 mpls 200; | |
1199 | } | |
1200 | ||
1201 | protocol bgp { | |
1202 | # regular channels | |
1203 | ipv6 mpls { ... }; | |
1204 | vpn6 mpls { ... }; | |
1205 | ||
1206 | # MPLS channel | |
1207 | mpls { | |
1208 | # domain mdom; | |
1209 | # table mtab; | |
1210 | label range bgprange; | |
1211 | label policy aggregate; | |
1212 | }; | |
1213 | ||
1214 | ... | |
1215 | } | |
1216 | </code> | |
1217 | ||
1218 | ||
5a203dac | 1219 | <chapt>Remote control |
b9864aa8 | 1220 | <label id="remote-control"> |
36032ded | 1221 | |
dad92c30 OZ |
1222 | <p>You can use the command-line client <file>birdc</file> to talk with a running |
1223 | BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless | |
1224 | changed with the <tt/-s/ option given to both the server and the client). The | |
1225 | commands can perform simple actions such as enabling/disabling of protocols, | |
1226 | telling BIRD to show various information, telling it to show routing table | |
1227 | filtered by filter, or asking BIRD to reconfigure. Press <tt/?/ at any time to | |
1228 | get online help. Option <tt/-r/ can be used to enable a restricted mode of BIRD | |
1229 | client, which allows just read-only commands (<cf/show .../). Option <tt/-v/ can | |
1230 | be passed to the client, to make it dump numeric return codes along with the | |
1231 | messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your | |
1232 | own applications could do that, too -- the format of communication between BIRD | |
1233 | and <file/birdc/ is stable (see the programmer's documentation). | |
1234 | ||
1235 | <p>There is also lightweight variant of BIRD client called <file/birdcl/, which | |
1236 | does not support command line editing and history and has minimal dependencies. | |
1237 | This is useful for running BIRD in resource constrained environments, where | |
1238 | Readline library (required for regular BIRD client) is not available. | |
a5e9f3d2 OZ |
1239 | |
1240 | <p>Many commands have the <m/name/ of the protocol instance as an argument. | |
f434d191 OZ |
1241 | This argument can be omitted if there exists only a single instance. |
1242 | ||
5a203dac | 1243 | <p>Here is a brief list of supported functions: |
64722c98 PM |
1244 | |
1245 | <descrip> | |
b9864aa8 | 1246 | <tag><label id="cli-show-status">show status</tag> |
dad92c30 OZ |
1247 | Show router status, that is BIRD version, uptime and time from last |
1248 | reconfiguration. | |
5a203dac | 1249 | |
b9864aa8 | 1250 | <tag><label id="cli-show-interfaces">show interfaces [summary]</tag> |
43fc6bb0 OZ |
1251 | Show the list of interfaces. For each interface, print its type, state, |
1252 | MTU and addresses assigned. | |
1253 | ||
b9864aa8 | 1254 | <tag><label id="cli-show-protocols">show protocols [all]</tag> |
dad92c30 OZ |
1255 | Show list of protocol instances along with tables they are connected to |
1256 | and protocol status, possibly giving verbose information, if <cf/all/ is | |
1257 | specified. | |
64722c98 | 1258 | |
3e52d112 | 1259 | <!-- TODO: Move these protocol-specific remote control commands to the protocol sections --> |
b9864aa8 | 1260 | <tag><label id="cli-show-ospf-iface">show ospf interface [<m/name/] ["<m/interface/"]</tag> |
f434d191 OZ |
1261 | Show detailed information about OSPF interfaces. |
1262 | ||
b9864aa8 | 1263 | <tag><label id="cli-show-ospf-neighbors">show ospf neighbors [<m/name/] ["<m/interface/"]</tag> |
f434d191 OZ |
1264 | Show a list of OSPF neighbors and a state of adjacency to them. |
1265 | ||
b9864aa8 | 1266 | <tag><label id="cli-show-ospf-state">show ospf state [all] [<m/name/]</tag> |
dad92c30 OZ |
1267 | Show detailed information about OSPF areas based on a content of the |
1268 | link-state database. It shows network topology, stub networks, | |
1269 | aggregated networks and routers from other areas and external routes. | |
1270 | The command shows information about reachable network nodes, use option | |
1271 | <cf/all/ to show information about all network nodes in the link-state | |
1272 | database. | |
0ea8fb4a | 1273 | |
b9864aa8 | 1274 | <tag><label id="cli-show-ospf-topology">show ospf topology [all] [<m/name/]</tag> |
dad92c30 OZ |
1275 | Show a topology of OSPF areas based on a content of the link-state |
1276 | database. It is just a stripped-down version of 'show ospf state'. | |
64722c98 | 1277 | |
b9864aa8 | 1278 | <tag><label id="cli-show-ospf-lsadb">show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag> |
dad92c30 OZ |
1279 | Show contents of an OSPF LSA database. Options could be used to filter |
1280 | entries. | |
20ab192b | 1281 | |
b9864aa8 | 1282 | <tag><label id="cli-show-rip-interfaces">show rip interfaces [<m/name/] ["<m/interface/"]</tag> |
43fc6bb0 OZ |
1283 | Show detailed information about RIP interfaces. |
1284 | ||
b9864aa8 | 1285 | <tag><label id="cli-show-rip-neighbors">show rip neighbors [<m/name/] ["<m/interface/"]</tag> |
43fc6bb0 OZ |
1286 | Show a list of RIP neighbors and associated state. |
1287 | ||
b9864aa8 | 1288 | <tag><label id="cli-show-static">show static [<m/name/]</tag> |
f434d191 OZ |
1289 | Show detailed information about static routes. |
1290 | ||
26dd61ee OZ |
1291 | <tag><label id="cli-show-bfd-sessions">show bfd sessions [<m/name/] [address (<m/IP/|<m/prefix/)] [(interface|dev) "<m/name/"] [ipv4|ipv6] [direct|multihop] [all]</tag> |
1292 | Show information about BFD sessions. Options could be used to filter | |
1293 | entries, or in the case of the option <cf/all/ to give verbose output. | |
12201fd8 | 1294 | |
b9864aa8 | 1295 | <tag><label id="cli-show-symbols">show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag> |
dad92c30 OZ |
1296 | Show the list of symbols defined in the configuration (names of |
1297 | protocols, routing tables etc.). | |
5a203dac | 1298 | |
231c6385 | 1299 | <tag><label id="cli-show-route">show route [[(for|in)] <m/prefix/|for <m/IP/] [table (<m/t/|all)] [(import|export) table <m/p/.<m/c/] [filter <m/f/|where <m/cond/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [(stats|count)] [<m/options/]</tag> |
2faf519c | 1300 | Show contents of specified routing tables, that is routes, their metrics |
dad92c30 | 1301 | and (in case the <cf/all/ switch is given) all their attributes. |
5a203dac PM |
1302 | |
1303 | <p>You can specify a <m/prefix/ if you want to print routes for a | |
1304 | specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get | |
1305 | the entry which will be used for forwarding of packets to the given | |
231c6385 JM |
1306 | destination. Finally, if you use <cf>in <m/prefix/</cf>, you get all |
1307 | prefixes covered by the given prefix. | |
1308 | By default, all routes for each network are printed with | |
5a203dac PM |
1309 | the selected one at the top, unless <cf/primary/ is given in which case |
1310 | only the selected route is shown. | |
1311 | ||
b2949999 OZ |
1312 | <p>The <cf/show route/ command can process one or multiple routing |
1313 | tables. The set of selected tables is determined on three levels: First, | |
1314 | tables can be explicitly selected by <cf/table/ switch, which could be | |
1315 | used multiple times, all tables are specified by <cf/table all/. Second, | |
1316 | tables can be implicitly selected by channels or protocols that are | |
1317 | arguments of several other switches (e.g., <cf/export/, <cf/protocol/). | |
1318 | Last, the set of default tables is used: <cf/master4/, <cf/master6/ and | |
1319 | each first table of any other network type. | |
1320 | ||
5aebce5e AZ |
1321 | <p>There are internal tables when <cf/(import|export) table/ options |
1322 | are used for some channels. They can be selected explicitly with | |
1323 | <cf/(import|export) table/ switch, specifying protocol <m/p/ and | |
1324 | channel name <m/c/. | |
1325 | ||
5a203dac PM |
1326 | <p>You can also ask for printing only routes processed and accepted by |
1327 | a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ } | |
1328 | </cf> or matching a given condition (<cf>where <m/condition/</cf>). | |
7aa80901 OZ |
1329 | |
1330 | The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for | |
b2949999 OZ |
1331 | printing of routes that are exported to the specified protocol or |
1332 | channel. With <cf/preexport/, the export filter of the channel is | |
1333 | skipped. With <cf/noexport/, routes rejected by the export filter are | |
1334 | printed instead. Note that routes not exported for other reasons | |
7aa80901 | 1335 | (e.g. secondary routes or routes imported from that protocol) are not |
b2949999 OZ |
1336 | printed even with <cf/noexport/. These switches also imply that |
1337 | associated routing tables are selected instead of default ones. | |
5a203dac | 1338 | |
4d176e14 | 1339 | <p>You can also select just routes added by a specific protocol. |
b2949999 OZ |
1340 | <cf>protocol <m/p/</cf>. This switch also implies that associated |
1341 | routing tables are selected instead of default ones. | |
4d176e14 | 1342 | |
dad92c30 OZ |
1343 | <p>If BIRD is configured to keep filtered routes (see <cf/import keep |
1344 | filtered/ option), you can show them instead of routes by using | |
1345 | <cf/filtered/ switch. | |
cf98be7b | 1346 | |
5a203dac PM |
1347 | <p>The <cf/stats/ switch requests showing of route statistics (the |
1348 | number of networks, number of routes before and after filtering). If | |
1349 | you use <cf/count/ instead, only the statistics will be printed. | |
af582c48 | 1350 | |
fc1b9333 OZ |
1351 | <tag><label id="cli-mrt-dump">mrt dump table <m/name/|"<m/pattern/" to "<m/filename/" [filter <m/f/|where <m/c/]</tag> |
1352 | Dump content of a routing table to a specified file in MRT table dump | |
1353 | format. See <ref id="mrt" name="MRT protocol"> for details. | |
1354 | ||
b9864aa8 | 1355 | <tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag> |
dad92c30 OZ |
1356 | Reload configuration from a given file. BIRD will smoothly switch itself |
1357 | to the new configuration, protocols are reconfigured if possible, | |
1358 | restarted otherwise. Changes in filters usually lead to restart of | |
1359 | affected protocols. | |
1360 | ||
371eb490 OZ |
1361 | The previous configuration is saved and the user can switch back to it |
1362 | with <ref id="cli-configure-undo" name="configure undo"> command. The | |
1363 | old saved configuration is released (even if the reconfiguration attempt | |
1364 | fails due to e.g. a syntax error). | |
1365 | ||
dad92c30 OZ |
1366 | If <cf/soft/ option is used, changes in filters does not cause BIRD to |
1367 | restart affected protocols, therefore already accepted routes (according | |
1368 | to old filters) would be still propagated, but new routes would be | |
1369 | processed according to the new filters. | |
1370 | ||
1371 | If <cf/timeout/ option is used, config timer is activated. The new | |
1372 | configuration could be either confirmed using <cf/configure confirm/ | |
1373 | command, or it will be reverted to the old one when the config timer | |
1374 | expires. This is useful for cases when reconfiguration breaks current | |
fff7498d | 1375 | routing and a router becomes inaccessible for an administrator. The |
dad92c30 OZ |
1376 | config timeout expiration is equivalent to <cf/configure undo/ |
1377 | command. The timeout duration could be specified, default is 300 s. | |
a92cf57d | 1378 | |
b9864aa8 | 1379 | <tag><label id="cli-configure-confirm">configure confirm</tag> |
a92cf57d OZ |
1380 | Deactivate the config undo timer and therefore confirm the current |
1381 | configuration. | |
1382 | ||
b9864aa8 | 1383 | <tag><label id="cli-configure-undo">configure undo</tag> |
dad92c30 OZ |
1384 | Undo the last configuration change and smoothly switch back to the |
1385 | previous (stored) configuration. If the last configuration change was | |
1386 | soft, the undo change is also soft. There is only one level of undo, but | |
1387 | in some specific cases when several reconfiguration requests are given | |
1388 | immediately in a row and the intermediate ones are skipped then the undo | |
1389 | also skips them back. | |
a92cf57d | 1390 | |
b9864aa8 | 1391 | <tag><label id="cli-configure-check">configure check ["<m/config file/"]</tag> |
dad92c30 OZ |
1392 | Read and parse given config file, but do not use it. useful for checking |
1393 | syntactic and some semantic validity of an config file. | |
a92cf57d | 1394 | |
b9864aa8 | 1395 | <tag><label id="cli-enable-disable-restart">enable|disable|restart <m/name/|"<m/pattern/"|all</tag> |
dad92c30 OZ |
1396 | Enable, disable or restart a given protocol instance, instances matching |
1397 | the <cf><m/pattern/</cf> or <cf/all/ instances. | |
bf47fe4b | 1398 | |
b9864aa8 | 1399 | <tag><label id="cli-reload">reload [in|out] <m/name/|"<m/pattern/"|all</tag> |
dad92c30 OZ |
1400 | Reload a given protocol instance, that means re-import routes from the |
1401 | protocol instance and re-export preferred routes to the instance. If | |
1402 | <cf/in/ or <cf/out/ options are used, the command is restricted to one | |
1403 | direction (re-import or re-export). | |
1404 | ||
1405 | This command is useful if appropriate filters have changed but the | |
1406 | protocol instance was not restarted (or reloaded), therefore it still | |
1407 | propagates the old set of routes. For example when <cf/configure soft/ | |
1408 | command was used to change filters. | |
1409 | ||
1410 | Re-export always succeeds, but re-import is protocol-dependent and might | |
1411 | fail (for example, if BGP neighbor does not support route-refresh | |
1412 | extension). In that case, re-export is also skipped. Note that for the | |
1413 | pipe protocol, both directions are always reloaded together (<cf/in/ or | |
1414 | <cf/out/ options are ignored in that case). | |
8a7fb885 | 1415 | |
b9864aa8 | 1416 | <tag><label id="cli-down">down</tag> |
5a203dac | 1417 | Shut BIRD down. |
64722c98 | 1418 | |
96e4d096 OZ |
1419 | <tag><label id="cli-graceful-restart">graceful restart</tag> |
1420 | Shut BIRD down for graceful restart. See <ref id="graceful-restart" | |
1421 | name="graceful restart"> section for details. | |
1422 | ||
9df52a98 | 1423 | <tag><label id="cli-debug">debug <m/protocol/|<m/pattern/|all all|off|{ states|routes|filters|events|packets [, <m/.../] }</tag> |
64722c98 | 1424 | Control protocol debugging. |
508d9360 | 1425 | |
b9864aa8 | 1426 | <tag><label id="cli-dump">dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag> |
508d9360 OZ |
1427 | Dump contents of internal data structures to the debugging output. |
1428 | ||
b9864aa8 | 1429 | <tag><label id="cli-echo">echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag> |
508d9360 | 1430 | Control echoing of log messages to the command-line output. |
b9864aa8 | 1431 | See <ref id="opt-log" name="log option"> for a list of log classes. |
508d9360 | 1432 | |
b9864aa8 | 1433 | <tag><label id="cli-eval">eval <m/expr/</tag> |
508d9360 | 1434 | Evaluate given expression. |
64722c98 | 1435 | </descrip> |
36032ded | 1436 | |
72163bd5 | 1437 | |
371adba6 | 1438 | <chapt>Filters |
b9864aa8 | 1439 | <label id="filters"> |
d37f899b | 1440 | |
371adba6 | 1441 | <sect>Introduction |
b9864aa8 | 1442 | <label id="filters-intro"> |
d37f899b | 1443 | |
dad92c30 OZ |
1444 | <p>BIRD contains a simple programming language. (No, it can't yet read mail :-). |
1445 | There are two objects in this language: filters and functions. Filters are | |
1446 | interpreted by BIRD core when a route is being passed between protocols and | |
1447 | routing tables. The filter language contains control structures such as if's and | |
1448 | switches, but it allows no loops. An example of a filter using many features can | |
1449 | be found in <file>filter/test.conf</file>. | |
d37f899b | 1450 | |
dad92c30 OZ |
1451 | <p>Filter gets the route, looks at its attributes and modifies some of them if |
1452 | it wishes. At the end, it decides whether to pass the changed route through | |
1453 | (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks like | |
1454 | this: | |
d37f899b | 1455 | |
a0dd1c74 | 1456 | <code> |
d37f899b | 1457 | filter not_too_far |
d37f899b | 1458 | { |
1ac8e11b | 1459 | int var; |
d37f899b PM |
1460 | if defined( rip_metric ) then |
1461 | var = rip_metric; | |
1462 | else { | |
1463 | var = 1; | |
1464 | rip_metric = 1; | |
1465 | } | |
1466 | if rip_metric > 10 then | |
1467 | reject "RIP metric is too big"; | |
1468 | else | |
1469 | accept "ok"; | |
1470 | } | |
a0dd1c74 | 1471 | </code> |
d37f899b | 1472 | |
dad92c30 OZ |
1473 | <p>As you can see, a filter has a header, a list of local variables, and a body. |
1474 | The header consists of the <cf/filter/ keyword followed by a (unique) name of | |
1475 | filter. The list of local variables consists of <cf><M>type name</M>;</cf> | |
3a22a6e8 | 1476 | pairs where each pair declares one local variable. The body consists of <cf> |
dad92c30 OZ |
1477 | { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You |
1478 | can group several statements to a single compound statement by using braces | |
1479 | (<cf>{ <M>statements</M> }</cf>) which is useful if you want to make a bigger | |
1480 | block of code conditional. | |
1632f1fe | 1481 | |
fc4398b4 OZ |
1482 | <p>BIRD supports functions, so that you don not have to repeat the same blocks |
1483 | of code over and over. Functions can have zero or more parameters and they can | |
1484 | have local variables. If the function returns value, then you should always | |
1485 | specify its return type. Direct recursion is possible. Function definitions look | |
1486 | like this: | |
0e5373fd PM |
1487 | |
1488 | <code> | |
fc4398b4 | 1489 | function name() -> int |
0e5373fd | 1490 | { |
1ac8e11b OZ |
1491 | int local_variable; |
1492 | int another_variable = 5; | |
062ff656 | 1493 | return 42; |
0e5373fd PM |
1494 | } |
1495 | ||
fc4398b4 | 1496 | function with_parameters(int parameter) -> pair |
0e5373fd PM |
1497 | { |
1498 | print parameter; | |
062ff656 | 1499 | return (1, 2); |
0e5373fd PM |
1500 | } |
1501 | </code> | |
1502 | ||
1ac8e11b OZ |
1503 | <p>Like in C programming language, variables are declared inside function body, |
1504 | either at the beginning, or mixed with other statements. Declarations may | |
1505 | contain initialization. You can also declare variables in nested blocks, such | |
1506 | variables have scope restricted to such block. There is a deprecated syntax to | |
1507 | declare variables after the <cf/function/ line, but before the first <cf/{/. | |
1508 | Functions are called like in C: <cf>name(); with_parameters(5);</cf>. Function | |
1509 | may return values using the <cf>return <m/[expr]/</cf> command. Returning a | |
1510 | value exits from current function (this is similar to C). | |
0e5373fd | 1511 | |
1ac8e11b | 1512 | <p>Filters are defined in a way similar to functions except they cannot have |
062ff656 | 1513 | explicit parameters and cannot return. They get a route table entry as an implicit parameter, it |
dad92c30 | 1514 | is also passed automatically to any functions called. The filter must terminate |
1ac8e11b | 1515 | with either <cf/accept/ or <cf/reject/ statement. If there is a runtime error in |
dad92c30 | 1516 | filter, the route is rejected. |
0e5373fd | 1517 | |
dad92c30 OZ |
1518 | <p>A nice trick to debug filters is to use <cf>show route filter <m/name/</cf> |
1519 | from the command line client. An example session might look like: | |
c184d9d0 PM |
1520 | |
1521 | <code> | |
1522 | pavel@bug:~/bird$ ./birdc -s bird.ctl | |
1523 | BIRD 0.0.0 ready. | |
c184d9d0 PM |
1524 | bird> show route |
1525 | 10.0.0.0/8 dev eth0 [direct1 23:21] (240) | |
1526 | 195.113.30.2/32 dev tunl1 [direct1 23:21] (240) | |
1527 | 127.0.0.0/8 dev lo [direct1 23:21] (240) | |
1528 | bird> show route ? | |
1632f1fe | 1529 | show route [<prefix>] [table <t>] [filter <f>] [all] [primary]... |
66701947 | 1530 | bird> show route filter { if 127.0.0.5 ˜ net then accept; } |
c184d9d0 PM |
1531 | 127.0.0.0/8 dev lo [direct1 23:21] (240) |
1532 | bird> | |
1533 | </code> | |
1534 | ||
dad92c30 | 1535 | |
371adba6 | 1536 | <sect>Data types |
b9864aa8 | 1537 | <label id="data-types"> |
d37f899b | 1538 | |
dad92c30 | 1539 | <p>Each variable and each value has certain type. Booleans, integers and enums |
eeb2c616 OZ |
1540 | are incompatible with each other (that is to prevent you from shooting oneself |
1541 | in the foot). | |
d37f899b PM |
1542 | |
1543 | <descrip> | |
b9864aa8 | 1544 | <tag><label id="type-bool">bool</tag> |
dad92c30 OZ |
1545 | This is a boolean type, it can have only two values, <cf/true/ and |
1546 | <cf/false/. Boolean is the only type you can use in <cf/if/ statements. | |
1547 | ||
b9864aa8 | 1548 | <tag><label id="type-int">int</tag> |
dad92c30 OZ |
1549 | This is a general integer type. It is an unsigned 32bit type; i.e., you |
1550 | can expect it to store values from 0 to 4294967295. Overflows are not | |
1551 | checked. You can use <cf/0x1234/ syntax to write hexadecimal values. | |
1552 | ||
b9864aa8 | 1553 | <tag><label id="type-pair">pair</tag> |
dad92c30 OZ |
1554 | This is a pair of two short integers. Each component can have values |
1555 | from 0 to 65535. Literals of this type are written as <cf/(1234,5678)/. | |
1556 | The same syntax can also be used to construct a pair from two arbitrary | |
1557 | integer expressions (for example <cf/(1+2,a)/). | |
1558 | ||
e15e4657 AZ |
1559 | Operators <cf/.asn/ and <cf/.data/ can be used to extract corresponding |
1560 | components of a pair: <cf>(<m/asn/, <m/data/)</cf>. | |
1561 | ||
b9864aa8 | 1562 | <tag><label id="type-quad">quad</tag> |
dad92c30 OZ |
1563 | This is a dotted quad of numbers used to represent router IDs (and |
1564 | others). Each component can have a value from 0 to 255. Literals of | |
1565 | this type are written like IPv4 addresses. | |
1566 | ||
b9864aa8 | 1567 | <tag><label id="type-string">string</tag> |
dad92c30 OZ |
1568 | This is a string of characters. There are no ways to modify strings in |
1569 | filters. You can pass them between functions, assign them to variables | |
1570 | of type <cf/string/, print such variables, use standard string | |
1571 | comparison operations (e.g. <cf/=, !=, <, >, <=, >=/), but | |
1572 | you can't concatenate two strings. String literals are written as | |
768d5e10 PT |
1573 | <cf/"This is a string constant"/. Additionally matching (<cf/˜, |
1574 | !˜/) operators could be used to match a string value against | |
1575 | a shell pattern (represented also as a string). | |
dad92c30 | 1576 | |
9d8e4b01 AZ |
1577 | <tag><label id="type-bytestring">bytestring</tag> |
1578 | This is a sequences of arbitrary bytes. There are no ways to modify | |
1579 | bytestrings in filters. You can pass them between function, assign | |
1580 | them to variables of type <cf/bytestring/, print such values, | |
c5c3a22b | 1581 | compare bytestings (<cf/=, !=/). |
9d8e4b01 | 1582 | |
c5c3a22b OZ |
1583 | Bytestring literals are written as a sequence of hexadecimal digit |
1584 | pairs, optionally colon-separated. A bytestring specified this way | |
1585 | must be either at least 16 bytes (32 digits) long, or prefixed by the | |
1586 | <cf/hex:/ prefix: <cf/01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef/, | |
1587 | <cf/0123456789abcdef0123456789abcdef/, <cf/hex:/, <cf/hex:12:34:56/, | |
1588 | <cf/hex:12345678/. | |
9d8e4b01 AZ |
1589 | |
1590 | A bytestring can be made from a hex string using <cf/from_hex()/ | |
c5c3a22b OZ |
1591 | function. Source strings can use any number of dots, colons, hyphens |
1592 | and spaces as byte separators: <cf/from_hex(" 12.34 56:78 ab-cd-ef ")/. | |
9d8e4b01 | 1593 | |
b9864aa8 | 1594 | <tag><label id="type-ip">ip</tag> |
cf3e3845 OZ |
1595 | This type can hold a single IP address. The IPv4 addresses are stored as |
1596 | IPv4-Mapped IPv6 addresses so one data type for both of them is used. | |
14ce8904 | 1597 | Whether the address is IPv4 or not may be checked by <cf>.is_v4</cf> |
eeb2c616 | 1598 | which returns a <cf/bool/. IP addresses are written in the standard |
cf3e3845 OZ |
1599 | notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special |
1600 | operator <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out | |
1601 | all but first <cf><M>num</M></cf> bits from the IP address. So | |
dad92c30 OZ |
1602 | <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. |
1603 | ||
b9864aa8 | 1604 | <tag><label id="type-prefix">prefix</tag> |
8c9986d3 JMM |
1605 | This type can hold a network prefix consisting of IP address, prefix |
1606 | length and several other values. This is the key in route tables. | |
1607 | ||
a5d2a344 OZ |
1608 | Prefixes may be of several types, which can be determined by the special |
1609 | operator <cf/.type/. The type may be: | |
8c9986d3 | 1610 | |
a5d2a344 | 1611 | <cf/NET_IP4/ and <cf/NET_IP6/ prefixes hold an IP prefix. The literals |
0575c7db | 1612 | are written as <cf><m/ipaddress//<m/pxlen/</cf>. There are two special |
cf3e3845 OZ |
1613 | operators on these: <cf/.ip/ which extracts the IP address from the |
1614 | pair, and <cf/.len/, which separates prefix length from the pair. | |
90dc0f08 | 1615 | So <cf>1.2.0.0/16.len = 16</cf> is true. |
dad92c30 | 1616 | |
159d619c OZ |
1617 | <cf/NET_IP6_SADR/ nettype holds both destination and source IPv6 |
1618 | prefix. The literals are written as <cf><m/ipaddress//<m/pxlen/ from | |
1619 | <m/ipaddress//<m/pxlen/</cf>, where the first part is the destination | |
1620 | prefix and the second art is the source prefix. They support the same | |
ff2ca10c OZ |
1621 | operators as IP prefixes, but just for the destination part. They also |
1622 | support <cf/.src/ and <cf/.dst/ operators to get respective parts of the | |
1623 | address as separate <cf/NET_IP6/ values. | |
159d619c | 1624 | |
a5d2a344 OZ |
1625 | <cf/NET_VPN4/ and <cf/NET_VPN6/ prefixes hold an IP prefix with VPN |
1626 | Route Distinguisher (<rfc id="4364">). They support the same special | |
1627 | operators as IP prefixes, and also <cf/.rd/ which extracts the Route | |
1628 | Distinguisher. Their literals are written | |
1629 | as <cf><m/vpnrd/ <m/ipprefix/</cf> | |
8c9986d3 | 1630 | |
a5d2a344 OZ |
1631 | <cf/NET_ROA4/ and <cf/NET_ROA6/ prefixes hold an IP prefix range |
1632 | together with an ASN. They support the same special operators as IP | |
1633 | prefixes, and also <cf/.maxlen/ which extracts maximal prefix length, | |
1634 | and <cf/.asn/ which extracts the ASN. | |
8c9986d3 | 1635 | |
a5d2a344 | 1636 | <cf/NET_FLOW4/ and <cf/NET_FLOW6/ hold an IP prefix together with a |
ff2ca10c OZ |
1637 | flowspec rule. Filters currently do not support much flowspec parsing, |
1638 | only <cf/.src/ and <cf/.dst/ operators to get source and destination | |
1639 | parts of the flowspec as separate <cf/NET_IP4/ / <cf/NET_IP6/ values. | |
8c9986d3 | 1640 | |
cf3e3845 OZ |
1641 | <cf/NET_MPLS/ holds a single MPLS label and its handling is currently |
1642 | not implemented. | |
3e52d112 JMM |
1643 | |
1644 | <tag><label id="type-vpnrd">vpnrd</tag> | |
1645 | This is a route distinguisher according to <rfc id="4364">. There are | |
1646 | three kinds of RD's: <cf><m/asn/:<m/32bit int/</cf>, <cf><m/asn4/:<m/16bit int/</cf> | |
1647 | and <cf><m/IPv4 address/:<m/32bit int/</cf> | |
1648 | ||
b9864aa8 | 1649 | <tag><label id="type-ec">ec</tag> |
dad92c30 OZ |
1650 | This is a specialized type used to represent BGP extended community |
1651 | values. It is essentially a 64bit value, literals of this type are | |
1652 | usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>, where | |
1653 | <cf/kind/ is a kind of extended community (e.g. <cf/rt/ / <cf/ro/ for a | |
1654 | route target / route origin communities), the format and possible values | |
1655 | of <cf/key/ and <cf/value/ are usually integers, but it depends on the | |
1656 | used kind. Similarly to pairs, ECs can be constructed using expressions | |
1657 | for <cf/key/ and <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where | |
1658 | <cf/myas/ is an integer variable). | |
dcde7ae5 | 1659 | |
b9864aa8 | 1660 | <tag><label id="type-lc">lc</tag> |
cec4a73c OZ |
1661 | This is a specialized type used to represent BGP large community |
1662 | values. It is essentially a triplet of 32bit values, where the first | |
1663 | value is reserved for the AS number of the issuer, while meaning of | |
1664 | remaining parts is defined by the issuer. Literals of this type are | |
1665 | written as <cf/(123, 456, 789)/, with any integer values. Similarly to | |
1666 | pairs, LCs can be constructed using expressions for its parts, (e.g. | |
1667 | <cf/(myas, 10+20, 3*10)/, where <cf/myas/ is an integer variable). | |
1668 | ||
e15e4657 AZ |
1669 | Operators <cf/.asn/, <cf/.data1/, and <cf/.data2/ can be used |
1670 | to extract corresponding components of LCs: | |
1671 | <cf>(<m/asn/, <m/data1/, <m/data2/)</cf>. | |
1672 | ||
b9864aa8 | 1673 | <tag><label id="type-set">int|pair|quad|ip|prefix|ec|lc|enum set</tag> |
dad92c30 OZ |
1674 | Filters recognize four types of sets. Sets are similar to strings: you |
1675 | can pass them around but you can't modify them. Literals of type <cf>int | |
1676 | set</cf> look like <cf> [ 1, 2, 5..7 ]</cf>. As you can see, both simple | |
1677 | values and ranges are permitted in sets. | |
1678 | ||
1679 | For pair sets, expressions like <cf/(123,*)/ can be used to denote | |
1680 | ranges (in that case <cf/(123,0)..(123,65535)/). You can also use | |
1681 | <cf/(123,5..100)/ for range <cf/(123,5)..(123,100)/. You can also use | |
1682 | <cf/*/ and <cf/a..b/ expressions in the first part of a pair, note that | |
1683 | such expressions are translated to a set of intervals, which may be | |
1684 | memory intensive. E.g. <cf/(*,4..20)/ is translated to <cf/(0,4..20), | |
1685 | (1,4..20), (2,4..20), ... (65535, 4..20)/. | |
1686 | ||
1687 | EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123, | |
1688 | 10..20)/ or <cf/(ro, 123, *)/. Expressions requiring the translation | |
1689 | (like <cf/(rt, *, 3)/) are not allowed (as they usually have 4B range | |
1690 | for ASNs). | |
1691 | ||
cec4a73c OZ |
1692 | Also LC sets use similar expressions like pair sets. You can use ranges |
1693 | and wildcards, but if one field uses that, more specific (later) fields | |
1694 | must be wildcards. E.g., <cf/(10, 20..30, *)/ or <cf/(10, 20, 30..40)/ | |
1695 | is valid, while <cf/(10, *, 20..30)/ or <cf/(10, 20..30, 40)/ is not | |
1696 | valid. | |
1697 | ||
1698 | You can also use expressions for int, pair, EC and LC set values. | |
1699 | However, it must be possible to evaluate these expressions before daemon | |
1700 | boots. So you can use only constants inside them. E.g. | |
dad92c30 | 1701 | |
946dc15c OF |
1702 | <code> |
1703 | define one=1; | |
8815d846 | 1704 | define myas=64500; |
946dc15c OF |
1705 | int set odds; |
1706 | pair set ps; | |
8815d846 | 1707 | ec set es; |
946dc15c | 1708 | |
8815d846 | 1709 | odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ]; |
b54ad333 | 1710 | ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ]; |
8815d846 | 1711 | es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ]; |
946dc15c | 1712 | </code> |
b1a597e0 | 1713 | |
dad92c30 OZ |
1714 | Sets of prefixes are special: their literals does not allow ranges, but |
1715 | allows prefix patterns that are written | |
1716 | as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>. | |
1717 | Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix | |
1718 | pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if the | |
1719 | first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are | |
06301a99 | 1720 | identical and <cf>l <= len1 <= h</cf>. A valid prefix pattern |
dad92c30 OZ |
1721 | has to satisfy <cf>low <= high</cf>, but <cf/pxlen/ is not |
1722 | constrained by <cf/low/ or <cf/high/. Obviously, a prefix matches a | |
1723 | prefix set literal if it matches any prefix pattern in the prefix set | |
1724 | literal. | |
1725 | ||
1726 | There are also two shorthands for prefix patterns: <cf><m/address//<m/len/+</cf> | |
1727 | is a shorthand for <cf><m/address//<m/len/{<m/len/,<m/maxlen/}</cf> | |
1728 | (where <cf><m/maxlen/</cf> is 32 for IPv4 and 128 for IPv6), that means | |
1729 | network prefix <cf><m/address//<m/len/</cf> and all its subnets. | |
1730 | <cf><m/address//<m/len/-</cf> is a shorthand for | |
1731 | <cf><m/address//<m/len/{0,<m/len/}</cf>, that means network prefix | |
1732 | <cf><m/address//<m/len/</cf> and all its supernets (network prefixes | |
1733 | that contain it). | |
1734 | ||
1735 | For example, <cf>[ 1.0.0.0/8, 2.0.0.0/8+, 3.0.0.0/8-, 4.0.0.0/8{16,24} | |
1736 | ]</cf> matches prefix <cf>1.0.0.0/8</cf>, all subprefixes of | |
1737 | <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes | |
1738 | <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf> | |
1739 | matches all prefixes (regardless of IP address) whose prefix length is | |
1740 | 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP | |
1741 | address <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 ˜ [ 1.0.0.0/8{15,17} ]</cf> | |
1742 | is true, but <cf>1.0.0.0/16 ˜ [ 1.0.0.0/8- ]</cf> is false. | |
1743 | ||
1744 | Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed | |
523f020b | 1745 | in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as |
dad92c30 OZ |
1746 | <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as |
1747 | <cf>192.168.0.0/16{24,32}</cf>. | |
d37f899b | 1748 | |
a1090561 OZ |
1749 | It is not possible to mix IPv4 and IPv6 prefixes in a prefix set. It is |
1750 | currently possible to mix IPv4 and IPv6 addresses in an ip set, but that | |
1751 | behavior may change between versions without any warning; don't do it | |
1752 | unless you are more than sure what you are doing. (Really, don't do it.) | |
3e52d112 | 1753 | |
b9864aa8 | 1754 | <tag><label id="type-enum">enum</tag> |
dad92c30 OZ |
1755 | Enumeration types are fixed sets of possibilities. You can't define your |
1756 | own variables of such type, but some route attributes are of enumeration | |
1757 | type. Enumeration types are incompatible with each other. | |
0e5373fd | 1758 | |
b9864aa8 | 1759 | <tag><label id="type-bgppath">bgppath</tag> |
dad92c30 OZ |
1760 | BGP path is a list of autonomous system numbers. You can't write |
1761 | literals of this type. There are several special operators on bgppaths: | |
4cdd0784 | 1762 | |
dad92c30 | 1763 | <cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/. |
4cdd0784 | 1764 | |
dad92c30 | 1765 | <cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/. |
4cdd0784 | 1766 | |
9c9cc35c OZ |
1767 | <cf><m/P/.last_nonaggregated</cf> returns the last ASN in the non-aggregated part of the path <m/P/. |
1768 | ||
dad92c30 OZ |
1769 | Both <cf/first/ and <cf/last/ return zero if there is no appropriate |
1770 | ASN, for example if the path contains an AS set element as the first (or | |
9c9cc35c OZ |
1771 | the last) part. If the path ends with an AS set, <cf/last_nonaggregated/ |
1772 | may be used to get last ASN before any AS set. | |
4cdd0784 | 1773 | |
dad92c30 | 1774 | <cf><m/P/.len</cf> returns the length of path <m/P/. |
4cdd0784 | 1775 | |
fc9d471b | 1776 | <cf><m/P/.empty</cf> makes the path <m/P/ empty. Can't be used as a value, always modifies the object. |
18ea2ea7 | 1777 | |
fc9d471b | 1778 | <cf><m/P/.prepend(<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and |
dad92c30 | 1779 | returns the result. |
bff9ce51 | 1780 | |
fc9d471b | 1781 | <cf><m/P/.delete(<m/A/)</cf> deletes all instances of ASN <m/A/ from |
dad92c30 OZ |
1782 | from path <m/P/ and returns the result. <m/A/ may also be an integer |
1783 | set, in that case the operator deletes all ASNs from path <m/P/ that are | |
1784 | also members of set <m/A/. | |
bff9ce51 | 1785 | |
fc9d471b MM |
1786 | <cf><m/P/.filter(<m/A/)</cf> deletes all ASNs from path <m/P/ that are |
1787 | not members of integer set <m/A/, and returns the result. | |
1788 | I.e., <cf/filter/ do the same as <cf/delete/ with inverted set <m/A/. | |
bff9ce51 | 1789 | |
fc9d471b MM |
1790 | Methods <cf>prepend</cf>, <cf>delete</cf> and <cf>filter</cf> keep the |
1791 | original object intact as long as you use the result in any way. You can | |
1792 | also write e.g. <cf><m/P/.prepend(<m/A/);</cf> as a standalone statement. | |
1793 | This variant does modify the original object with the result of the operation. | |
4a5bb2bf | 1794 | |
b9864aa8 | 1795 | <tag><label id="type-bgpmask">bgpmask</tag> |
dad92c30 OZ |
1796 | BGP masks are patterns used for BGP path matching (using <cf>path |
1797 | ˜ [= 2 3 5 * =]</cf> syntax). The masks resemble wildcard patterns | |
1798 | as used by UNIX shells. Autonomous system numbers match themselves, | |
1799 | <cf/*/ matches any (even empty) sequence of arbitrary AS numbers and | |
523f020b | 1800 | <cf/?/ matches one arbitrary AS number. For example, if <cf>bgp_path</cf> |
dad92c30 | 1801 | is 4 3 2 1, then: <tt>bgp_path ˜ [= * 4 3 * =]</tt> is true, |
ec430a7f OZ |
1802 | but <tt>bgp_path ˜ [= * 4 5 * =]</tt> is false. There is also |
1803 | <cf/+/ operator which matches one or multiple instances of previous | |
1804 | expression, e.g. <tt>[= 1 2+ 3 =]</tt> matches both path 1 2 3 and path | |
1805 | 1 2 2 2 3, but not 1 3 nor 1 2 4 3. Note that while <cf/*/ and <cf/?/ | |
1806 | are wildcard-style operators, <cf/+/ is regex-style operator. | |
1807 | ||
1808 | BGP mask expressions can also contain integer expressions enclosed in | |
1809 | parenthesis and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. | |
1810 | You can also use ranges (e.g. <tt>[= * 3..5 2 100..200 * =]</tt>) | |
1811 | and sets (e.g. <tt>[= 1 2 [3, 5, 7] * =]</tt>). | |
4cdd0784 | 1812 | |
b9864aa8 | 1813 | <tag><label id="type-clist">clist</tag> |
dad92c30 OZ |
1814 | Clist is similar to a set, except that unlike other sets, it can be |
1815 | modified. The type is used for community list (a set of pairs) and for | |
1816 | cluster list (a set of quads). There exist no literals of this type. | |
77042292 | 1817 | There are special operators on clists: |
dad92c30 OZ |
1818 | |
1819 | <cf><m/C/.len</cf> returns the length of clist <m/C/. | |
1820 | ||
fc9d471b | 1821 | <cf><m/C/.empty</cf> makes the list <m/C/ empty. Can't be used as a value, always modifies the object. |
18ea2ea7 | 1822 | |
fc9d471b | 1823 | <cf><m/C/.add(<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and |
dad92c30 OZ |
1824 | returns the result. If item <m/P/ is already in clist <m/C/, it does |
1825 | nothing. <m/P/ may also be a clist, in that case all its members are | |
1826 | added; i.e., it works as clist union. | |
1827 | ||
fc9d471b | 1828 | <cf><m/C/.delete(<m/P/)</cf> deletes pair (or quad) <m/P/ from clist |
dad92c30 OZ |
1829 | <m/C/ and returns the result. If clist <m/C/ does not contain item |
1830 | <m/P/, it does nothing. <m/P/ may also be a pair (or quad) set, in that | |
1831 | case the operator deletes all items from clist <m/C/ that are also | |
1832 | members of set <m/P/. Moreover, <m/P/ may also be a clist, which works | |
1833 | analogously; i.e., it works as clist difference. | |
1834 | ||
fc9d471b MM |
1835 | <cf><m/C/.filter(<m/P/)</cf> deletes all items from clist <m/C/ that are |
1836 | not members of pair (or quad) set <m/P/, and returns the result. I.e., <cf/filter/ do the same | |
dad92c30 OZ |
1837 | as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which |
1838 | works analogously; i.e., it works as clist intersection. | |
1839 | ||
fc9d471b MM |
1840 | Methods <cf>add</cf>, <cf>delete</cf> and <cf>filter</cf> keep the |
1841 | original object intact as long as you use the result in any way. You can | |
1842 | also write e.g. <cf><m/P/.add(<m/A/);</cf> as a standalone statement. | |
1843 | This variant does modify the original object with the result of the operation. | |
8815d846 | 1844 | |
77042292 AZ |
1845 | <cf><m/C/.min</cf> returns the minimum element of clist <m/C/. |
1846 | ||
1847 | <cf><m/C/.max</cf> returns the maximum element of clist <m/C/. | |
1848 | ||
1849 | Operators <cf/.min/, <cf/.max/ can be used together with <cf/filter/ | |
1850 | to extract the community from the specific subset of communities | |
1851 | (e.g. localpref or prepend) without the need to check every possible | |
1852 | value (e.g. <cf/filter(bgp_community, [(23456, 1000..1099)]).min/). | |
1853 | ||
b9864aa8 | 1854 | <tag><label id="type-eclist">eclist</tag> |
dad92c30 OZ |
1855 | Eclist is a data type used for BGP extended community lists. Eclists |
1856 | are very similar to clists, but they are sets of ECs instead of pairs. | |
768d5e10 PT |
1857 | The same operations (like <cf/add/, <cf/delete/ or <cf/˜/ and |
1858 | <cf/!˜/ membership operators) can be used to modify or test | |
1859 | eclists, with ECs instead of pairs as arguments. | |
cec4a73c | 1860 | |
eeb2c616 | 1861 | <tag><label id="type-lclist">lclist</tag> |
cec4a73c OZ |
1862 | Lclist is a data type used for BGP large community lists. Like eclists, |
1863 | lclists are very similar to clists, but they are sets of LCs instead of | |
1864 | pairs. The same operations (like <cf/add/, <cf/delete/ or <cf/˜/ | |
1865 | and <cf/!˜/ membership operators) can be used to modify or test | |
1866 | lclists, with LCs instead of pairs as arguments. | |
d37f899b PM |
1867 | </descrip> |
1868 | ||
159d619c | 1869 | |
a7c9f7c0 | 1870 | <sect>Operators |
b9864aa8 | 1871 | <label id="operators"> |
d37f899b | 1872 | |
dad92c30 OZ |
1873 | <p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, |
1874 | parentheses <cf/(a*(b+c))/, comparison <cf/(a=b, a!=b, a<b, a>=b)/. | |
3e52d112 | 1875 | Logical operations include unary not (<cf/!/), and (<cf/&&/), and or |
768d5e10 PT |
1876 | (<cf/||/). Special operators include (<cf/˜/, |
1877 | <cf/!˜/) for "is (not) element of a set" operation - it can be used on | |
1878 | element and set of elements of the same type (returning true if element is | |
1879 | contained in the given set), or on two strings (returning true if first string | |
1880 | matches a shell-like pattern stored in second string) or on IP and prefix | |
1881 | (returning true if IP is within the range defined by that prefix), or on prefix | |
1882 | and prefix (returning true if first prefix is more specific than second one) or | |
1883 | on bgppath and bgpmask (returning true if the path matches the mask) or on | |
1884 | number and bgppath (returning true if the number is in the path) or on bgppath | |
1885 | and int (number) set (returning true if any ASN from the path is in the set) or | |
1886 | on pair/quad and clist (returning true if the pair/quad is element of the | |
1887 | clist) or on clist and pair/quad set (returning true if there is an element of | |
1888 | the clist that is also a member of the pair/quad set). | |
dad92c30 OZ |
1889 | |
1890 | <p>There is one operator related to ROA infrastructure - <cf/roa_check()/. It | |
7935b9d2 PT |
1891 | examines a ROA table and does <rfc id="6483"> route origin validation for a |
1892 | given network prefix. The basic usage is <cf>roa_check(<m/table/)</cf>, which | |
eeb2c616 OZ |
1893 | checks the current route (which should be from BGP to have AS_PATH argument) in |
1894 | the specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA, | |
dad92c30 | 1895 | ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant |
af582c48 | 1896 | ROAs but none of them match. There is also an extended variant |
dad92c30 OZ |
1897 | <cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to specify a |
1898 | prefix and an ASN as arguments. | |
af582c48 | 1899 | |
d37f899b | 1900 | |
371adba6 | 1901 | <sect>Control structures |
b9864aa8 | 1902 | <label id="control-structures"> |
d37f899b | 1903 | |
cb339a30 OZ |
1904 | <p>Filters support several control structures: conditions, for loops and case |
1905 | switches. | |
a7c9f7c0 | 1906 | |
3e52d112 JMM |
1907 | <p>Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/commandT/; |
1908 | else <m/commandF/;</cf> and you can use <cf>{ <m/command1/; <m/command2/; | |
dad92c30 | 1909 | <M>...</M> }</cf> instead of either command. The <cf>else</cf> clause may be |
3e52d112 JMM |
1910 | omitted. If the <cf><m>boolean expression</m></cf> is true, <m/commandT/ is |
1911 | executed, otherwise <m/commandF/ is executed. | |
dad92c30 | 1912 | |
cb339a30 OZ |
1913 | <p>For loops allow to iterate over elements in compound data like BGP paths or |
1914 | community lists. The syntax is: <cf>for [ <m/type/ ] <m/variable/ in <m/expr/ | |
1915 | do <m/command/;</cf> and you can also use compound command like in conditions. | |
1916 | The expression is evaluated to a compound data, then for each element from such | |
1917 | data the command is executed with the item assigned to the variable. A variable | |
1918 | may be an existing one (when just name is used) or a locally defined (when type | |
1919 | and name is used). In both cases, it must have the same type as elements. | |
1920 | ||
dad92c30 OZ |
1921 | <p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case |
1922 | <m/expr/ { else: | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ | |
1923 | ... ] }</cf>. The expression after <cf>case</cf> can be of any type which can be | |
1924 | on the left side of the ˜ operator and anything that could be a member of | |
1925 | a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ | |
1926 | grouping. If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements | |
1927 | between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches | |
1928 | neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed. | |
d37f899b | 1929 | |
a7c9f7c0 | 1930 | <p>Here is example that uses <cf/if/ and <cf/case/ structures: |
af0b25d2 PM |
1931 | |
1932 | <code> | |
cb339a30 OZ |
1933 | if 1234 = i then printn "."; else { |
1934 | print "not 1234"; | |
1935 | print "You need {} around multiple commands"; | |
1936 | } | |
1937 | ||
1938 | for int asn in bgp_path do { | |
1939 | printn "ASN: ", asn; | |
1940 | if asn < 65536 then print " (2B)"; else print " (4B)"; | |
1941 | } | |
1942 | ||
af0b25d2 PM |
1943 | case arg1 { |
1944 | 2: print "two"; print "I can do more commands without {}"; | |
1945 | 3 .. 5: print "three to five"; | |
1946 | else: print "something else"; | |
a7c9f7c0 | 1947 | } |
af0b25d2 PM |
1948 | </code> |
1949 | ||
dad92c30 | 1950 | |
371adba6 | 1951 | <sect>Route attributes |
b9864aa8 | 1952 | <label id="route-attributes"> |
0e5373fd | 1953 | |
dad92c30 | 1954 | <p>A filter is implicitly passed a route, and it can access its attributes just |
3a22a6e8 OZ |
1955 | like it accesses variables. There are common route attributes, protocol-specific |
1956 | route attributes and custom route attributes. Most common attributes are | |
1957 | mandatory (always defined), while remaining are optional. Attempts to access | |
1958 | undefined attribute result in a runtime error; you can check if an attribute is | |
1959 | defined by using the <cf>defined( <m>attribute</m> )</cf> operator. One notable | |
1960 | exception to this rule are attributes of bgppath and *clist types, where | |
1961 | undefined value is regarded as empty bgppath/*clist for most purposes. | |
1962 | ||
1963 | Attributes can be defined by just setting them in filters. Custom attributes | |
1964 | have to be first declared by <ref id="opt-attribute" name="attribute"> global | |
1965 | option. You can also undefine optional attribute back to non-existence by using | |
1966 | the <cf>unset( <m/attribute/ )</cf> operator. | |
1967 | ||
1968 | Common route attributes are: | |
a7c9f7c0 | 1969 | |
36032ded | 1970 | <descrip> |
b9864aa8 | 1971 | <tag><label id="rta-net"><m/prefix/ net</tag> |
cf3e3845 OZ |
1972 | The network prefix or anything else the route is talking about. The |
1973 | primary key of the routing table. Read-only. (See the <ref id="routes" | |
1974 | name="chapter about routes">.) | |
a7c9f7c0 | 1975 | |
b9864aa8 | 1976 | <tag><label id="rta-scope"><m/enum/ scope</tag> |
dad92c30 OZ |
1977 | The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes |
1978 | local to this host, <cf/SCOPE_LINK/ for those specific for a physical | |
1979 | link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private routes and | |
1980 | <cf/SCOPE_UNIVERSE/ for globally visible routes. This attribute is not | |
1981 | interpreted by BIRD and can be used to mark routes in filters. The | |
1982 | default value for new routes is <cf/SCOPE_UNIVERSE/. | |
0e5373fd | 1983 | |
b9864aa8 | 1984 | <tag><label id="rta-preference"><m/int/ preference</tag> |
dad92c30 OZ |
1985 | Preference of the route. Valid values are 0-65535. (See the chapter |
1986 | about routing tables.) | |
c184d9d0 | 1987 | |
b9864aa8 | 1988 | <tag><label id="rta-from"><m/ip/ from</tag> |
00192d5a | 1989 | The router which the route has originated from. |
523f020b | 1990 | |
b9864aa8 | 1991 | <tag><label id="rta-gw"><m/ip/ gw</tag> |
a7c9f7c0 | 1992 | Next hop packets routed using this route should be forwarded to. |
0e5373fd | 1993 | |
b9864aa8 | 1994 | <tag><label id="rta-proto"><m/string/ proto</tag> |
dad92c30 OZ |
1995 | The name of the protocol which the route has been imported from. |
1996 | Read-only. | |
e29fa06e | 1997 | |
b9864aa8 | 1998 | <tag><label id="rta-source"><m/enum/ source</tag> |
dad92c30 | 1999 | what protocol has told me about this route. Possible values: |
3660f19d | 2000 | <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/, |
4155104c OZ |
2001 | <cf/RTS_RIP/, <cf/RTS_OSPF/, <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, |
2002 | <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/, <cf/RTS_PIPE/, <cf/RTS_BABEL/. | |
c184d9d0 | 2003 | |
b9864aa8 | 2004 | <tag><label id="rta-dest"><m/enum/ dest</tag> |
182a7895 OZ |
2005 | Type of destination the packets should be sent to |
2006 | (<cf/RTD_ROUTER/ for forwarding to a neighboring router, | |
2007 | <cf/RTD_DEVICE/ for routing to a directly-connected network, | |
2008 | <cf/RTD_MULTIPATH/ for multipath destinations, | |
2009 | <cf/RTD_BLACKHOLE/ for packets to be silently discarded, | |
dad92c30 OZ |
2010 | <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be |
2011 | returned with ICMP host unreachable / ICMP administratively prohibited | |
2012 | messages). Can be changed, but only to <cf/RTD_BLACKHOLE/, | |
2013 | <cf/RTD_UNREACHABLE/ or <cf/RTD_PROHIBIT/. | |
b74f45f8 | 2014 | |
b9864aa8 | 2015 | <tag><label id="rta-ifname"><m/string/ ifname</tag> |
dad92c30 OZ |
2016 | Name of the outgoing interface. Sink routes (like blackhole, unreachable |
2017 | or prohibit) and multipath routes have no interface associated with | |
f2d8e680 OZ |
2018 | them, so <cf/ifname/ returns an empty string for such routes. Setting it |
2019 | would also change route to a direct one (remove gateway). | |
a5fc5958 | 2020 | |
b9864aa8 | 2021 | <tag><label id="rta-ifindex"><m/int/ ifindex</tag> |
dad92c30 OZ |
2022 | Index of the outgoing interface. System wide index of the interface. May |
2023 | be used for interface matching, however indexes might change on interface | |
2024 | creation/removal. Zero is returned for routes with undefined outgoing | |
a5fc5958 OZ |
2025 | interfaces. Read-only. |
2026 | ||
7144c9ca RC |
2027 | <tag><label id="rta-onlink"><m/bool/ onlink</tag> |
2028 | Onlink flag means that the specified nexthop is accessible on the | |
2029 | interface regardless of IP prefixes configured on the interface. | |
2030 | The attribute can be used to configure such next hops by first setting | |
2031 | <cf/onlink = true/ and <cf/ifname/, and then setting <cf/gw/. Possible | |
2032 | use case for setting this flag is to automatically build overlay IP-IP | |
2033 | networks on linux. | |
2034 | ||
8cc5bb09 OZ |
2035 | <tag><label id="rta-weight"><m/int/ weight</tag> |
2036 | Multipath weight of route next hops. Valid values are 1-256. Reading | |
2037 | returns the weight of the first next hop, setting it sets weights of all | |
2038 | next hops to the specified value. Therefore, this attribute is not much | |
2039 | useful for manipulating individual next hops of an ECMP route, but can | |
2040 | be used in BGP multipath setup to set weights of individual routes that | |
2041 | are merged to one ECMP route during export to the Kernel protocol | |
2042 | (with active <ref id="krt-merge-paths" name="marge paths"> option). | |
2043 | ||
e5468d16 TB |
2044 | <tag><label id="rta-gw-mpls"><m/int/ gw_mpls</tag> |
2045 | Outgoing MPLS label attached to route (i.e., incoming MPLS label on the | |
2046 | next hop router for this label-switched path). Reading returns the label | |
2047 | value and setting it sets it to the start of the label stack. Setting | |
2048 | implicit-NULL label (3) disables the MPLS label stack. Only the first | |
2049 | next hop and only one label in the label stack supported right now. This | |
2050 | is experimental option, will be likely changed in the future to handle | |
2051 | full MPLS label stack. | |
2052 | ||
b9864aa8 | 2053 | <tag><label id="rta-igp-metric"><m/int/ igp_metric</tag> |
dad92c30 OZ |
2054 | The optional attribute that can be used to specify a distance to the |
2055 | network for routes that do not have a native protocol metric attribute | |
2056 | (like <cf/ospf_metric1/ for OSPF routes). It is used mainly by BGP to | |
feae132e | 2057 | compare internal distances to boundary routers (see below). |
8a708856 OZ |
2058 | |
2059 | <tag><label id="rta-mpls-label"><m/int/ mpls_label</tag> | |
2060 | Local MPLS label attached to the route. This attribute is produced by | |
2061 | MPLS-aware protocols for labeled routes. It can also be set in import | |
2062 | filters to assign static labels, but that also requires static MPLS | |
2063 | label policy. | |
2064 | ||
2065 | <tag><label id="rta-mpls-policy"><m/enum/ mpls_policy</tag> | |
2066 | For MPLS-aware protocols, this attribute defines which | |
2067 | <ref id="mpls-channel-label-policy" name="MPLS label policy"> will be | |
2068 | used for the route. It can be set in import filters to change it on | |
2069 | per-route basis. Valid values are <cf/MPLS_POLICY_NONE/ (no label), | |
2070 | <cf/MPLS_POLICY_STATIC/ (static label), <cf/MPLS_POLICY_PREFIX/ | |
2071 | (per-prefix label), <cf/MPLS_POLICY_AGGREGATE/ (aggregated label), | |
2072 | and <cf/MPLS_POLICY_VRF/ (per-VRF label). See <ref | |
2073 | id="mpls-channel-label-policy" name="MPLS label policy"> for details. | |
2074 | ||
2075 | <tag><label id="rta-mpls-class"><m/int/ mpls_class</tag> | |
2076 | When <ref id="mpls-channel-label-policy" name="MPLS label policy"> is | |
2077 | set to <cf/aggregate/, it may be useful to apply more fine-grained | |
2078 | aggregation than just one based on next hops. When routes have different | |
2079 | value of this attribute, they will not be aggregated under one local | |
2080 | label even if they have the same next hops. | |
ba1dda49 | 2081 | </descrip> |
0e5373fd | 2082 | |
3a22a6e8 OZ |
2083 | <p>Protocol-specific route attributes are described in the corresponding |
2084 | protocol sections. | |
dad92c30 | 2085 | |
0e5373fd | 2086 | |
1632f1fe | 2087 | <sect>Other statements |
b9864aa8 | 2088 | <label id="other-statements"> |
69477cad | 2089 | |
a7c9f7c0 | 2090 | <p>The following statements are available: |
69477cad PM |
2091 | |
2092 | <descrip> | |
b9864aa8 | 2093 | <tag><label id="assignment"><m/variable/ = <m/expr/</tag> |
3a22a6e8 | 2094 | Set variable (or route attribute) to a given value. |
326e33f5 | 2095 | |
b9864aa8 | 2096 | <tag><label id="filter-accept-reject">accept|reject [ <m/expr/ ]</tag> |
dad92c30 | 2097 | Accept or reject the route, possibly printing <cf><m>expr</m></cf>. |
326e33f5 | 2098 | |
b9864aa8 | 2099 | <tag><label id="return">return <m/expr/</tag> |
dad92c30 OZ |
2100 | Return <cf><m>expr</m></cf> from the current function, the function ends |
2101 | at this point. | |
326e33f5 | 2102 | |
b9864aa8 | 2103 | <tag><label id="print">print|printn <m/expr/ [<m/, expr.../]</tag> |
dad92c30 OZ |
2104 | Prints given expressions; useful mainly while debugging filters. The |
2105 | <cf/printn/ variant does not terminate the line. | |
69477cad PM |
2106 | </descrip> |
2107 | ||
dad92c30 | 2108 | |
371adba6 | 2109 | <chapt>Protocols |
b9864aa8 | 2110 | <label id="protocols"> |
d37f899b | 2111 | |
a4adb09f MM |
2112 | <sect>Aggregator |
2113 | <label id="aggregator"> | |
2114 | ||
2115 | <sect1>Introduction | |
2116 | <label id="aggregator-intro"> | |
2117 | <p>The Aggregator protocol explicitly merges routes by the given rules. There | |
2118 | are four phases of aggregation. First routes are filtered, then sorted into buckets, | |
2119 | then buckets are merged and finally the results are filtered once again. | |
2120 | Aggregating an already aggregated route is forbidden. | |
2121 | ||
2122 | <p>This is an experimental protocol, use with caution. | |
2123 | ||
2124 | <sect1>Configuration | |
2125 | <label id="aggregator-config"> | |
2126 | <p><descrip> | |
2127 | <tag><label id="aggregator-table">table <m/table/</tag> | |
2128 | The table from which routes are exported to get aggregated. | |
2129 | ||
2130 | <tag><label id="aggregator-export">export <m/.../</tag> | |
2131 | A standard channel's <cf/export/ clause, defining which routes are accepted into aggregation. | |
2132 | ||
2133 | <tag><label id="aggregator-rule">aggregate on <m/expr/ | <m/attribute/ [<m/, .../]</tag> | |
2134 | All the given filter expressions and route attributes are evaluated for each route. Then routes | |
2135 | are sorted into buckets where <em/all/ values are the same. Note: due to performance reasons, | |
2136 | all filter expressions must return a compact type, e.g. integer, a BGP | |
2137 | (standard, extended, large) community or an IP address. If you need to compare e.g. modified | |
2138 | AS Paths in the aggregation rule, you can define a custom route attribute and set this attribute | |
2139 | in the export filter. For now, it's mandatory to say <cf/net/ here, we can't merge prefixes yet. | |
2140 | ||
2141 | <tag><label id="aggregation-merge">merge by { <m/filter code/ }</tag> | |
2142 | The given filter code has an extra symbol defined: <cf/routes/. By iterating over <cf/routes/, | |
2143 | you get all the routes in the bucket and you can construct your new route. All attributes | |
2144 | selected in <cf/aggregate on/ are already set to the common values. For now, it's not possible | |
2145 | to use a named filter here. You have to finalize the route by calling <cf/accept/. | |
2146 | ||
2147 | <tag><label id="aggregator-import">import <m/.../</tag> | |
2148 | Filter applied to the route after <cf/merge by/. Here you can use a named filter. | |
2149 | ||
2150 | <tag><label id="aggregator-peer-table">peer table <m/table/</tag> | |
2151 | The table to which aggregated routes are imported. It may be the same table | |
2152 | as <cf/table/. | |
2153 | </descrip> | |
2154 | ||
2155 | <sect1>Example | |
2156 | <label id="aggregator-example"> | |
2157 | ||
2158 | <p><code> | |
2159 | protocol aggregator { | |
2160 | table master6; | |
2161 | export where defined(bgp_path); | |
2162 | /* Merge all routes with the same AS Path length */ | |
2163 | aggregate on net, bgp_path.len; | |
2164 | merge by { | |
2165 | for route r in routes do { | |
2166 | if ! defined(bgp_path) then { bgp_path = r.bgp_path } | |
2167 | bgp_community = bgp_community.add(r.bgp_community); | |
2168 | } | |
2169 | accept; | |
2170 | }; | |
2171 | import all; | |
2172 | peer table agr_result; | |
2173 | } | |
2174 | </code> | |
2175 | ||
937e75d8 | 2176 | <sect>Babel |
b9864aa8 | 2177 | <label id="babel"> |
937e75d8 OZ |
2178 | |
2179 | <sect1>Introduction | |
b9864aa8 | 2180 | <label id="babel-intro"> |
937e75d8 | 2181 | |
7935b9d2 | 2182 | <p>The Babel protocol |
501256cf | 2183 | (<rfc id="8966">) is a loop-avoiding distance-vector routing protocol that is |
7935b9d2 PT |
2184 | robust and efficient both in ordinary wired networks and in wireless mesh |
2185 | networks. Babel is conceptually very simple in its operation and "just works" | |
2186 | in its default configuration, though some configuration is possible and in some | |
2187 | cases desirable. | |
937e75d8 | 2188 | |
300bd0eb OZ |
2189 | <p>The Babel protocol is dual stack; i.e., it can carry both IPv4 and IPv6 |
2190 | routes over the same IPv6 transport. For sending and receiving Babel packets, | |
2191 | only a link-local IPv6 address is needed. | |
937e75d8 | 2192 | |
159d619c OZ |
2193 | <p>BIRD implements an extension for IPv6 source-specific routing (SSR or SADR), |
2194 | but must be configured accordingly to use it. SADR-enabled Babel router can | |
2195 | interoperate with non-SADR Babel router, but the later would ignore routes | |
2196 | with specific (non-zero) source prefix. | |
937e75d8 OZ |
2197 | |
2198 | <sect1>Configuration | |
b9864aa8 | 2199 | <label id="babel-config"> |
937e75d8 | 2200 | |
159d619c OZ |
2201 | <p>The Babel protocol support both IPv4 and IPv6 channels; both can be |
2202 | configured simultaneously. It can also be configured with <ref | |
2203 | id="ip-sadr-routes" name="IPv6 SADR"> channel instead of regular IPv6 | |
2204 | channel, in such case SADR support is enabled. Babel supports no global | |
2205 | configuration options apart from those common to all other protocols, but | |
2206 | supports the following per-interface configuration options: | |
937e75d8 OZ |
2207 | |
2208 | <code> | |
2209 | protocol babel [<name>] { | |
3e52d112 | 2210 | ipv4 { <channel config> }; |
159d619c | 2211 | ipv6 [sadr] { <channel config> }; |
70fab178 | 2212 | randomize router id <switch>; |
937e75d8 | 2213 | interface <interface pattern> { |
f08abcb8 | 2214 | type <wired|wireless|tunnel>; |
937e75d8 | 2215 | rxcost <number>; |
b47eaefe | 2216 | limit <number>; |
cf3e3845 OZ |
2217 | hello interval <time>; |
2218 | update interval <time>; | |
937e75d8 OZ |
2219 | port <number>; |
2220 | tx class|dscp <number>; | |
2221 | tx priority <number>; | |
2222 | rx buffer <number>; | |
2223 | tx length <number>; | |
2224 | check link <switch>; | |
300bd0eb OZ |
2225 | next hop ipv4 <address>; |
2226 | next hop ipv6 <address>; | |
eecc3f02 | 2227 | extended next hop <switch>; |
f08abcb8 THJ |
2228 | rtt cost <number>; |
2229 | rtt min <time>; | |
2230 | rtt max <time>; | |
2231 | rtt decay <number>; | |
2232 | send timestamps <switch>; | |
b218a28f THJ |
2233 | authentication none|mac [permissive]; |
2234 | password "<text>"; | |
2235 | password "<text>" { | |
2236 | id <num>; | |
2237 | generate from "<date>"; | |
2238 | generate to "<date>"; | |
2239 | accept from "<date>"; | |
2240 | accept to "<date>"; | |
2241 | from "<date>"; | |
2242 | to "<date>"; | |
b174cc0a OZ |
2243 | algorithm ( hmac sha1 | hmac sha256 | hmac sha384 | |
2244 | hmac sha512 | blake2s128 | blake2s256 | blake2b256 | blake2b512 ); | |
b218a28f | 2245 | }; |
937e75d8 OZ |
2246 | }; |
2247 | } | |
2248 | </code> | |
2249 | ||
2250 | <descrip> | |
159d619c OZ |
2251 | <tag><label id="babel-channel">ipv4 | ipv6 [sadr] <m/channel config/</tag> |
2252 | The supported channels are IPv4, IPv6, and IPv6 SADR. | |
3e52d112 | 2253 | |
70fab178 OZ |
2254 | <tag><label id="babel-random-router-id">randomize router id <m/switch/</tag> |
2255 | If enabled, Bird will randomize the top 32 bits of its router ID whenever | |
2256 | the protocol instance starts up. If a Babel node restarts, it loses its | |
2257 | sequence number, which can cause its routes to be rejected by peers until | |
2258 | the state is cleared out by other nodes in the network (which can take on | |
2259 | the order of minutes). Enabling this option causes Bird to pick a random | |
2260 | router ID every time it starts up, which avoids this problem at the cost | |
2261 | of not having stable router IDs in the network. Default: no. | |
2262 | ||
f08abcb8 THJ |
2263 | <tag><label id="babel-type">type wired|wireless|tunnel </tag> |
2264 | This option specifies the interface type: Wired, wireless or tunnel. On | |
2265 | wired interfaces a neighbor is considered unreachable after a small number | |
2266 | of Hello packets are lost, as described by <cf/limit/ option. On wireless | |
b47eaefe OZ |
2267 | interfaces the ETX link quality estimation technique is used to compute |
2268 | the metrics of routes discovered over this interface. This technique will | |
2269 | gradually degrade the metric of routes when packets are lost rather than | |
f08abcb8 THJ |
2270 | the more binary up/down mechanism of wired type links. A tunnel is like a |
2271 | wired interface, but turns on RTT-based metrics with a default cost of 96. | |
2272 | Default: <cf/wired/. | |
937e75d8 | 2273 | |
b9864aa8 | 2274 | <tag><label id="babel-rxcost">rxcost <m/num/</tag> |
b47eaefe OZ |
2275 | This option specifies the nominal RX cost of the interface. The effective |
2276 | neighbor costs for route metrics will be computed from this value with a | |
2277 | mechanism determined by the interface <cf/type/. Note that in contrast to | |
2278 | other routing protocols like RIP or OSPF, the <cf/rxcost/ specifies the | |
2279 | cost of RX instead of TX, so it affects primarily neighbors' route | |
2280 | selection and not local route selection. Default: 96 for wired interfaces, | |
2281 | 256 for wireless. | |
2282 | ||
2283 | <tag><label id="babel-limit">limit <m/num/</tag> | |
2284 | BIRD keeps track of received Hello messages from each neighbor to | |
2285 | establish neighbor reachability. For wired type interfaces, this option | |
2286 | specifies how many of last 16 hellos have to be correctly received in | |
2287 | order to neighbor is assumed to be up. The option is ignored on wireless | |
2288 | type interfaces, where gradual cost degradation is used instead of sharp | |
2289 | limit. Default: 12. | |
937e75d8 | 2290 | |
cf3e3845 | 2291 | <tag><label id="babel-hello">hello interval <m/time/ s|ms</tag> |
b47eaefe | 2292 | Interval at which periodic Hello messages are sent on this interface, |
cf3e3845 | 2293 | with time units. Default: 4 seconds. |
937e75d8 | 2294 | |
cf3e3845 OZ |
2295 | <tag><label id="babel-update">update interval <m/time/ s|ms</tag> |
2296 | Interval at which periodic (full) updates are sent, with time | |
2297 | units. Default: 4 times the hello interval. | |
937e75d8 | 2298 | |
b9864aa8 | 2299 | <tag><label id="babel-port">port <m/number/</tag> |
937e75d8 OZ |
2300 | This option selects an UDP port to operate on. The default is to operate |
2301 | on port 6696 as specified in the Babel RFC. | |
2302 | ||
b9864aa8 | 2303 | <tag><label id="babel-tx-class">tx class|dscp|priority <m/number/</tag> |
937e75d8 | 2304 | These options specify the ToS/DiffServ/Traffic class/Priority of the |
b9864aa8 | 2305 | outgoing Babel packets. See <ref id="proto-tx-class" name="tx class"> common |
937e75d8 OZ |
2306 | option for detailed description. |
2307 | ||
b9864aa8 | 2308 | <tag><label id="babel-rx-buffer">rx buffer <m/number/</tag> |
937e75d8 OZ |
2309 | This option specifies the size of buffers used for packet processing. |
2310 | The buffer size should be bigger than maximal size of received packets. | |
2311 | The default value is the interface MTU, and the value will be clamped to a | |
2312 | minimum of 512 bytes + IP packet overhead. | |
2313 | ||
b9864aa8 | 2314 | <tag><label id="babel-tx-length">tx length <m/number/</tag> |
937e75d8 OZ |
2315 | This option specifies the maximum length of generated Babel packets. To |
2316 | avoid IP fragmentation, it should not exceed the interface MTU value. | |
2317 | The default value is the interface MTU value, and the value will be | |
2318 | clamped to a minimum of 512 bytes + IP packet overhead. | |
2319 | ||
b9864aa8 | 2320 | <tag><label id="babel-check-link">check link <m/switch/</tag> |
937e75d8 OZ |
2321 | If set, the hardware link state (as reported by OS) is taken into |
2322 | consideration. When the link disappears (e.g. an ethernet cable is | |
2323 | unplugged), neighbors are immediately considered unreachable and all | |
2324 | routes received from them are withdrawn. It is possible that some | |
2325 | hardware drivers or platforms do not implement this feature. Default: | |
2326 | yes. | |
300bd0eb OZ |
2327 | |
2328 | <tag><label id="babel-next-hop-ipv4">next hop ipv4 <m/address/</tag> | |
2329 | Set the next hop address advertised for IPv4 routes advertised on this | |
cf3e3845 | 2330 | interface. Default: the preferred IPv4 address of the interface. |
300bd0eb OZ |
2331 | |
2332 | <tag><label id="babel-next-hop-ipv6">next hop ipv6 <m/address/</tag> | |
2333 | Set the next hop address advertised for IPv6 routes advertised on this | |
2334 | interface. If not set, the same link-local address that is used as the | |
2335 | source for Babel packets will be used. In normal operation, it should not | |
2336 | be necessary to set this option. | |
b218a28f | 2337 | |
eecc3f02 AR |
2338 | <tag><label id="babel-extended-next-hop">extended next hop <m/switch/</tag> |
2339 | If enabled, BIRD will accept and emit IPv4 routes with an IPv6 next | |
2340 | hop when IPv4 addresses are absent from the interface as described in | |
2341 | <rfc id="9229">. Default: yes. | |
2342 | ||
f08abcb8 THJ |
2343 | <tag><label id="babel-rtt-cost">rtt cost <m/number/</tag> |
2344 | The RTT-based cost that will be applied to all routes from each neighbour | |
2345 | based on the measured RTT to that neighbour. If this value is set, | |
2346 | timestamps will be included in generated Babel Hello and IHU messages, and | |
2347 | (if the neighbours also have timestamps enabled), the RTT to each | |
2348 | neighbour will be computed. An additional cost is added to a neighbour if | |
2349 | its RTT is above the <ref id="babel-rtt-min" name="rtt min"> value | |
2350 | configured on the interface. The added cost scales linearly from 0 up to | |
2351 | the RTT cost configured in this option; the full cost is applied if the | |
2352 | neighbour RTT reaches the RTT configured in the <ref id="babel-rtt-max" | |
2353 | name="rtt max"> option (and for all RTTs above this value). Default: 0 | |
2354 | (disabled), except for tunnel interfaces, where it is 96. | |
2355 | ||
2356 | <tag><label id="babel-rtt-min">rtt min <m/time/ s|ms</tag> | |
2357 | The minimum RTT above which the RTT cost will start to be applied (scaling | |
2358 | linearly from zero up to the full cost). Default: 10 ms | |
2359 | ||
2360 | <tag><label id="babel-rtt-max">rtt max <m/time/ s|ms</tag> | |
2361 | The maximum RTT above which the full RTT cost will start be applied. | |
2362 | Default: 120 ms | |
2363 | ||
2364 | <tag><label id="babel-rtt-decay">rtt decay <m/number/</tag> | |
2365 | The decay factor used for the exponentional moving average of the RTT | |
2366 | samples from each neighbour, in units of 1/256. Higher values discards old | |
2367 | RTT samples faster. Must be between 1 and 256. Default: 42 | |
2368 | ||
2369 | <tag><label id="babel-send-timestamps">send timestamps <m/switch/</tag> | |
2370 | Whether to send the timestamps used for RTT calculation on this interface. | |
2371 | Sending the timestamps enables peers to calculate an RTT to this node, | |
2372 | even if no RTT cost is applied to the route metrics. Default: yes. | |
2373 | ||
b218a28f THJ |
2374 | <tag><label id="babel-authentication">authentication none|mac [permissive]</tag> |
2375 | Selects authentication method to be used. <cf/none/ means that packets | |
2376 | are not authenticated at all, <cf/mac/ means MAC authentication is | |
2377 | performed as described in <rfc id="8967">. If MAC authentication is | |
2378 | selected, the <cf/permissive/ suffix can be used to select an operation | |
2379 | mode where outgoing packets are signed, but incoming packets will be | |
2380 | accepted even if they fail authentication. This can be useful for | |
2381 | incremental deployment of MAC authentication across a network. If MAC | |
2382 | authentication is selected, a key must be specified with the | |
2383 | <cf/password/ configuration option. Default: none. | |
2384 | ||
b174cc0a OZ |
2385 | <tag><label id="babel-password">password "<m/text/"</tag> |
2386 | Specifies a password used for authentication. See the <ref id="proto-pass" | |
b218a28f THJ |
2387 | name="password"> common option for a detailed description. The Babel |
2388 | protocol will only accept HMAC-based algorithms or one of the Blake | |
2389 | algorithms, and the length of the supplied password string must match the | |
2390 | key size used by the selected algorithm. | |
937e75d8 OZ |
2391 | </descrip> |
2392 | ||
12640c14 | 2393 | <sect1>Attributes |
b9864aa8 | 2394 | <label id="babel-attr"> |
12640c14 OZ |
2395 | |
2396 | <p>Babel defines just one attribute: the internal babel metric of the route. It | |
2397 | is exposed as the <cf/babel_metric/ attribute and has range from 1 to infinity | |
2398 | (65535). | |
2399 | ||
2400 | <sect1>Example | |
b9864aa8 | 2401 | <label id="babel-exam"> |
12640c14 OZ |
2402 | |
2403 | <p><code> | |
2404 | protocol babel { | |
2405 | interface "eth*" { | |
2406 | type wired; | |
2407 | }; | |
2408 | interface "wlan0", "wlan1" { | |
2409 | type wireless; | |
2410 | hello interval 1; | |
2411 | rxcost 512; | |
2412 | }; | |
2413 | interface "tap0"; | |
2414 | ||
2415 | # This matches the default of babeld: redistribute all addresses | |
2416 | # configured on local interfaces, plus re-distribute all routes received | |
2417 | # from other babel peers. | |
2418 | ||
300bd0eb OZ |
2419 | ipv4 { |
2420 | export where (source = RTS_DEVICE) || (source = RTS_BABEL); | |
2421 | }; | |
2422 | ipv6 { | |
2423 | export where (source = RTS_DEVICE) || (source = RTS_BABEL); | |
2424 | }; | |
12640c14 OZ |
2425 | } |
2426 | </code> | |
2427 | ||
3e52d112 JMM |
2428 | <sect1>Known issues |
2429 | <label id="babel-issues"> | |
2430 | ||
cf3e3845 OZ |
2431 | <p>When retracting a route, Babel generates an unreachable route for a little |
2432 | while (according to RFC). The interaction of this behavior with other protocols | |
2433 | is not well tested and strange things may happen. | |
2434 | ||
937e75d8 | 2435 | |
5bf35a9a | 2436 | <sect>BFD |
b9864aa8 | 2437 | <label id="bfd"> |
1ec52253 OZ |
2438 | |
2439 | <sect1>Introduction | |
b9864aa8 | 2440 | <label id="bfd-intro"> |
1ec52253 OZ |
2441 | |
2442 | <p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it | |
2443 | is an independent tool providing liveness and failure detection. Routing | |
2444 | protocols like OSPF and BGP use integrated periodic "hello" messages to monitor | |
2445 | liveness of neighbors, but detection times of these mechanisms are high (e.g. 40 | |
2446 | seconds by default in OSPF, could be set down to several seconds). BFD offers | |
2447 | universal, fast and low-overhead mechanism for failure detection, which could be | |
2448 | attached to any routing protocol in an advisory role. | |
2449 | ||
2450 | <p>BFD consists of mostly independent BFD sessions. Each session monitors an | |
2451 | unicast bidirectional path between two BFD-enabled routers. This is done by | |
2452 | periodically sending control packets in both directions. BFD does not handle | |
2453 | neighbor discovery, BFD sessions are created on demand by request of other | |
2454 | protocols (like OSPF or BGP), which supply appropriate information like IP | |
2455 | addresses and associated interfaces. When a session changes its state, these | |
2456 | protocols are notified and act accordingly (e.g. break an OSPF adjacency when | |
2457 | the BFD session went down). | |
2458 | ||
7935b9d2 PT |
2459 | <p>BIRD implements basic BFD behavior as defined in <rfc id="5880"> (some |
2460 | advanced features like the echo mode or authentication are not implemented), IP | |
2461 | transport for BFD as defined in <rfc id="5881"> and <rfc id="5883"> and | |
2462 | interaction with client protocols as defined in <rfc id="5882">. | |
1ec52253 | 2463 | |
d96ec7f6 OZ |
2464 | <p>BFD packets are sent with a dynamic source port number. Linux systems use by |
2465 | default a bit different dynamic port range than the IANA approved one | |
2466 | (49152-65535). If you experience problems with compatibility, please adjust | |
8c703ecf | 2467 | <cf>/proc/sys/net/ipv4/ip_local_port_range</cf>. |
d96ec7f6 | 2468 | |
1ec52253 | 2469 | <sect1>Configuration |
b9864aa8 | 2470 | <label id="bfd-config"> |
1ec52253 OZ |
2471 | |
2472 | <p>BFD configuration consists mainly of multiple definitions of interfaces. | |
2473 | Most BFD config options are session specific. When a new session is requested | |
2474 | and dynamically created, it is configured from one of these definitions. For | |
2475 | sessions to directly connected neighbors, <cf/interface/ definitions are chosen | |
2476 | based on the interface associated with the session, while <cf/multihop/ | |
2477 | definition is used for multihop sessions. If no definition is relevant, the | |
2478 | session is just created with the default configuration. Therefore, an empty BFD | |
2479 | configuration is often sufficient. | |
2480 | ||
2481 | <p>Note that to use BFD for other protocols like OSPF or BGP, these protocols | |
2482 | also have to be configured to request BFD sessions, usually by <cf/bfd/ option. | |
4a42e7e9 OZ |
2483 | In BGP case, it is also possible to specify per-peer BFD session options (e.g. |
2484 | rx/tx intervals) as a part of the <cf/bfd/ option. | |
1ec52253 | 2485 | |
8c703ecf OZ |
2486 | <p>A BFD instance not associated with any VRF handles session requests from all |
2487 | other protocols, even ones associated with a VRF. Such setup would work for | |
2488 | single-hop BFD sessions if <cf/net.ipv4.udp_l3mdev_accept/ sysctl is enabled, | |
2489 | but does not currently work for multihop sessions. Another approach is to | |
2490 | configure multiple BFD instances, one for each VRF (including the default VRF). | |
2491 | Each BFD instance associated with a VRF (regular or default) only handles | |
2492 | session requests from protocols in the same VRF. | |
2493 | ||
1ec52253 OZ |
2494 | <p>Some of BFD session options require <m/time/ value, which has to be specified |
2495 | with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds | |
2496 | are allowed as units, practical minimum values are usually in order of tens of | |
2497 | milliseconds. | |
2498 | ||
2499 | <code> | |
2500 | protocol bfd [<name>] { | |
7f9adafc | 2501 | accept [ipv4|ipv6] [direct|multihop]; |
1ec52253 OZ |
2502 | interface <interface pattern> { |
2503 | interval <time>; | |
2504 | min rx interval <time>; | |
2505 | min tx interval <time>; | |
2506 | idle tx interval <time>; | |
2507 | multiplier <num>; | |
2508 | passive <switch>; | |
e03dc6a9 OZ |
2509 | authentication none; |
2510 | authentication simple; | |
2511 | authentication [meticulous] keyed md5|sha1; | |
2512 | password "<text>"; | |
2513 | password "<text>" { | |
2514 | id <num>; | |
2515 | generate from "<date>"; | |
2516 | generate to "<date>"; | |
2517 | accept from "<date>"; | |
2518 | accept to "<date>"; | |
2519 | from "<date>"; | |
2520 | to "<date>"; | |
2521 | }; | |
1ec52253 OZ |
2522 | }; |
2523 | multihop { | |
2524 | interval <time>; | |
2525 | min rx interval <time>; | |
2526 | min tx interval <time>; | |
2527 | idle tx interval <time>; | |
2528 | multiplier <num>; | |
2529 | passive <switch>; | |
2530 | }; | |
2531 | neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>]; | |
2532 | } | |
2533 | </code> | |
2534 | ||
2535 | <descrip> | |
7f9adafc OZ |
2536 | <tag><label id="bfd-accept">accept [ipv4|ipv6] [direct|multihop]</tag> |
2537 | A BFD protocol instance accepts (by default) all BFD session requests | |
2538 | (with regard to VRF restrictions, see above). This option controls | |
2539 | whether IPv4 / IPv6 and direct / multihop session requests are accepted | |
2540 | (and which listening sockets are opened). It can be used, for example, | |
2541 | to configure separate BFD protocol instances for IPv4 and for IPv6 | |
2542 | sessions. | |
2543 | ||
692055e3 OZ |
2544 | <tag><label id="bfd-strict-bind">strict bind <m/switch/</tag> |
2545 | Specify whether each BFD interface should use a separate listening | |
2546 | socket bound to its local address, or just use a shared listening socket | |
2547 | accepting all addresses. Binding to a specific address could be useful | |
2548 | in cases like running multiple BIRD instances on a machine, each | |
2549 | handling a different set of interfaces. Default: disabled. | |
2550 | ||
9df52a98 | 2551 | <tag><label id="bfd-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag> |
1ec52253 OZ |
2552 | Interface definitions allow to specify options for sessions associated |
2553 | with such interfaces and also may contain interface specific options. | |
b9864aa8 | 2554 | See <ref id="proto-iface" name="interface"> common option for a detailed |
1ec52253 OZ |
2555 | description of interface patterns. Note that contrary to the behavior of |
2556 | <cf/interface/ definitions of other protocols, BFD protocol would accept | |
2557 | sessions (in default configuration) even on interfaces not covered by | |
2558 | such definitions. | |
2559 | ||
b9864aa8 | 2560 | <tag><label id="bfd-multihop">multihop { <m/options/ }</tag> |
1ec52253 OZ |
2561 | Multihop definitions allow to specify options for multihop BFD sessions, |
2562 | in the same manner as <cf/interface/ definitions are used for directly | |
2563 | connected sessions. Currently only one such definition (for all multihop | |
2564 | sessions) could be used. | |
2565 | ||
b9864aa8 | 2566 | <tag><label id="bfd-neighbor">neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag> |
1ec52253 OZ |
2567 | BFD sessions are usually created on demand as requested by other |
2568 | protocols (like OSPF or BGP). This option allows to explicitly add | |
2569 | a BFD session to the specified neighbor regardless of such requests. | |
523f020b | 2570 | |
1ec52253 | 2571 | The session is identified by the IP address of the neighbor, with |
dad92c30 | 2572 | optional specification of used interface and local IP. By default |
fff7498d | 2573 | the neighbor must be directly connected, unless the session is |
1ec52253 OZ |
2574 | configured as multihop. Note that local IP must be specified for |
2575 | multihop sessions. | |
2576 | </descrip> | |
2577 | ||
2578 | <p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions): | |
2579 | ||
2580 | <descrip> | |
b9864aa8 | 2581 | <tag><label id="bfd-interval">interval <m/time/</tag> |
1ec52253 OZ |
2582 | BFD ensures availability of the forwarding path associated with the |
2583 | session by periodically sending BFD control packets in both | |
2584 | directions. The rate of such packets is controlled by two options, | |
2585 | <cf/min rx interval/ and <cf/min tx interval/ (see below). This option | |
2586 | is just a shorthand to set both of these options together. | |
2587 | ||
b9864aa8 | 2588 | <tag><label id="bfd-min-rx-interval">min rx interval <m/time/</tag> |
1ec52253 OZ |
2589 | This option specifies the minimum RX interval, which is announced to the |
2590 | neighbor and used there to limit the neighbor's rate of generated BFD | |
2591 | control packets. Default: 10 ms. | |
2592 | ||
b9864aa8 | 2593 | <tag><label id="bfd-min-tx-interval">min tx interval <m/time/</tag> |
1ec52253 OZ |
2594 | This option specifies the desired TX interval, which controls the rate |
2595 | of generated BFD control packets (together with <cf/min rx interval/ | |
2596 | announced by the neighbor). Note that this value is used only if the BFD | |
2597 | session is up, otherwise the value of <cf/idle tx interval/ is used | |
2598 | instead. Default: 100 ms. | |
2599 | ||
b9864aa8 | 2600 | <tag><label id="bfd-idle-tx-interval">idle tx interval <m/time/</tag> |
1ec52253 OZ |
2601 | In order to limit unnecessary traffic in cases where a neighbor is not |
2602 | available or not running BFD, the rate of generated BFD control packets | |
2603 | is lower when the BFD session is not up. This option specifies the | |
2604 | desired TX interval in such cases instead of <cf/min tx interval/. | |
2605 | Default: 1 s. | |
2606 | ||
b9864aa8 | 2607 | <tag><label id="bfd-multiplier">multiplier <m/num/</tag> |
1ec52253 OZ |
2608 | Failure detection time for BFD sessions is based on established rate of |
2609 | BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this | |
2610 | multiplier, which is essentially (ignoring jitter) a number of missed | |
2611 | packets after which the session is declared down. Note that rates and | |
2612 | multipliers could be different in each direction of a BFD session. | |
2613 | Default: 5. | |
2614 | ||
b9864aa8 | 2615 | <tag><label id="bfd-passive">passive <m/switch/</tag> |
fff7498d | 2616 | Generally, both BFD session endpoints try to establish the session by |
1ec52253 OZ |
2617 | sending control packets to the other side. This option allows to enable |
2618 | passive mode, which means that the router does not send BFD packets | |
2619 | until it has received one from the other side. Default: disabled. | |
e03dc6a9 OZ |
2620 | |
2621 | <tag>authentication none</tag> | |
2622 | No passwords are sent in BFD packets. This is the default value. | |
2623 | ||
2624 | <tag>authentication simple</tag> | |
2625 | Every packet carries 16 bytes of password. Received packets lacking this | |
2626 | password are ignored. This authentication mechanism is very weak. | |
2627 | ||
2628 | <tag>authentication [meticulous] keyed md5|sha1</tag> | |
2629 | An authentication code is appended to each packet. The cryptographic | |
2630 | algorithm is keyed MD5 or keyed SHA-1. Note that the algorithm is common | |
2631 | for all keys (on one interface), in contrast to OSPF or RIP, where it | |
2632 | is a per-key option. Passwords (keys) are not sent open via network. | |
2633 | ||
2634 | The <cf/meticulous/ variant means that cryptographic sequence numbers | |
2635 | are increased for each sent packet, while in the basic variant they are | |
2636 | increased about once per second. Generally, the <cf/meticulous/ variant | |
2637 | offers better resistance to replay attacks but may require more | |
2638 | computation. | |
2639 | ||
2640 | <tag>password "<M>text</M>"</tag> | |
7e8d6116 | 2641 | Specifies a password used for authentication. See <ref id="proto-pass" |
e03dc6a9 OZ |
2642 | name="password"> common option for detailed description. Note that |
2643 | password option <cf/algorithm/ is not available in BFD protocol. The | |
2644 | algorithm is selected by <cf/authentication/ option for all passwords. | |
2645 | ||
1ec52253 OZ |
2646 | </descrip> |
2647 | ||
2648 | <sect1>Example | |
b9864aa8 | 2649 | <label id="bfd-exam"> |
1ec52253 OZ |
2650 | |
2651 | <p><code> | |
2652 | protocol bfd { | |
2653 | interface "eth*" { | |
2654 | min rx interval 20 ms; | |
2655 | min tx interval 50 ms; | |
2656 | idle tx interval 300 ms; | |
2657 | }; | |
2658 | interface "gre*" { | |
2659 | interval 200 ms; | |
2660 | multiplier 10; | |
2661 | passive; | |
2662 | }; | |
2663 | multihop { | |
2664 | interval 200 ms; | |
2665 | multiplier 10; | |
2666 | }; | |
2667 | ||
2668 | neighbor 192.168.1.10; | |
2669 | neighbor 192.168.2.2 dev "eth2"; | |
2670 | neighbor 192.168.10.1 local 192.168.1.1 multihop; | |
2671 | } | |
2672 | </code> | |
2673 | ||
dad92c30 | 2674 | |
371adba6 | 2675 | <sect>BGP |
b9864aa8 | 2676 | <label id="bgp"> |
1b55b1a3 | 2677 | |
dad92c30 OZ |
2678 | <p>The Border Gateway Protocol is the routing protocol used for backbone level |
2679 | routing in the today's Internet. Contrary to other protocols, its convergence | |
2680 | does not rely on all routers following the same rules for route selection, | |
2681 | making it possible to implement any routing policy at any router in the network, | |
2682 | the only restriction being that if a router advertises a route, it must accept | |
2683 | and forward packets according to it. | |
2684 | ||
2685 | <p>BGP works in terms of autonomous systems (often abbreviated as AS). Each AS | |
2686 | is a part of the network with common management and common routing policy. It is | |
2687 | identified by a unique 16-bit number (ASN). Routers within each AS usually | |
2688 | exchange AS-internal routing information with each other using an interior | |
2689 | gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of | |
2690 | the AS communicate global (inter-AS) network reachability information with their | |
2691 | neighbors in the neighboring AS'es via exterior BGP (eBGP) and redistribute | |
2692 | received information to other routers in the AS via interior BGP (iBGP). | |
2693 | ||
2694 | <p>Each BGP router sends to its neighbors updates of the parts of its routing | |
2695 | table it wishes to export along with complete path information (a list of AS'es | |
2696 | the packet will travel through if it uses the particular route) in order to | |
2697 | avoid routing loops. | |
56ab03c7 | 2698 | |
71c51aa4 | 2699 | <sect1>Supported standards |
c49e4a65 OZ |
2700 | <label id="bgp-standards"> |
2701 | ||
71c51aa4 | 2702 | <p> |
c49e4a65 OZ |
2703 | <itemize> |
2704 | <item> <rfc id="4271"> - Border Gateway Protocol 4 (BGP) | |
2705 | <item> <rfc id="1997"> - BGP Communities Attribute | |
2706 | <item> <rfc id="2385"> - Protection of BGP Sessions via TCP MD5 Signature | |
2707 | <item> <rfc id="2545"> - Use of BGP Multiprotocol Extensions for IPv6 | |
2708 | <item> <rfc id="2918"> - Route Refresh Capability | |
2709 | <item> <rfc id="3107"> - Carrying Label Information in BGP | |
2710 | <item> <rfc id="4360"> - BGP Extended Communities Attribute | |
2711 | <item> <rfc id="4364"> - BGP/MPLS IPv4 Virtual Private Networks | |
2712 | <item> <rfc id="4456"> - BGP Route Reflection | |
2713 | <item> <rfc id="4486"> - Subcodes for BGP Cease Notification Message | |
2714 | <item> <rfc id="4659"> - BGP/MPLS IPv6 Virtual Private Networks | |
2715 | <item> <rfc id="4724"> - Graceful Restart Mechanism for BGP | |
2716 | <item> <rfc id="4760"> - Multiprotocol extensions for BGP | |
2717 | <item> <rfc id="4798"> - Connecting IPv6 Islands over IPv4 MPLS | |
2718 | <item> <rfc id="5065"> - AS confederations for BGP | |
2719 | <item> <rfc id="5082"> - Generalized TTL Security Mechanism | |
2720 | <item> <rfc id="5492"> - Capabilities Advertisement with BGP | |
c49e4a65 OZ |
2721 | <item> <rfc id="5575"> - Dissemination of Flow Specification Rules |
2722 | <item> <rfc id="5668"> - 4-Octet AS Specific BGP Extended Community | |
2723 | <item> <rfc id="6286"> - AS-Wide Unique BGP Identifier | |
2724 | <item> <rfc id="6608"> - Subcodes for BGP Finite State Machine Error | |
2725 | <item> <rfc id="6793"> - BGP Support for 4-Octet AS Numbers | |
09ee846d | 2726 | <item> <rfc id="7311"> - Accumulated IGP Metric Attribute for BGP |
c49e4a65 OZ |
2727 | <item> <rfc id="7313"> - Enhanced Route Refresh Capability for BGP |
2728 | <item> <rfc id="7606"> - Revised Error Handling for BGP UPDATE Messages | |
2729 | <item> <rfc id="7911"> - Advertisement of Multiple Paths in BGP | |
2730 | <item> <rfc id="7947"> - Internet Exchange BGP Route Server | |
2731 | <item> <rfc id="8092"> - BGP Large Communities Attribute | |
7fc55925 | 2732 | <item> <rfc id="8203"> - BGP Administrative Shutdown Communication |
3831b619 | 2733 | <item> <rfc id="8212"> - Default EBGP Route Propagation Behavior without Policies |
913ec57f | 2734 | <item> <rfc id="8654"> - Extended Message Support for BGP |
9bf20484 | 2735 | <item> <rfc id="8950"> - Advertising IPv4 NLRI with an IPv6 Next Hop |
913ec57f | 2736 | <item> <rfc id="9072"> - Extended Optional Parameters Length for BGP OPEN Message |
1f2eb2ac | 2737 | <item> <rfc id="9117"> - Revised Validation Procedure for BGP Flow Specifications |
c73b5d2d | 2738 | <item> <rfc id="9234"> - Route Leak Prevention and Detection Using Roles |
c49e4a65 | 2739 | </itemize> |
5459fac6 | 2740 | |
371adba6 | 2741 | <sect1>Route selection rules |
b9864aa8 | 2742 | <label id="bgp-route-select-rules"> |
5459fac6 MM |
2743 | |
2744 | <p>BGP doesn't have any simple metric, so the rules for selection of an optimal | |
2745 | route among multiple BGP routes with the same preference are a bit more complex | |
dad92c30 OZ |
2746 | and they are implemented according to the following algorithm. It starts the |
2747 | first rule, if there are more "best" routes, then it uses the second rule to | |
2748 | choose among them and so on. | |
5459fac6 MM |
2749 | |
2750 | <itemize> | |
5a203dac | 2751 | <item>Prefer route with the highest Local Preference attribute. |
5459fac6 | 2752 | <item>Prefer route with the shortest AS path. |
b74f45f8 | 2753 | <item>Prefer IGP origin over EGP and EGP origin over incomplete. |
5459fac6 | 2754 | <item>Prefer the lowest value of the Multiple Exit Discriminator. |
b74f45f8 OZ |
2755 | <item>Prefer routes received via eBGP over ones received via iBGP. |
2756 | <item>Prefer routes with lower internal distance to a boundary router. | |
5a203dac | 2757 | <item>Prefer the route with the lowest value of router ID of the |
5459fac6 MM |
2758 | advertising router. |
2759 | </itemize> | |
56ab03c7 | 2760 | |
b74f45f8 | 2761 | <sect1>IGP routing table |
b9864aa8 | 2762 | <label id="bgp-igp-routing-table"> |
b74f45f8 | 2763 | |
dad92c30 OZ |
2764 | <p>BGP is mainly concerned with global network reachability and with routes to |
2765 | other autonomous systems. When such routes are redistributed to routers in the | |
2766 | AS via BGP, they contain IP addresses of a boundary routers (in route attribute | |
2767 | NEXT_HOP). BGP depends on existing IGP routing table with AS-internal routes to | |
2768 | determine immediate next hops for routes and to know their internal distances to | |
2769 | boundary routers for the purpose of BGP route selection. In BIRD, there is | |
2770 | usually one routing table used for both IGP routes and BGP routes. | |
b74f45f8 | 2771 | |
3e52d112 JMM |
2772 | <sect1>Protocol configuration |
2773 | <label id="bgp-proto-config"> | |
56ab03c7 | 2774 | |
dad92c30 OZ |
2775 | <p>Each instance of the BGP corresponds to one neighboring router. This allows |
2776 | to set routing policy and all the other parameters differently for each neighbor | |
2777 | using the following configuration parameters: | |
5459fac6 MM |
2778 | |
2779 | <descrip> | |
7a8ae228 | 2780 | <tag><label id="bgp-local">local [<m/ip/] [port <m/number/] [as <m/number/]</tag> |
dad92c30 OZ |
2781 | Define which AS we are part of. (Note that contrary to other IP routers, |
2782 | BIRD is able to act as a router located in multiple AS'es simultaneously, | |
2783 | but in such cases you need to tweak the BGP paths manually in the filters | |
2784 | to get consistent behavior.) Optional <cf/ip/ argument specifies a source | |
7a8ae228 | 2785 | address, equivalent to the <cf/source address/ option (see below). |
159d619c | 2786 | Optional <cf/port/ argument specifies the local BGP port instead of |
7a8ae228 OZ |
2787 | standard port 179. The parameter may be used multiple times with |
2788 | different sub-options (e.g., both <cf/local 10.0.0.1 as 65000;/ and | |
2789 | <cf/local 10.0.0.1; local as 65000;/ are valid). This parameter is | |
2790 | mandatory. | |
f3e59178 | 2791 | |
dbbe4a78 | 2792 | <tag><label id="bgp-neighbor">neighbor [<m/ip/ | range <m/prefix/] [port <m/number/] [as <m/number/] [internal|external]</tag> |
dad92c30 | 2793 | Define neighboring router this instance will be talking to and what AS |
a1beb8f3 | 2794 | it is located in. In case the neighbor is in the same AS as we are, we |
23ee6b1c | 2795 | automatically switch to IBGP. Alternatively, it is possible to specify |
96e4d096 | 2796 | just <cf/internal/ or <cf/external/ instead of AS number, in that case |
23ee6b1c OZ |
2797 | either local AS number, or any external AS number is accepted. |
2798 | Optionally, the remote port may also be specified. Like <cf/local/ | |
2799 | parameter, this parameter may also be used multiple times with different | |
2800 | sub-options. This parameter is mandatory. | |
a1beb8f3 | 2801 | |
dbbe4a78 OZ |
2802 | It is possible to specify network prefix (with <cf/range/ keyword) |
2803 | instead of explicit neighbor IP address. This enables dynamic BGP | |
2804 | behavior, where the BGP instance listens on BGP port, but new BGP | |
2805 | instances are spawned for incoming BGP connections (if source address | |
2806 | matches the network prefix). It is possible to mix regular BGP instances | |
2807 | with dynamic BGP instances and have multiple dynamic BGP instances with | |
2808 | different ranges. | |
2809 | ||
b9864aa8 | 2810 | <tag><label id="bgp-iface">interface <m/string/</tag> |
a1beb8f3 OZ |
2811 | Define interface we should use for link-local BGP IPv6 sessions. |
2812 | Interface can also be specified as a part of <cf/neighbor address/ | |
33b6c292 OZ |
2813 | (e.g., <cf/neighbor fe80::1234%eth0 as 65000;/). The option may also be |
2814 | used for non link-local sessions when it is necessary to explicitly | |
2815 | specify an interface, but only for direct (not multihop) sessions. | |
dad92c30 | 2816 | |
b9864aa8 | 2817 | <tag><label id="bgp-direct">direct</tag> |
dad92c30 OZ |
2818 | Specify that the neighbor is directly connected. The IP address of the |
2819 | neighbor must be from a directly reachable IP range (i.e. associated | |
2820 | with one of your router's interfaces), otherwise the BGP session | |
2821 | wouldn't start but it would wait for such interface to appear. The | |
2822 | alternative is the <cf/multihop/ option. Default: enabled for eBGP. | |
2823 | ||
b9864aa8 | 2824 | <tag><label id="bgp-multihop">multihop [<m/number/]</tag> |
dad92c30 OZ |
2825 | Configure multihop BGP session to a neighbor that isn't directly |
2826 | connected. Accurately, this option should be used if the configured | |
2827 | neighbor IP address does not match with any local network subnets. Such | |
2828 | IP address have to be reachable through system routing table. The | |
2829 | alternative is the <cf/direct/ option. For multihop BGP it is | |
2830 | recommended to explicitly configure the source address to have it | |
2831 | stable. Optional <cf/number/ argument can be used to specify the number | |
2832 | of hops (used for TTL). Note that the number of networks (edges) in a | |
2833 | path is counted; i.e., if two BGP speakers are separated by one router, | |
2834 | the number of hops is 2. Default: enabled for iBGP. | |
2835 | ||
b9864aa8 | 2836 | <tag><label id="bgp-source-address">source address <m/ip/</tag> |
1cab2b4a OZ |
2837 | Define local address we should use as a source address for the BGP |
2838 | session. Default: the address of the local end of the interface our | |
2839 | neighbor is connected to. | |
9be9a264 | 2840 | |
dbbe4a78 OZ |
2841 | <tag><label id="bgp-dynamic-name">dynamic name "<m/text/"</tag> |
2842 | Define common prefix of names used for new BGP instances spawned when | |
e840cb9c | 2843 | dynamic BGP behavior is active. Actual names also contain numeric |
dbbe4a78 OZ |
2844 | index to distinguish individual instances. Default: "dynbgp". |
2845 | ||
96e4d096 | 2846 | <tag><label id="bgp-dynamic-name-digits">dynamic name digits <m/number/</tag> |
dbbe4a78 OZ |
2847 | Define minimum number of digits for index in names of spawned dynamic |
2848 | BGP instances. E.g., if set to 2, then the first name would be | |
2849 | "dynbgp01". Default: 0. | |
2850 | ||
82f42ea0 OZ |
2851 | <tag><label id="bgp-strict-bind">strict bind <m/switch/</tag> |
2852 | Specify whether BGP listening socket should be bound to a specific local | |
2853 | address (the same as the <cf/source address/) and associated interface, | |
2854 | or to all addresses. Binding to a specific address could be useful in | |
2855 | cases like running multiple BIRD instances on a machine, each using its | |
2856 | IP address. Note that listening sockets bound to a specific address and | |
2857 | to all addresses collide, therefore either all BGP protocols (of the | |
2858 | same address family and using the same local port) should have set | |
2859 | <cf/strict bind/, or none of them. Default: disabled. | |
2860 | ||
60e9def9 OZ |
2861 | <tag><label id="bgp-free-bind">free bind <m/switch/</tag> |
2862 | Use IP_FREEBIND socket option for the listening socket, which allows | |
2863 | binding to an IP address not (yet) assigned to an interface. Note that | |
2864 | all BGP instances that share a listening socket should have the same | |
2865 | value of the <cf/freebind/ option. Default: disabled. | |
2866 | ||
b9864aa8 | 2867 | <tag><label id="bgp-check-link">check link <M>switch</M></tag> |
523f020b OZ |
2868 | BGP could use hardware link state into consideration. If enabled, |
2869 | BIRD tracks the link state of the associated interface and when link | |
2870 | disappears (e.g. an ethernet cable is unplugged), the BGP session is | |
2871 | immediately shut down. Note that this option cannot be used with | |
cf3e3845 | 2872 | multihop BGP. Default: enabled for direct BGP, disabled otherwise. |
523f020b | 2873 | |
4a42e7e9 | 2874 | <tag><label id="bgp-bfd">bfd <M>switch</M>|graceful| { <m/options/ }</tag> |
1ec52253 OZ |
2875 | BGP could use BFD protocol as an advisory mechanism for neighbor |
2876 | liveness and failure detection. If enabled, BIRD setups a BFD session | |
2877 | for the BGP neighbor and tracks its liveness by it. This has an | |
2878 | advantage of an order of magnitude lower detection times in case of | |
5bd73431 OZ |
2879 | failure. When a neighbor failure is detected, the BGP session is |
2880 | restarted. Optionally, it can be configured (by <cf/graceful/ argument) | |
4a42e7e9 OZ |
2881 | to trigger graceful restart instead of regular restart. It is also |
2882 | possible to specify section with per-peer BFD session options instead of | |
d0512ba7 OZ |
2883 | just the switch argument. All BFD session-specific options are allowed |
2884 | here. Note that BFD protocol also has to be configured, see | |
2885 | <ref id="bfd" name="BFD"> section for details. Default: disabled. | |
1ec52253 | 2886 | |
b9864aa8 | 2887 | <tag><label id="bgp-ttl-security">ttl security <m/switch/</tag> |
7935b9d2 PT |
2888 | Use GTSM (<rfc id="5082"> - the generalized TTL security mechanism). GTSM |
2889 | protects against spoofed packets by ignoring received packets with a | |
dad92c30 | 2890 | smaller than expected TTL. To work properly, GTSM have to be enabled on |
7935b9d2 PT |
2891 | both sides of a BGP session. If both <cf/ttl security/ and |
2892 | <cf/multihop/ options are enabled, <cf/multihop/ option should specify | |
2893 | proper hop value to compute expected TTL. Kernel support required: | |
2894 | Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only. | |
2895 | Note that full (ICMP protection, for example) <rfc id="5082"> support is | |
2896 | provided by Linux only. Default: disabled. | |
523f020b | 2897 | |
82f42ea0 | 2898 | <tag><label id="bgp-password">password <m/string/</tag> |
7935b9d2 PT |
2899 | Use this password for MD5 authentication of BGP sessions (<rfc id="2385">). When |
2900 | used on BSD systems, see also <cf/setkey/ option below. Default: no | |
2901 | authentication. | |
a7baa098 | 2902 | |
b9864aa8 | 2903 | <tag><label id="bgp-setkey">setkey <m/switch/</tag> |
a7baa098 OZ |
2904 | On BSD systems, keys for TCP MD5 authentication are stored in the global |
2905 | SA/SP database, which can be accessed by external utilities (e.g. | |
2906 | setkey(8)). BIRD configures security associations in the SA/SP database | |
2907 | automatically based on <cf/password/ options (see above), this option | |
2908 | allows to disable automatic updates by BIRD when manual configuration by | |
2909 | external utilities is preferred. Note that automatic SA/SP database | |
2910 | updates are currently implemented only for FreeBSD. Passwords have to be | |
2911 | set manually by an external utility on NetBSD and OpenBSD. Default: | |
2912 | enabled (ignored on non-FreeBSD). | |
dad92c30 | 2913 | |
b9864aa8 | 2914 | <tag><label id="bgp-passive">passive <m/switch/</tag> |
dad92c30 | 2915 | Standard BGP behavior is both initiating outgoing connections and |
7935b9d2 | 2916 | accepting incoming connections. In passive mode, outgoing connections |
dad92c30 OZ |
2917 | are not initiated. Default: off. |
2918 | ||
5509e17d OZ |
2919 | <tag><label id="bgp-confederation">confederation <m/number/</tag> |
2920 | BGP confederations (<rfc id="5065">) are collections of autonomous | |
2921 | systems that act as one entity to external systems, represented by one | |
2922 | confederation identifier (instead of AS numbers). This option allows to | |
2923 | enable BGP confederation behavior and to specify the local confederation | |
2924 | identifier. When BGP confederations are used, all BGP speakers that are | |
2925 | members of the BGP confederation should have the same confederation | |
2926 | identifier configured. Default: 0 (no confederation). | |
2927 | ||
2928 | <tag><label id="bgp-confederation-member">confederation member <m/switch/</tag> | |
2929 | When BGP confederations are used, this option allows to specify whether | |
2930 | the BGP neighbor is a member of the same confederation as the local BGP | |
2931 | speaker. The option is unnecessary (and ignored) for IBGP sessions, as | |
2932 | the same AS number implies the same confederation. Default: no. | |
2933 | ||
b9864aa8 | 2934 | <tag><label id="bgp-rr-client">rr client</tag> |
dad92c30 OZ |
2935 | Be a route reflector and treat the neighbor as a route reflection |
2936 | client. Default: disabled. | |
2937 | ||
b9864aa8 | 2938 | <tag><label id="bgp-rr-cluster-id">rr cluster id <m/IPv4 address/</tag> |
dad92c30 OZ |
2939 | Route reflectors use cluster id to avoid route reflection loops. When |
2940 | there is one route reflector in a cluster it usually uses its router id | |
2941 | as a cluster id, but when there are more route reflectors in a cluster, | |
2942 | these need to be configured (using this option) to use a common cluster | |
2943 | id. Clients in a cluster need not know their cluster id and this option | |
2944 | is not allowed for them. Default: the same as router id. | |
2945 | ||
b9864aa8 | 2946 | <tag><label id="bgp-rs-client">rs client</tag> |
dad92c30 OZ |
2947 | Be a route server and treat the neighbor as a route server client. |
2948 | A route server is used as a replacement for full mesh EBGP routing in | |
2949 | Internet exchange points in a similar way to route reflectors used in | |
7935b9d2 PT |
2950 | IBGP routing. BIRD does not implement obsoleted <rfc id="1863">, but |
2951 | uses ad-hoc implementation, which behaves like plain EBGP but reduces | |
dad92c30 | 2952 | modifications to advertised route attributes to be transparent (for |
7935b9d2 PT |
2953 | example does not prepend its AS number to AS PATH attribute and |
2954 | keeps MED attribute). Default: disabled. | |
dad92c30 | 2955 | |
1950a479 | 2956 | <tag><label id="bgp-allow-local-pref">allow bgp_local_pref <m/switch/</tag> |
9e44ace3 TB |
2957 | Standard BGP implementations do not send the Local Preference attribute |
2958 | to EBGP neighbors and ignore this attribute if received from EBGP | |
1950a479 | 2959 | neighbors, as per <rfc id="4271">. When this option is enabled on an |
9e44ace3 | 2960 | EBGP session, this attribute will be sent to and accepted from the peer, |
1950a479 | 2961 | which is useful for example if you have a setup like in <rfc id="7938">. |
9e44ace3 TB |
2962 | The option does not affect IBGP sessions. Default: off. |
2963 | ||
2964 | <tag><label id="bgp-allow-med">allow bgp_med <m/switch/</tag> | |
2965 | Standard BGP implementations do not propagate the MULTI_EXIT_DESC | |
2966 | attribute unless it is configured locally. When this option is enabled | |
2967 | on an EBGP session, this attribute will be sent to the peer regardless, | |
2968 | which is useful for example if you have a setup like in <rfc id="7938">. | |
2969 | The option does not affect IBGP sessions. Default: off. | |
1950a479 | 2970 | |
b9864aa8 | 2971 | <tag><label id="bgp-allow-local-as">allow local as [<m/number/]</tag> |
dad92c30 OZ |
2972 | BGP prevents routing loops by rejecting received routes with the local |
2973 | AS number in the AS path. This option allows to loose or disable the | |
2974 | check. Optional <cf/number/ argument can be used to specify the maximum | |
2975 | number of local ASNs in the AS path that is allowed for received | |
2976 | routes. When the option is used without the argument, the check is | |
2977 | completely disabled and you should ensure loop-free behavior by some | |
2978 | other means. Default: 0 (no local AS number allowed). | |
2979 | ||
d54a69ac OZ |
2980 | <tag><label id="bgp-allow-as-sets">allow as sets [<m/switch/]</tag> |
2981 | AS path attribute received with BGP routes may contain not only | |
2982 | sequences of AS numbers, but also sets of AS numbers. These rarely used | |
2983 | artifacts are results of inter-AS route aggregation. AS sets are | |
2984 | deprecated (<rfc id="6472">), and likely to be rejected in the future, | |
2985 | as they complicate security features like RPKI validation. When this | |
2986 | option is disabled, then received AS paths with AS sets are rejected as | |
2987 | malformed and corresponding BGP updates are treated as withdraws. | |
becda563 | 2988 | Default: on. |
d54a69ac | 2989 | |
0b228fca OZ |
2990 | <tag><label id="bgp-enforce-first-as">enforce first as [<m/switch/]</tag> |
2991 | Routes received from an EBGP neighbor are generally expected to have the | |
2992 | first (leftmost) AS number in their AS path equal to the neighbor AS | |
2993 | number. This is not enforced by default as there are legitimate cases | |
2994 | where it is not true, e.g. connections to route servers. When this | |
2995 | option is enabled, routes with non-matching first AS number are rejected | |
2996 | and corresponding updates are treated as withdraws. The option is valid | |
2997 | on EBGP sessions only. Default: off. | |
2998 | ||
b9864aa8 | 2999 | <tag><label id="bgp-enable-route-refresh">enable route refresh <m/switch/</tag> |
9aed29e6 OZ |
3000 | After the initial route exchange, BGP protocol uses incremental updates |
3001 | to keep BGP speakers synchronized. Sometimes (e.g., if BGP speaker | |
3002 | changes its import filter, or if there is suspicion of inconsistency) it | |
3003 | is necessary to do a new complete route exchange. BGP protocol extension | |
7935b9d2 | 3004 | Route Refresh (<rfc id="2918">) allows BGP speaker to request |
8ad9c4bb MM |
3005 | re-advertisement of all routes from its neighbor. This option |
3006 | specifies whether BIRD advertises this capability and supports | |
7935b9d2 | 3007 | related procedures. Note that even when disabled, BIRD can send route |
8ad9c4bb MM |
3008 | refresh requests. Disabling Route Refresh also disables Enhanced Route Refresh. |
3009 | Default: on. | |
3010 | ||
3fb06fea OZ |
3011 | <tag><label id="bgp-require-route-refresh">require route refresh <m/switch/</tag> |
3012 | If enabled, the BGP Route Refresh capability (<rfc id="2918">) must be | |
3013 | announced by the BGP neighbor, otherwise the BGP session will not be | |
3014 | established. Default: off. | |
3015 | ||
8ad9c4bb | 3016 | <tag><label id="bgp-enable-enhanced-route-refresh">enable enhanced route refresh <m/switch/</tag> |
3fb06fea OZ |
3017 | BGP protocol extension Enhanced Route Refresh (<rfc id="7313">) |
3018 | specifies explicit begin and end for Route Refresh (see previous | |
3019 | option), therefore the receiver can remove stale routes that were not | |
3020 | advertised during the exchange. This option specifies whether BIRD | |
3021 | advertises this capability and supports related procedures. Default: on. | |
3022 | ||
3023 | <tag><label id="bgp-require-enhanced-route-refresh">require enhanced route refresh <m/switch/</tag> | |
3024 | If enabled, the BGP Enhanced Route Refresh capability (<rfc id="7313">) | |
3025 | must be announced by the BGP neighbor, otherwise the BGP session | |
3026 | will not be established. Default: off. | |
bf47fe4b | 3027 | |
7fc55925 OZ |
3028 | <tag><label id="bgp-graceful-restart">graceful restart <m/switch/|aware</tag> |
3029 | When a BGP speaker restarts or crashes, neighbors will discard all | |
3030 | received paths from the speaker, which disrupts packet forwarding even | |
3031 | when the forwarding plane of the speaker remains intact. <rfc id="4724"> | |
3032 | specifies an optional graceful restart mechanism to alleviate this | |
3033 | issue. This option controls the mechanism. It has three states: | |
3034 | Disabled, when no support is provided. Aware, when the graceful restart | |
3035 | support is announced and the support for restarting neighbors is | |
3036 | provided, but no local graceful restart is allowed (i.e. receiving-only | |
3037 | role). Enabled, when the full graceful restart support is provided | |
3038 | (i.e. both restarting and receiving role). Restarting role could be also | |
3039 | configured per-channel. Note that proper support for local graceful | |
3040 | restart requires also configuration of other protocols. Default: aware. | |
3041 | ||
b9864aa8 | 3042 | <tag><label id="bgp-graceful-restart-time">graceful restart time <m/number/</tag> |
3fb06fea | 3043 | The restart time is announced in the BGP Graceful Restart capability |
6eda3f13 OZ |
3044 | and specifies how long the neighbor would wait for the BGP session to |
3045 | re-establish after a restart before deleting stale routes. Default: | |
3046 | 120 seconds. | |
3047 | ||
3fb06fea OZ |
3048 | <tag><label id="bgp-require-graceful-restart">require graceful restart <m/switch/</tag> |
3049 | If enabled, the BGP Graceful Restart capability (<rfc id="4724">) | |
3050 | must be announced by the BGP neighbor, otherwise the BGP session | |
3051 | will not be established. Default: off. | |
3052 | ||
5bd73431 OZ |
3053 | <tag><label id="bgp-long-lived-graceful-restart">long lived graceful restart <m/switch/|aware</tag> |
3054 | The long-lived graceful restart is an extension of the traditional | |
3055 | <ref id="bgp-graceful-restart" name="BGP graceful restart">, where stale | |
3056 | routes are kept even after the <ref id="bgp-graceful-restart-time" | |
3057 | name="restart time"> expires for additional long-lived stale time, but | |
3058 | they are marked with the LLGR_STALE community, depreferenced, and | |
3059 | withdrawn from routers not supporting LLGR. Like traditional BGP | |
3060 | graceful restart, it has three states: disabled, aware (receiving-only), | |
3061 | and enabled. Note that long-lived graceful restart requires at least | |
3062 | aware level of traditional BGP graceful restart. Default: aware, unless | |
3063 | graceful restart is disabled. | |
3064 | ||
3065 | <tag><label id="bgp-long-lived-stale-time">long lived stale time <m/number/</tag> | |
3fb06fea OZ |
3066 | The long-lived stale time is announced in the BGP Long-lived Graceful |
3067 | Restart capability and specifies how long the neighbor would keep stale | |
5bd73431 OZ |
3068 | routes depreferenced during long-lived graceful restart until either the |
3069 | session is re-stablished and synchronized or the stale time expires and | |
3070 | routes are removed. Default: 3600 seconds. | |
3071 | ||
3fb06fea OZ |
3072 | <tag><label id="bgp-require-long-lived-graceful-restart">require long lived graceful restart <m/switch/</tag> |
3073 | If enabled, the BGP Long-lived Graceful Restart capability (draft) | |
3074 | must be announced by the BGP neighbor, otherwise the BGP session | |
3075 | will not be established. Default: off. | |
3076 | ||
b9864aa8 | 3077 | <tag><label id="bgp-interpret-communities">interpret communities <m/switch/</tag> |
7935b9d2 PT |
3078 | <rfc id="1997"> demands that BGP speaker should process well-known |
3079 | communities like no-export (65535, 65281) or no-advertise (65535, | |
3080 | 65282). For example, received route carrying a no-adverise community | |
3081 | should not be advertised to any of its neighbors. If this option is | |
3082 | enabled (which is by default), BIRD has such behavior automatically (it | |
3083 | is evaluated when a route is exported to the BGP protocol just before | |
3084 | the export filter). Otherwise, this integrated processing of | |
3085 | well-known communities is disabled. In that case, similar behavior can | |
3086 | be implemented in the export filter. Default: on. | |
dad92c30 | 3087 | |
b9864aa8 | 3088 | <tag><label id="bgp-enable-as4">enable as4 <m/switch/</tag> |
dad92c30 OZ |
3089 | BGP protocol was designed to use 2B AS numbers and was extended later to |
3090 | allow 4B AS number. BIRD supports 4B AS extension, but by disabling this | |
3091 | option it can be persuaded not to advertise it and to maintain old-style | |
3092 | sessions with its neighbors. This might be useful for circumventing bugs | |
3093 | in neighbor's implementation of 4B AS extension. Even when disabled | |
3094 | (off), BIRD behaves internally as AS4-aware BGP router. Default: on. | |
3095 | ||
3fb06fea OZ |
3096 | <tag><label id="bgp-require-as4">require as4 <m/switch/</tag> |
3097 | If enabled, the BGP 4B AS number capability (<rfc id="6793">) must be | |
3098 | announced by the BGP neighbor, otherwise the BGP session will not be | |
3099 | established. Default: off. | |
3100 | ||
b9864aa8 | 3101 | <tag><label id="bgp-enable-extended-messages">enable extended messages <m/switch/</tag> |
79a4f74a | 3102 | The BGP protocol uses maximum message length of 4096 bytes. This option |
be7c1aef OZ |
3103 | provides an extension (<rfc id="8654">) to allow extended messages with |
3104 | length up to 65535 bytes. Default: off. | |
79a4f74a | 3105 | |
3fb06fea OZ |
3106 | <tag><label id="bgp-require-extended-messages">require extended messages <m/switch/</tag> |
3107 | If enabled, the BGP Extended Message capability (<rfc id="8654">) must | |
3108 | be announced by the BGP neighbor, otherwise the BGP session will not be | |
3109 | established. Default: off. | |
3110 | ||
b9864aa8 | 3111 | <tag><label id="bgp-capabilities">capabilities <m/switch/</tag> |
dad92c30 OZ |
3112 | Use capability advertisement to advertise optional capabilities. This is |
3113 | standard behavior for newer BGP implementations, but there might be some | |
3114 | older BGP implementations that reject such connection attempts. When | |
3115 | disabled (off), features that request it (4B AS support) are also | |
3116 | disabled. Default: on, with automatic fallback to off when received | |
3117 | capability-related error. | |
3118 | ||
71423871 | 3119 | <tag><label id="bgp-advertise-hostname">advertise hostname <m/switch/</tag> |
3fb06fea OZ |
3120 | Advertise the hostname capability along with the hostname. Default: off. |
3121 | ||
3122 | <tag><label id="bgp-require-hostname">require hostname <m/switch/</tag> | |
3123 | If enabled, the hostname capability must be announced by the BGP | |
3124 | neighbor, otherwise the BGP session negotiation fails. Default: off. | |
71423871 | 3125 | |
b9864aa8 | 3126 | <tag><label id="bgp-disable-after-error">disable after error <m/switch/</tag> |
dad92c30 OZ |
3127 | When an error is encountered (either locally or by the other side), |
3128 | disable the instance automatically and wait for an administrator to fix | |
3129 | the problem manually. Default: off. | |
3130 | ||
c408d807 OZ |
3131 | <tag><label id="bgp-disable-after-cease">disable after cease <m/switch/|<m/set-of-flags/</tag> |
3132 | When a Cease notification is received, disable the instance | |
3133 | automatically and wait for an administrator to fix the problem manually. | |
3134 | When used with <m/switch/ argument, it means handle every Cease subtype | |
3135 | with the exception of <cf/connection collision/. Default: off. | |
3136 | ||
3137 | The <m/set-of-flags/ allows to narrow down relevant Cease subtypes. The | |
3138 | syntax is <cf>{<m/flag/ [, <m/.../] }</cf>, where flags are: <cf/cease/, | |
3139 | <cf/prefix limit hit/, <cf/administrative shutdown/, | |
3140 | <cf/peer deconfigured/, <cf/administrative reset/, | |
3141 | <cf/connection rejected/, <cf/configuration change/, | |
3142 | <cf/connection collision/, <cf/out of resources/. | |
3143 | ||
b9864aa8 | 3144 | <tag><label id="bgp-hold-time">hold time <m/number/</tag> |
dad92c30 | 3145 | Time in seconds to wait for a Keepalive message from the other side |
3859e4ef OZ |
3146 | before considering the connection stale. The effective value is |
3147 | negotiated during session establishment and it is a minimum of this | |
3148 | configured value and the value proposed by the peer. The zero value has | |
3149 | a special meaning, signifying that no keepalives are used. Default: 240 | |
3150 | seconds. | |
3151 | ||
3152 | <tag><label id="bgp-min-hold-time">min hold time <m/number/</tag> | |
3153 | Minimum value of the hold time that is accepted during session negotiation. | |
3154 | If the peer proposes a lower value, the session is rejected with error. | |
3155 | Default: none. | |
dad92c30 | 3156 | |
b9864aa8 | 3157 | <tag><label id="bgp-startup-hold-time">startup hold time <m/number/</tag> |
dad92c30 OZ |
3158 | Value of the hold timer used before the routers have a chance to exchange |
3159 | open messages and agree on the real value. Default: 240 seconds. | |
3160 | ||
b9864aa8 | 3161 | <tag><label id="bgp-keepalive-time">keepalive time <m/number/</tag> |
dad92c30 | 3162 | Delay in seconds between sending of two consecutive Keepalive messages. |
3859e4ef OZ |
3163 | The effective value depends on the negotiated hold time, as it is scaled |
3164 | to maintain proportion between the keepalive time and the hold time. | |
dad92c30 OZ |
3165 | Default: One third of the hold time. |
3166 | ||
3859e4ef OZ |
3167 | <tag><label id="bgp-min-keepalive-time">min keepalive time <m/number/</tag> |
3168 | Minimum value of the keepalive time that is accepted during session | |
3169 | negotiation. If the proposed hold time would lead to a lower value of | |
3170 | the keepalive time, the session is rejected with error. Default: none. | |
3171 | ||
bcf23274 KK |
3172 | <tag><label id="bgp-send-hold-time">send hold time <m/number/</tag> |
3173 | Maximum time in seconds betweeen successfull transmissions of BGP messages. | |
3174 | Send hold timer drops the session if the neighbor is sending keepalives, | |
3175 | but does not receive our messages, causing the TCP connection to stall. | |
3176 | This may happen due to malfunctioning or overwhelmed neighbor. See | |
3177 | <HTMLURL URL="https://datatracker.ietf.org/doc/draft-ietf-idr-bgp-sendholdtimer/" | |
3178 | name="draft-ietf-idr-bgp-sendholdtimer"> for more details. | |
3179 | ||
3180 | Like the option <cf/keepalive time/, the effective value depends on the | |
3181 | negotiated hold time, as it is scaled to maintain proportion between the | |
3182 | send hold time and the keepalive time. If it is set to zero, the timer | |
3183 | is disabled. Default: double of the hold timer limit. | |
3184 | ||
3185 | The option <cf/disable rx/ is intended only for testing this feature and | |
3186 | should not be used anywhere else. It discards received messages and | |
3187 | disables the hold timer. | |
3188 | ||
b9864aa8 | 3189 | <tag><label id="bgp-connect-delay-time">connect delay time <m/number/</tag> |
6cf72d7a OZ |
3190 | Delay in seconds between protocol startup and the first attempt to |
3191 | connect. Default: 5 seconds. | |
3192 | ||
b9864aa8 | 3193 | <tag><label id="bgp-connect-retry-time">connect retry time <m/number/</tag> |
dad92c30 OZ |
3194 | Time in seconds to wait before retrying a failed attempt to connect. |
3195 | Default: 120 seconds. | |
3196 | ||
b9864aa8 | 3197 | <tag><label id="bgp-error-wait-time">error wait time <m/number/,<m/number/</tag> |
dad92c30 | 3198 | Minimum and maximum delay in seconds between a protocol failure (either |
1f2eb2ac | 3199 | local or reported by the peer) and automatic restart. Doesn not apply |
dad92c30 OZ |
3200 | when <cf/disable after error/ is configured. If consecutive errors |
3201 | happen, the delay is increased exponentially until it reaches the | |
3202 | maximum. Default: 60, 300. | |
3203 | ||
b9864aa8 | 3204 | <tag><label id="bgp-error-forget-time">error forget time <m/number/</tag> |
dad92c30 OZ |
3205 | Maximum time in seconds between two protocol failures to treat them as a |
3206 | error sequence which makes <cf/error wait time/ increase exponentially. | |
3207 | Default: 300 seconds. | |
3208 | ||
b9864aa8 | 3209 | <tag><label id="bgp-path-metric">path metric <m/switch/</tag> |
dad92c30 OZ |
3210 | Enable comparison of path lengths when deciding which BGP route is the |
3211 | best one. Default: on. | |
3212 | ||
b9864aa8 | 3213 | <tag><label id="bgp-med-metric">med metric <m/switch/</tag> |
dad92c30 OZ |
3214 | Enable comparison of MED attributes (during best route selection) even |
3215 | between routes received from different ASes. This may be useful if all | |
3216 | MED attributes contain some consistent metric, perhaps enforced in | |
3217 | import filters of AS boundary routers. If this option is disabled, MED | |
3218 | attributes are compared only if routes are received from the same AS | |
3219 | (which is the standard behavior). Default: off. | |
3220 | ||
3e52d112 JMM |
3221 | <tag><label id="bgp-deterministic-med">deterministic med <m/switch/</tag> |
3222 | BGP route selection algorithm is often viewed as a comparison between | |
3223 | individual routes (e.g. if a new route appears and is better than the | |
3224 | current best one, it is chosen as the new best one). But the proper | |
3225 | route selection, as specified by <rfc id="4271">, cannot be fully | |
3226 | implemented in that way. The problem is mainly in handling the MED | |
3227 | attribute. BIRD, by default, uses an simplification based on individual | |
3228 | route comparison, which in some cases may lead to temporally dependent | |
3229 | behavior (i.e. the selection is dependent on the order in which routes | |
3230 | appeared). This option enables a different (and slower) algorithm | |
3231 | implementing proper <rfc id="4271"> route selection, which is | |
3232 | deterministic. Alternative way how to get deterministic behavior is to | |
3233 | use <cf/med metric/ option. This option is incompatible with <ref | |
3234 | id="dsc-table-sorted" name="sorted tables">. Default: off. | |
3235 | ||
3236 | <tag><label id="bgp-igp-metric">igp metric <m/switch/</tag> | |
3237 | Enable comparison of internal distances to boundary routers during best | |
cf3e3845 | 3238 | route selection. Default: on. |
3e52d112 JMM |
3239 | |
3240 | <tag><label id="bgp-prefer-older">prefer older <m/switch/</tag> | |
3241 | Standard route selection algorithm breaks ties by comparing router IDs. | |
3242 | This changes the behavior to prefer older routes (when both are external | |
3243 | and from different peer). For details, see <rfc id="5004">. Default: off. | |
3244 | ||
3245 | <tag><label id="bgp-default-med">default bgp_med <m/number/</tag> | |
3246 | Value of the Multiple Exit Discriminator to be used during route | |
3247 | selection when the MED attribute is missing. Default: 0. | |
3248 | ||
3249 | <tag><label id="bgp-default-local-pref">default bgp_local_pref <m/number/</tag> | |
3250 | A default value for the Local Preference attribute. It is used when | |
3251 | a new Local Preference attribute is attached to a route by the BGP | |
3252 | protocol itself (for example, if a route is received through eBGP and | |
3253 | therefore does not have such attribute). Default: 100 (0 in pre-1.2.0 | |
3254 | versions of BIRD). | |
c73b5d2d EB |
3255 | |
3256 | <tag><label id="bgp-local-role">local role <m/role-name/</tag> | |
3257 | BGP roles are a mechanism for route leak prevention and automatic route | |
3258 | filtering based on common BGP topology relationships. They are defined | |
3259 | in <rfc id="9234">. Instead of manually configuring filters and | |
3260 | communities, automatic filtering is done with the help of the OTC | |
3261 | attribute - a flag for routes that should be sent only to customers. | |
3262 | The same attribute is also used to automatically detect and filter route | |
3263 | leaks created by third parties. | |
3264 | ||
3265 | This option is valid for EBGP sessions, but it is not recommended to be | |
971721c9 OZ |
3266 | used within AS confederations (which would require manual filtering of |
3267 | <cf/bgp_otc/ attribute on confederation boundaries). | |
c73b5d2d EB |
3268 | |
3269 | Possible <cf><m/role-name/</cf> values are: <cf/provider/, | |
3270 | <cf/rs_server/, <cf/rs_client/, <cf/customer/ and <cf/peer/. | |
3271 | Default: No local role assigned. | |
3272 | ||
3273 | <tag><label id="bgp-require-roles">require roles <m/switch/</tag> | |
3274 | If this option is set, the BGP roles must be defined on both sides, | |
3275 | otherwise the session will not be established. This behavior is defined | |
3276 | in <rfc id="9234"> as "strict mode" and is used to enforce corresponding | |
3277 | configuration at your conterpart side. Default: disabled. | |
3e52d112 JMM |
3278 | </descrip> |
3279 | ||
3280 | <sect1>Channel configuration | |
3281 | <label id="bgp-channel-config"> | |
3282 | ||
3283 | <p>BGP supports several AFIs and SAFIs over one connection. Every AFI/SAFI | |
3284 | announced to the peer corresponds to one channel. The table of supported AFI/SAFIs | |
3285 | together with their appropriate channels follows. | |
3286 | ||
71c51aa4 | 3287 | <table loc="h"> |
3e52d112 JMM |
3288 | <tabular ca="l|l|l|r|r"> |
3289 | <bf/Channel name/ | <bf/Table nettype/ | <bf/IGP table allowed/ | <bf/AFI/ | <bf/SAFI/ | |
71c51aa4 | 3290 | @<hline> |
3e52d112 JMM |
3291 | <cf/ipv4/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 1 |
3292 | @ <cf/ipv6/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 1 | |
3293 | @ <cf/ipv4 multicast/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 2 | |
3294 | @ <cf/ipv6 multicast/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 2 | |
3295 | @ <cf/ipv4 mpls/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 4 | |
3296 | @ <cf/ipv6 mpls/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 4 | |
3297 | @ <cf/vpn4 mpls/ | <cf/vpn4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 128 | |
3298 | @ <cf/vpn6 mpls/ | <cf/vpn6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 128 | |
3299 | @ <cf/vpn4 multicast/ | <cf/vpn4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 129 | |
3300 | @ <cf/vpn6 multicast/ | <cf/vpn6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 129 | |
3301 | @ <cf/flow4/ | <cf/flow4/ | --- | 1 | 133 | |
3302 | @ <cf/flow6/ | <cf/flow6/ | --- | 2 | 133 | |
3303 | </tabular> | |
71c51aa4 | 3304 | </table> |
3e52d112 | 3305 | |
8a708856 OZ |
3306 | <p>The BGP protocol can be configured as MPLS-aware (by defining both AFI/SAFI |
3307 | channels and the MPLS channel). In such case the BGP protocol assigns labels to | |
3308 | routes imported from MPLS-aware SAFIs (i.e. <cf/ipvX mpls/ and <cf/vpnX mpls/) | |
3309 | and automatically announces corresponding MPLS route for each labeled route. As | |
3310 | BGP generally processes a large amount of routes, it is suggested to set MPLS | |
3311 | label policy to <cf/aggregate/. | |
3312 | ||
3313 | <p>Note that even BGP instances without MPLS channel and without local MPLS | |
3314 | configuration can still propagate third-party MPLS labels, e.g. as route | |
3315 | reflectors, they just will not assign local labels to imported routes and will | |
3316 | not announce MPLS routes for local MPLS forwarding. | |
3317 | ||
3831b619 OZ |
3318 | <p>Due to <rfc id="8212">, external BGP protocol requires explicit configuration |
3319 | of import and export policies (in contrast to other protocols, where default | |
3320 | policies of <cf/import all/ and <cf/export none/ are used in absence of explicit | |
3321 | configuration). Note that blanket policies like <cf/all/ or <cf/none/ can still | |
3322 | be used in explicit configuration. | |
3323 | ||
72163bd5 | 3324 | <p>BGP channels have additional config options (together with the common ones): |
3e52d112 JMM |
3325 | |
3326 | <descrip> | |
3c360581 OZ |
3327 | <tag><label id="bgp-mandatory">mandatory <m/switch/</tag> |
3328 | When local and neighbor sets of configured AFI/SAFI pairs differ, | |
3329 | capability negotiation ensures that a common subset is used. For | |
3330 | mandatory channels their associated AFI/SAFI must be negotiated | |
3331 | (i.e., also announced by the neighbor), otherwise BGP session | |
3332 | negotiation fails with <it/'Required capability missing'/ error. | |
3333 | Regardless, at least one AFI/SAFI must be negotiated in order to BGP | |
3334 | session be successfully established. Default: off. | |
3335 | ||
1cab2b4a OZ |
3336 | <tag><label id="bgp-next-hop-keep">next hop keep <m/switch/|ibgp|ebgp</tag> |
3337 | Do not modify the Next Hop attribute and advertise the current one | |
3338 | unchanged even in cases where our own local address should be used | |
3339 | instead. This is necessary when the BGP speaker does not forward network | |
3340 | traffic (route servers and some route reflectors) and also can be useful | |
3341 | in some other cases (e.g. multihop EBGP sessions). Can be enabled for | |
3342 | all routes, or just for routes received from IBGP / EBGP neighbors. | |
3343 | Default: disabled for regular BGP, enabled for route servers, | |
3344 | <cf/ibgp/ for route reflectors. | |
3345 | ||
3346 | <tag><label id="bgp-next-hop-self">next hop self <m/switch/|ibgp|ebgp</tag> | |
3347 | Always advertise our own local address as a next hop, even in cases | |
3348 | where the current Next Hop attribute should be used unchanged. This is | |
3349 | sometimes used for routes propagated from EBGP to IBGP when IGP routing | |
3350 | does not cover inter-AS links, therefore IP addreses of EBGP neighbors | |
3351 | are not resolvable through IGP. Can be enabled for all routes, or just | |
3352 | for routes received from IBGP / EBGP neighbors. Default: disabled. | |
3e52d112 JMM |
3353 | |
3354 | <tag><label id="bgp-next-hop-address">next hop address <m/ip/</tag> | |
1cab2b4a OZ |
3355 | Specify which address to use when our own local address should be |
3356 | announced in the Next Hop attribute. Default: the source address of the | |
3357 | BGP session (if acceptable), or the preferred address of an associated | |
3358 | interface. | |
3e52d112 | 3359 | |
8f79e6b9 OZ |
3360 | <tag><label id="bgp-next-hop-prefer">next hop prefer global</tag> |
3361 | Prefer global IPv6 address to link-local IPv6 address for immediate next | |
3362 | hops of received routes. For IPv6 routes, the Next Hop attribute may | |
3363 | contain both a global IP address and a link-local IP address. For IBGP | |
3364 | sessions, the global IP address is resolved (<ref id="bgp-gateway" | |
3365 | name="gateway recursive">) through an IGP routing table | |
3366 | (<ref id="bgp-igp-table" name="igp table">) to get an immediate next | |
3367 | hop. If the resulting IGP route is a direct route (i.e., the next hop is | |
3368 | a direct neighbor), then the link-local IP address from the Next Hop | |
3369 | attribute is used as the immediate next hop. This option change it to | |
3370 | use the global IP address instead. Note that even with this option | |
3371 | enabled a route may end with a link-local immediate next hop when the | |
3372 | IGP route has one. Default: disabled. | |
3373 | ||
3e52d112 JMM |
3374 | <tag><label id="bgp-gateway">gateway direct|recursive</tag> |
3375 | For received routes, their <cf/gw/ (immediate next hop) attribute is | |
3376 | computed from received <cf/bgp_next_hop/ attribute. This option | |
3377 | specifies how it is computed. Direct mode means that the IP address from | |
3232d171 OZ |
3378 | <cf/bgp_next_hop/ is used and must be directly reachable. Recursive mode |
3379 | means that the gateway is computed by an IGP routing table lookup for | |
3380 | the IP address from <cf/bgp_next_hop/. Note that there is just one level | |
3381 | of indirection in recursive mode - the route obtained by the lookup must | |
3382 | not be recursive itself, to prevent mutually recursive routes. | |
3e52d112 JMM |
3383 | |
3384 | Recursive mode is the behavior specified by the BGP | |
3385 | standard. Direct mode is simpler, does not require any routes in a | |
3386 | routing table, and was used in older versions of BIRD, but does not | |
3387 | handle well nontrivial iBGP setups and multihop. Recursive mode is | |
3388 | incompatible with <ref id="dsc-table-sorted" name="sorted tables">. Default: | |
3389 | <cf/direct/ for direct sessions, <cf/recursive/ for multihop sessions. | |
be4cd99a | 3390 | |
3e52d112 JMM |
3391 | <tag><label id="bgp-igp-table">igp table <m/name/</tag> |
3392 | Specifies a table that is used as an IGP routing table. The type of this | |
3393 | table must be as allowed in the table above. This option is allowed once | |
3394 | for every allowed table type. Default: the same as the main table | |
3395 | the channel is connected to (if eligible). | |
dad92c30 | 3396 | |
9e92f357 | 3397 | <tag><label id="bgp-import-table">import table <m/switch/</tag> |
1cab2b4a | 3398 | A BGP import table contains all received routes from given BGP neighbor, |
9e92f357 OZ |
3399 | before application of import filters. It is also called <em/Adj-RIB-In/ |
3400 | in BGP terminology. BIRD BGP by default operates without import tables, | |
3401 | in which case received routes are just processed by import filters, | |
3402 | accepted ones are stored in the master table, and the rest is forgotten. | |
3403 | Enabling <cf/import table/ allows to store unprocessed routes, which can | |
3404 | be examined later by <cf/show route/, and can be used to reconfigure | |
3405 | import filters without full route refresh. Default: off. | |
3406 | ||
e48f898f OZ |
3407 | Note that currently the import table breaks routes with recursive |
3408 | nexthops (e.g. ones from IBGP, see <ref id="bgp-gateway" name="gateway | |
3409 | recursive">), they are not properly updated after next hop change. For | |
3410 | the same reason, it also breaks re-evaluation of flowspec routes with | |
3411 | <ref id="bgp-validate" name="flowspec validation"> option enabled on | |
3412 | flowspec channels. | |
3413 | ||
b7d7599c OZ |
3414 | <tag><label id="bgp-export-table">export table <m/switch/</tag> |
3415 | A BGP export table contains all routes sent to given BGP neighbor, after | |
3416 | application of export filters. It is also called <em/Adj-RIB-Out/ in BGP | |
3417 | terminology. BIRD BGP by default operates without export tables, in | |
3418 | which case routes from master table are just processed by export filters | |
3419 | and then announced by BGP. Enabling <cf/export table/ allows to store | |
3420 | routes after export filter processing, so they can be examined later by | |
3421 | <cf/show route/, and can be used to eliminate unnecessary updates or | |
3422 | withdraws. Default: off. | |
3423 | ||
3e52d112 JMM |
3424 | <tag><label id="bgp-secondary">secondary <m/switch/</tag> |
3425 | Usually, if an export filter rejects a selected route, no other route is | |
3426 | propagated for that network. This option allows to try the next route in | |
3427 | order until one that is accepted is found or all routes for that network | |
3428 | are rejected. This can be used for route servers that need to propagate | |
3429 | different tables to each client but do not want to have these tables | |
3430 | explicitly (to conserve memory). This option requires that the connected | |
3431 | routing table is <ref id="dsc-table-sorted" name="sorted">. Default: off. | |
dad92c30 | 3432 | |
1f2eb2ac OZ |
3433 | <tag><label id="bgp-validate">validate <m/switch/</tag> |
3434 | Apply flowspec validation procedure as described in <rfc id="8955"> | |
3435 | section 6 and <rfc id="9117">. The Validation procedure enforces that | |
3436 | only routers in the forwarding path for a network can originate flowspec | |
3437 | rules for that network. The validation procedure should be used for EBGP | |
3438 | to prevent injection of malicious flowspec rules from outside, but it | |
3439 | should also be used for IBGP to ensure that selected flowspec rules are | |
3440 | consistent with selected IP routes. The validation procedure uses an IP | |
3441 | routing table (<ref id="bgp-base-table" name="base table">, see below) | |
3442 | against which flowspec rules are validated. This option is limited to | |
3443 | flowspec channels. Default: off (for compatibility reasons). | |
3444 | ||
3445 | Note that currently the flowspec validation does not work reliably | |
3446 | together with <ref id="bgp-import-table" name="import table"> option | |
3447 | enabled on flowspec channels. | |
3448 | ||
3449 | <tag><label id="bgp-base-table">base table <m/name/</tag> | |
3450 | Specifies an IP table used for the flowspec validation procedure. The | |
3451 | table must have enabled <cf/trie/ option, otherwise the validation | |
3452 | procedure would not work. The type of the table must be <cf/ipv4/ for | |
3453 | <cf/flow4/ channels and <cf/ipv6/ for <cf/flow6/ channels. This option | |
3454 | is limited to flowspec channels. Default: the main table of the | |
3455 | <cf/ipv4/ / <cf/ipv6/ channel of the same BGP instance, or the | |
3456 | <cf/master4/ / <cf/master6/ table if there is no such channel. | |
3457 | ||
a63d20aa OZ |
3458 | <tag><label id="bgp-extended-next-hop">extended next hop <m/switch/</tag> |
3459 | BGP expects that announced next hops have the same address family as | |
3460 | associated network prefixes. This option provides an extension to use | |
3461 | IPv4 next hops with IPv6 prefixes and vice versa. For IPv4 / VPNv4 | |
3462 | channels, the behavior is controlled by the Extended Next Hop Encoding | |
9bf20484 | 3463 | capability, as described in <rfc id="8950">. For IPv6 / VPNv6 channels, |
a63d20aa OZ |
3464 | just IPv4-mapped IPv6 addresses are used, as described in |
3465 | <rfc id="4798"> and <rfc id="4659">. Default: off. | |
3466 | ||
3fb06fea OZ |
3467 | <tag><label id="bgp-require-extended-next-hop">require extended next hop <m/switch/</tag> |
3468 | If enabled, the BGP Extended Next Hop Encoding capability (<rfc id="8950">) | |
3469 | must be announced by the BGP neighbor, otherwise the BGP session will | |
3470 | not be established. Note that this option is relevant just for IPv4 / | |
3471 | VPNv4 channels, as IPv6 / VPNv6 channels use a different mechanism not | |
3472 | signalled by a capability. Default: off. | |
3473 | ||
3e52d112 JMM |
3474 | <tag><label id="bgp-add-paths">add paths <m/switch/|rx|tx</tag> |
3475 | Standard BGP can propagate only one path (route) per destination network | |
3fb06fea | 3476 | (usually the selected one). This option controls the ADD-PATH protocol |
3e52d112 | 3477 | extension, which allows to advertise any number of paths to a |
3fb06fea | 3478 | destination. Note that to be active, ADD-PATH has to be enabled on both |
3e52d112 JMM |
3479 | sides of the BGP session, but it could be enabled separately for RX and |
3480 | TX direction. When active, all available routes accepted by the export | |
3481 | filter are advertised to the neighbor. Default: off. | |
dad92c30 | 3482 | |
3fb06fea OZ |
3483 | <tag><label id="bgp-require-add-paths">require add paths <m/switch/</tag> |
3484 | If enabled, the BGP ADD-PATH capability (<rfc id="7911">) must be | |
3485 | announced by the BGP neighbor, otherwise the BGP session will not be | |
3486 | established. Announced directions in the capability must be compatible | |
3487 | with locally configured directions. E.g., If <cf/add path tx/ is | |
3488 | configured locally, then the neighbor capability must announce RX. | |
3489 | Default: off. | |
3490 | ||
09ee846d OZ |
3491 | <tag><label id="bgp-aigp">aigp <m/switch/|originate</tag> |
3492 | The BGP protocol does not use a common metric like other routing | |
3493 | protocols, instead it uses a set of criteria for route selection | |
3494 | consisting both overall AS path length and a distance to the nearest AS | |
3495 | boundary router. Assuming that metrics of different autonomous systems | |
3496 | are incomparable, once a route is propagated from an AS to a next one, | |
3497 | the distance in the old AS does not matter. | |
3498 | ||
3499 | The AIGP extension (<rfc id="7311">) allows to propagate accumulated | |
3500 | IGP metric (in the AIGP attribute) through both IBGP and EBGP links, | |
3501 | computing total distance through multiple autonomous systems (assuming | |
3502 | they use comparable IGP metric). The total AIGP metric is compared in | |
3503 | the route selection process just after Local Preference comparison (and | |
3504 | before AS path length comparison). | |
3505 | ||
3506 | This option controls whether AIGP attribute propagation is allowed on | |
3507 | the session. Optionally, it can be set to <cf/originate/, which not only | |
3508 | allows AIGP attribute propagation, but also new AIGP attributes are | |
3509 | automatically attached to non-BGP routes with valid IGP metric (e.g. | |
3510 | <cf/ospf_metric1/) as they are exported to the BGP session. Default: | |
3511 | enabled for IBGP (and intra-confederation EBGP), disabled for regular | |
3512 | EBGP. | |
3513 | ||
3514 | <tag><label id="bgp-cost">cost <m/number/</tag> | |
3515 | When BGP <ref id="bgp-gateway" name="gateway mode"> is <cf/recursive/ | |
3516 | (mainly multihop IBGP sessions), then the distance to BGP next hop is | |
3517 | based on underlying IGP metric. This option specifies the distance to | |
3518 | BGP next hop for BGP sessions in direct gateway mode (mainly direct | |
3519 | EBGP sessions). | |
3520 | ||
7fc55925 OZ |
3521 | <tag><label id="bgp-graceful-restart-c">graceful restart <m/switch/</tag> |
3522 | Although BGP graceful restart is configured mainly by protocol-wide | |
3523 | <ref id="bgp-graceful-restart" name="options">, it is possible to | |
3524 | configure restarting role per AFI/SAFI pair by this channel option. | |
3525 | The option is ignored if graceful restart is disabled by protocol-wide | |
3526 | option. Default: off in aware mode, on in full mode. | |
5bd73431 OZ |
3527 | |
3528 | <tag><label id="bgp-long-lived-graceful-restart-c">long lived graceful restart <m/switch/</tag> | |
3529 | BGP long-lived graceful restart is configured mainly by protocol-wide | |
3530 | <ref id="bgp-long-lived-graceful-restart" name="options">, but the | |
3531 | restarting role can be set per AFI/SAFI pair by this channel option. | |
3532 | The option is ignored if long-lived graceful restart is disabled by | |
3533 | protocol-wide option. Default: off in aware mode, on in full mode. | |
3534 | ||
3535 | <tag><label id="bgp-long-lived-stale-time-c">long lived stale time <m/number/</tag> | |
3536 | Like previous graceful restart channel options, this option allows to | |
3537 | set <ref id="bgp-long-lived-stale-time" name="long lived stale time"> | |
3538 | per AFI/SAFI pair instead of per protocol. Default: set by protocol-wide | |
3539 | option. | |
5459fac6 MM |
3540 | </descrip> |
3541 | ||
371adba6 | 3542 | <sect1>Attributes |
b9864aa8 | 3543 | <label id="bgp-attr"> |
56ab03c7 | 3544 | |
dad92c30 OZ |
3545 | <p>BGP defines several route attributes. Some of them (those marked with |
3546 | `<tt/I/' in the table below) are available on internal BGP connections only, | |
3547 | some of them (marked with `<tt/O/') are optional. | |
5459fac6 MM |
3548 | |
3549 | <descrip> | |
157f6c2a | 3550 | <tag><label id="rta-bgp-path">bgppath bgp_path</tag> |
dad92c30 OZ |
3551 | Sequence of AS numbers describing the AS path the packet will travel |
3552 | through when forwarded according to the particular route. In case of | |
3553 | internal BGP it doesn't contain the number of the local AS. | |
3554 | ||
157f6c2a | 3555 | <tag><label id="rta-bgp-local-pref">int bgp_local_pref [I]</tag> |
dad92c30 OZ |
3556 | Local preference value used for selection among multiple BGP routes (see |
3557 | the selection rules above). It's used as an additional metric which is | |
3558 | propagated through the whole local AS. | |
3559 | ||
157f6c2a | 3560 | <tag><label id="rta-bgp-med">int bgp_med [O]</tag> |
dad92c30 OZ |
3561 | The Multiple Exit Discriminator of the route is an optional attribute |
3562 | which is used on external (inter-AS) links to convey to an adjacent AS | |
3563 | the optimal entry point into the local AS. The received attribute is | |
3564 | also propagated over internal BGP links. The attribute value is zeroed | |
3565 | when a route is exported to an external BGP instance to ensure that the | |
3566 | attribute received from a neighboring AS is not propagated to other | |
3567 | neighboring ASes. A new value might be set in the export filter of an | |
7935b9d2 PT |
3568 | external BGP instance. See <rfc id="4451"> for further discussion of |
3569 | BGP MED attribute. | |
5a203dac | 3570 | |
157f6c2a | 3571 | <tag><label id="rta-bgp-origin">enum bgp_origin</tag> |
dad92c30 OZ |
3572 | Origin of the route: either <cf/ORIGIN_IGP/ if the route has originated |
3573 | in an interior routing protocol or <cf/ORIGIN_EGP/ if it's been imported | |
3574 | from the <tt>EGP</tt> protocol (nowadays it seems to be obsolete) or | |
3575 | <cf/ORIGIN_INCOMPLETE/ if the origin is unknown. | |
5a203dac | 3576 | |
157f6c2a | 3577 | <tag><label id="rta-bgp-next-hop">ip bgp_next_hop</tag> |
dad92c30 OZ |
3578 | Next hop to be used for forwarding of packets to this destination. On |
3579 | internal BGP connections, it's an address of the originating router if | |
3580 | it's inside the local AS or a boundary router the packet will leave the | |
3581 | AS through if it's an exterior route, so each BGP speaker within the AS | |
3582 | has a chance to use the shortest interior path possible to this point. | |
5a203dac | 3583 | |
157f6c2a | 3584 | <tag><label id="rta-bgp-atomic-aggr">void bgp_atomic_aggr [O]</tag> |
dad92c30 OZ |
3585 | This is an optional attribute which carries no value, but the sole |
3586 | presence of which indicates that the route has been aggregated from | |
3587 | multiple routes by some router on the path from the originator. | |
5a203dac | 3588 | |
09ee846d OZ |
3589 | <tag><label id="rta-bgp-aggregator">void bgp_aggregator [O]</tag> |
3590 | This is an optional attribute specifying AS number and IP address of the | |
3591 | BGP router that created the route by aggregating multiple BGP routes. | |
3592 | Currently, the attribute is not accessible from filters. | |
3593 | ||
157f6c2a | 3594 | <tag><label id="rta-bgp-community">clist bgp_community [O]</tag> |
dad92c30 OZ |
3595 | List of community values associated with the route. Each such value is a |
3596 | pair (represented as a <cf/pair/ data type inside the filters) of 16-bit | |
3597 | integers, the first of them containing the number of the AS which | |
3598 | defines the community and the second one being a per-AS identifier. | |
3599 | There are lots of uses of the community mechanism, but generally they | |
3600 | are used to carry policy information like "don't export to USA peers". | |
3601 | As each AS can define its own routing policy, it also has a complete | |
3602 | freedom about which community attributes it defines and what will their | |
3603 | semantics be. | |
3604 | ||
157f6c2a | 3605 | <tag><label id="rta-bgp-ext-community">eclist bgp_ext_community [O]</tag> |
dad92c30 OZ |
3606 | List of extended community values associated with the route. Extended |
3607 | communities have similar usage as plain communities, but they have an | |
3608 | extended range (to allow 4B ASNs) and a nontrivial structure with a type | |
3609 | field. Individual community values are represented using an <cf/ec/ data | |
3610 | type inside the filters. | |
3611 | ||
157f6c2a | 3612 | <tag><label id="rta-bgp-large-community">lclist bgp_large_community [O]</tag> |
cec4a73c OZ |
3613 | List of large community values associated with the route. Large BGP |
3614 | communities is another variant of communities, but contrary to extended | |
3615 | communities they behave very much the same way as regular communities, | |
3616 | just larger -- they are uniform untyped triplets of 32bit numbers. | |
3617 | Individual community values are represented using an <cf/lc/ data type | |
3618 | inside the filters. | |
3619 | ||
157f6c2a | 3620 | <tag><label id="rta-bgp-originator-id">quad bgp_originator_id [I, O]</tag> |
dad92c30 OZ |
3621 | This attribute is created by the route reflector when reflecting the |
3622 | route and contains the router ID of the originator of the route in the | |
3623 | local AS. | |
3624 | ||
157f6c2a | 3625 | <tag><label id="rta-bgp-cluster-list">clist bgp_cluster_list [I, O]</tag> |
dad92c30 OZ |
3626 | This attribute contains a list of cluster IDs of route reflectors. Each |
3627 | route reflector prepends its cluster ID when reflecting the route. | |
09ee846d OZ |
3628 | |
3629 | <tag><label id="rta-bgp-aigp">void bgp_aigp [O]</tag> | |
3630 | This attribute contains accumulated IGP metric, which is a total | |
3631 | distance to the destination through multiple autonomous systems. | |
3632 | Currently, the attribute is not accessible from filters. | |
c73b5d2d EB |
3633 | |
3634 | <tag><label id="bgp-otc">int bgp_otc [O]</tag> | |
3635 | This attribute is defined in <rfc id="9234">. OTC is a flag that marks | |
0bfa216f OZ |
3636 | routes that should be sent only to customers. If <ref id="bgp-local-role" |
3637 | name="local role"> is configured it set automatically. | |
5459fac6 MM |
3638 | </descrip> |
3639 | ||
57aa0772 OZ |
3640 | <p>For attributes unknown by BIRD, the user can assign a name (on top level) to |
3641 | an attribute by its number. This defined name can be used then to get, set (as a | |
3642 | bytestring, transitive) or unset the given attribute even though BIRD knows | |
3643 | nothing about it. | |
3644 | ||
3645 | <p>Note that it is not possible to define an attribute with the same number | |
3646 | as one known by BIRD, therefore use of this statement carries a risk of | |
3647 | incompatibility with future BIRD versions. | |
a0fb0eaa | 3648 | |
3649 | <tt><label id="bgp-attribute-custom">attribute bgp <m/number/ bytestring <m/name/;</tt> | |
3650 | ||
371adba6 | 3651 | <sect1>Example |
b9864aa8 | 3652 | <label id="bgp-exam"> |
56ab03c7 | 3653 | |
5459fac6 MM |
3654 | <p><code> |
3655 | protocol bgp { | |
cf3e3845 | 3656 | local 198.51.100.14 as 65000; # Use a private AS number |
9491f9f5 | 3657 | neighbor 198.51.100.130 as 64496; # Our neighbor ... |
6bcef225 | 3658 | multihop; # ... which is connected indirectly |
3e52d112 JMM |
3659 | ipv4 { |
3660 | export filter { # We use non-trivial export rules | |
3661 | if source = RTS_STATIC then { # Export only static routes | |
3662 | # Assign our community | |
3663 | bgp_community.add((65000,64501)); | |
3664 | # Artificially increase path length | |
3665 | # by advertising local AS number twice | |
3666 | if bgp_path ~ [= 65000 =] then | |
3667 | bgp_path.prepend(65000); | |
3668 | accept; | |
3669 | } | |
3670 | reject; | |
3671 | }; | |
3672 | import all; | |
3673 | next hop self; # advertise this router as next hop | |
3674 | igp table myigptable4; # IGP table for routes with IPv4 nexthops | |
3675 | igp table myigptable6; # IGP table for routes with IPv6 nexthops | |
3676 | }; | |
3677 | ipv6 { | |
3678 | export filter mylargefilter; # We use a named filter | |
3679 | import all; | |
3680 | missing lladdr self; | |
3681 | igp table myigptable4; # IGP table for routes with IPv4 nexthops | |
3682 | igp table myigptable6; # IGP table for routes with IPv6 nexthops | |
3683 | }; | |
3684 | ipv4 multicast { | |
3685 | import all; | |
3686 | export filter someotherfilter; | |
3687 | table mymulticasttable4; # Another IPv4 table, dedicated for multicast | |
3688 | igp table myigptable4; | |
3689 | }; | |
5459fac6 MM |
3690 | } |
3691 | </code> | |
3692 | ||
dad92c30 | 3693 | |
f3b599af OZ |
3694 | <sect>BMP |
3695 | <label id="bmp"> | |
3696 | ||
3697 | <p>The BGP Monitoring Protocol is used for monitoring BGP sessions and obtaining | |
3698 | routing table data. The current implementation in BIRD is a preliminary release | |
3699 | with a limited feature set, it will be subject to significant changes in the | |
3700 | future. It is not ready for production usage and therefore it is not compiled | |
3701 | by default and have to be enabled during installation by the configure option | |
3702 | <tt/--with-protocols=/. | |
3703 | ||
23f94b13 OZ |
3704 | <p>The implementation supports monitoring protocol state changes, pre-policy |
3705 | routes (in <ref id="bgp-import-table" name="BGP import tables">) and post-policy | |
3706 | routes (in regular routing tables). All BGP protocols are monitored automatically. | |
f3b599af OZ |
3707 | |
3708 | <sect1>Example | |
3709 | <label id="bmp-exam"> | |
3710 | ||
3711 | <p><code> | |
3712 | protocol bmp { | |
3713 | # The monitoring station to connect to | |
3714 | station address ip 198.51.100.10 port 1790; | |
3715 | ||
23f94b13 | 3716 | # Monitor received routes (in import table) |
f3b599af | 3717 | monitoring rib in pre_policy; |
23f94b13 OZ |
3718 | |
3719 | # Monitor accepted routes (passed import filters) | |
3720 | monitoring rib in post_policy; | |
f3b599af OZ |
3721 | } |
3722 | </code> | |
3723 | ||
3724 | ||
371adba6 | 3725 | <sect>Device |
b9864aa8 | 3726 | <label id="device"> |
1b55b1a3 | 3727 | |
dad92c30 OZ |
3728 | <p>The Device protocol is not a real routing protocol. It doesn't generate any |
3729 | routes and it only serves as a module for getting information about network | |
3e52d112 | 3730 | interfaces from the kernel. This protocol supports no channel. |
79a2b697 | 3731 | |
dad92c30 OZ |
3732 | <p>Except for very unusual circumstances, you probably should include this |
3733 | protocol in the configuration since almost all other protocols require network | |
3734 | interfaces to be defined for them to work with. | |
79a2b697 | 3735 | |
6f5603ba | 3736 | <sect1>Configuration |
b9864aa8 | 3737 | <label id="device-config"> |
79a2b697 MM |
3738 | |
3739 | <p><descrip> | |
b9864aa8 | 3740 | <tag><label id="device-scan-time">scan time <m/number/</tag> |
dad92c30 OZ |
3741 | Time in seconds between two scans of the network interface list. On |
3742 | systems where we are notified about interface status changes | |
3743 | asynchronously (such as newer versions of Linux), we need to scan the | |
3744 | list only in order to avoid confusion by lost notification messages, | |
3745 | so the default time is set to a large value. | |
3746 | ||
cf3e3845 | 3747 | <tag><label id="device-iface">interface <m/pattern/ [, <m/.../]</tag> |
cf3e3845 OZ |
3748 | By default, the Device protocol handles all interfaces without any |
3749 | configuration. Interface definitions allow to specify optional | |
3750 | parameters for specific interfaces. See <ref id="proto-iface" | |
3751 | name="interface"> common option for detailed description. Currently only | |
3752 | one interface option is available: | |
3753 | ||
3754 | <tag><label id="device-preferred">preferred <m/ip/</tag> | |
3755 | If a network interface has more than one IP address, BIRD chooses one of | |
3756 | them as a preferred one. Preferred IP address is used as source address | |
3757 | for packets or announced next hop by routing protocols. Precisely, BIRD | |
3758 | chooses one preferred IPv4 address, one preferred IPv6 address and one | |
3759 | preferred link-local IPv6 address. By default, BIRD chooses the first | |
3760 | found IP address as the preferred one. | |
3761 | ||
3762 | This option allows to specify which IP address should be preferred. May | |
3763 | be used multiple times for different address classes (IPv4, IPv6, IPv6 | |
3764 | link-local). In all cases, an address marked by operating system as | |
3765 | secondary cannot be chosen as the primary one. | |
79a2b697 MM |
3766 | </descrip> |
3767 | ||
79a2b697 | 3768 | <p>As the Device protocol doesn't generate any routes, it cannot have |
6f5603ba | 3769 | any attributes. Example configuration looks like this: |
79a2b697 MM |
3770 | |
3771 | <p><code> | |
3772 | protocol device { | |
3773 | scan time 10; # Scan the interfaces often | |
cf3e3845 OZ |
3774 | interface "eth0" { |
3775 | preferred 192.168.1.1; | |
3776 | preferred 2001:db8:1:10::1; | |
3777 | }; | |
79a2b697 MM |
3778 | } |
3779 | </code> | |
3780 | ||
cf3e3845 | 3781 | |
371adba6 | 3782 | <sect>Direct |
b9864aa8 | 3783 | <label id="direct"> |
1b55b1a3 | 3784 | |
79a2b697 | 3785 | <p>The Direct protocol is a simple generator of device routes for all the |
dad92c30 | 3786 | directly connected networks according to the list of interfaces provided by the |
cf3e3845 | 3787 | kernel via the Device protocol. The Direct protocol supports both IPv4 and IPv6 |
159d619c OZ |
3788 | channels; both can be configured simultaneously. It can also be configured with |
3789 | <ref id="ip-sadr-routes" name="IPv6 SADR"> channel instead of regular IPv6 | |
3790 | channel in order to be used together with SADR-enabled Babel protocol. | |
dad92c30 OZ |
3791 | |
3792 | <p>The question is whether it is a good idea to have such device routes in BIRD | |
3793 | routing table. OS kernel usually handles device routes for directly connected | |
3794 | networks by itself so we don't need (and don't want) to export these routes to | |
3795 | the kernel protocol. OSPF protocol creates device routes for its interfaces | |
159d619c OZ |
3796 | itself and BGP protocol is usually used for exporting aggregate routes. But the |
3797 | Direct protocol is necessary for distance-vector protocols like RIP or Babel to | |
3798 | announce local networks. | |
79a2b697 | 3799 | |
e90dd656 | 3800 | <p>There are just few configuration options for the Direct protocol: |
79a2b697 MM |
3801 | |
3802 | <p><descrip> | |
9df52a98 | 3803 | <tag><label id="direct-iface">interface <m/pattern/ [, <m/.../]</tag> |
dad92c30 OZ |
3804 | By default, the Direct protocol will generate device routes for all the |
3805 | interfaces available. If you want to restrict it to some subset of | |
d7c06285 OZ |
3806 | interfaces or addresses (e.g. if you're using multiple routing tables |
3807 | for policy routing and some of the policy domains don't contain all | |
b9864aa8 | 3808 | interfaces), just use this clause. See <ref id="proto-iface" name="interface"> |
d7c06285 OZ |
3809 | common option for detailed description. The Direct protocol uses |
3810 | extended interface clauses. | |
e90dd656 | 3811 | |
b9864aa8 | 3812 | <tag><label id="direct-check-link">check link <m/switch/</tag> |
e90dd656 OZ |
3813 | If enabled, a hardware link state (reported by OS) is taken into |
3814 | consideration. Routes for directly connected networks are generated only | |
3815 | if link up is reported and they are withdrawn when link disappears | |
3816 | (e.g., an ethernet cable is unplugged). Default value is no. | |
79a2b697 MM |
3817 | </descrip> |
3818 | ||
79a2b697 MM |
3819 | <p>Direct device routes don't contain any specific attributes. |
3820 | ||
4f88ac47 | 3821 | <p>Example config might look like this: |
79a2b697 MM |
3822 | |
3823 | <p><code> | |
3824 | protocol direct { | |
3e52d112 | 3825 | ipv4; |
3e52d112 | 3826 | ipv6; |
cf3e3845 | 3827 | interface "-arc*", "*"; # Exclude the ARCnets |
79a2b697 MM |
3828 | } |
3829 | </code> | |
3830 | ||
cf3e3845 | 3831 | |
371adba6 | 3832 | <sect>Kernel |
b9864aa8 | 3833 | <label id="krt"> |
1b55b1a3 | 3834 | |
0e4789c2 | 3835 | <p>The Kernel protocol is not a real routing protocol. Instead of communicating |
c429d4a4 | 3836 | with other routers in the network, it performs synchronization of BIRD's routing |
dad92c30 OZ |
3837 | tables with the OS kernel. Basically, it sends all routing table updates to the |
3838 | kernel and from time to time it scans the kernel tables to see whether some | |
3839 | routes have disappeared (for example due to unnoticed up/down transition of an | |
3840 | interface) or whether an `alien' route has been added by someone else (depending | |
3841 | on the <cf/learn/ switch, such routes are either ignored or accepted to our | |
f8e2d916 | 3842 | table). |
0e4789c2 | 3843 | |
d33cf3f4 | 3844 | <p>Note that routes created by OS kernel itself, namely direct routes |
e83beb70 PŠ |
3845 | representing IP subnets of associated interfaces, are imported only with |
3846 | <cf/learn all/ enabled. | |
c429d4a4 | 3847 | |
dad92c30 OZ |
3848 | <p>If your OS supports only a single routing table, you can configure only one |
3849 | instance of the Kernel protocol. If it supports multiple tables (in order to | |
3850 | allow policy routing; such an OS is for example Linux), you can run as many | |
3851 | instances as you want, but each of them must be connected to a different BIRD | |
3852 | routing table and to a different kernel table. | |
0e4789c2 | 3853 | |
dad92c30 OZ |
3854 | <p>Because the kernel protocol is partially integrated with the connected |
3855 | routing table, there are two limitations - it is not possible to connect more | |
3856 | kernel protocols to the same routing table and changing route destination | |
3857 | (gateway) in an export filter of a kernel protocol does not work. Both | |
3858 | limitations can be overcome using another routing table and the pipe protocol. | |
cf3e3845 | 3859 | |
159d619c OZ |
3860 | <p>The Kernel protocol supports both IPv4 and IPv6 channels; only one channel |
3861 | can be configured in each protocol instance. On Linux, it also supports <ref | |
3862 | id="ip-sadr-routes" name="IPv6 SADR"> and <ref id="mpls-routes" name="MPLS"> | |
3863 | channels. | |
71ca7716 | 3864 | |
371adba6 | 3865 | <sect1>Configuration |
b9864aa8 | 3866 | <label id="krt-config"> |
0e4789c2 MM |
3867 | |
3868 | <p><descrip> | |
b9864aa8 | 3869 | <tag><label id="krt-persist">persist <m/switch/</tag> |
6eda3f13 OZ |
3870 | Tell BIRD to leave all its routes in the routing tables when it exits |
3871 | (instead of cleaning them up). | |
3872 | ||
b9864aa8 | 3873 | <tag><label id="krt-scan-time">scan time <m/number/</tag> |
6eda3f13 OZ |
3874 | Time in seconds between two consecutive scans of the kernel routing |
3875 | table. | |
3876 | ||
e83beb70 | 3877 | <tag><label id="krt-learn">learn <m/switch/|all</tag> |
6eda3f13 OZ |
3878 | Enable learning of routes added to the kernel routing tables by other |
3879 | routing daemons or by the system administrator. This is possible only on | |
e83beb70 PŠ |
3880 | systems which support identification of route authorship. By default, |
3881 | routes created by kernel (marked as "proto kernel") are not imported. | |
3882 | Use <cf/learn all/ option to import even these routes. | |
6eda3f13 | 3883 | |
b9864aa8 | 3884 | <tag><label id="krt-kernel-table">kernel table <m/number/</tag> |
6eda3f13 OZ |
3885 | Select which kernel table should this particular instance of the Kernel |
3886 | protocol work with. Available only on systems supporting multiple | |
3887 | routing tables. | |
3888 | ||
b9864aa8 | 3889 | <tag><label id="krt-metric">metric <m/number/</tag> (Linux) |
4adcb9df OZ |
3890 | Use specified value as a kernel metric (priority) for all routes sent to |
3891 | the kernel. When multiple routes for the same network are in the kernel | |
3892 | routing table, the Linux kernel chooses one with lower metric. Also, | |
3893 | routes with different metrics do not clash with each other, therefore | |
3894 | using dedicated metric value is a reliable way to avoid overwriting | |
3895 | routes from other sources (e.g. kernel device routes). Metric 0 has a | |
3896 | special meaning of undefined metric, in which either OS default is used, | |
3897 | or per-route metric can be set using <cf/krt_metric/ attribute. Default: | |
bff21441 | 3898 | 32. |
4adcb9df | 3899 | |
b9864aa8 | 3900 | <tag><label id="krt-graceful-restart">graceful restart <m/switch/</tag> |
6eda3f13 OZ |
3901 | Participate in graceful restart recovery. If this option is enabled and |
3902 | a graceful restart recovery is active, the Kernel protocol will defer | |
3903 | synchronization of routing tables until the end of the recovery. Note | |
3904 | that import of kernel routes to BIRD is not affected. | |
8d9eef17 | 3905 | |
b9864aa8 | 3906 | <tag><label id="krt-merge-paths">merge paths <M>switch</M> [limit <M>number</M>]</tag> |
8d9eef17 OZ |
3907 | Usually, only best routes are exported to the kernel protocol. With path |
3908 | merging enabled, both best routes and equivalent non-best routes are | |
3909 | merged during export to generate one ECMP (equal-cost multipath) route | |
3910 | for each network. This is useful e.g. for BGP multipath. Note that best | |
3911 | routes are still pivotal for route export (responsible for most | |
3912 | properties of resulting ECMP routes), while exported non-best routes are | |
3913 | responsible just for additional multipath next hops. This option also | |
3914 | allows to specify a limit on maximal number of nexthops in one route. By | |
3915 | default, multipath merging is disabled. If enabled, default value of the | |
3916 | limit is 16. | |
81ee6cda OZ |
3917 | |
3918 | <tag><label id="krt-netlink-rx-buffer">netlink rx buffer <m/number/</tag> (Linux) | |
3919 | Set kernel receive buffer size (in bytes) for the netlink socket. The default | |
3920 | value is OS-dependent (from the <file>/proc/sys/net/core/rmem_default</file> | |
3921 | file), If you get some "Kernel dropped some netlink message ..." warnings, | |
3922 | you may increase this value. | |
0e4789c2 MM |
3923 | </descrip> |
3924 | ||
71ca7716 | 3925 | <sect1>Attributes |
b9864aa8 | 3926 | <label id="krt-attr"> |
71ca7716 | 3927 | |
dad92c30 OZ |
3928 | <p>The Kernel protocol defines several attributes. These attributes are |
3929 | translated to appropriate system (and OS-specific) route attributes. We support | |
3930 | these attributes: | |
71ca7716 OZ |
3931 | |
3932 | <descrip> | |
157f6c2a | 3933 | <tag><label id="rta-krt-source">int krt_source</tag> |
dad92c30 OZ |
3934 | The original source of the imported kernel route. The value is |
3935 | system-dependent. On Linux, it is a value of the protocol field of the | |
3936 | route. See /etc/iproute2/rt_protos for common values. On BSD, it is | |
72aed1a0 OZ |
3937 | based on STATIC and PROTOx flags. The attribute is read-only. |
3938 | ||
157f6c2a | 3939 | <tag><label id="rta-krt-metric">int krt_metric</tag> (Linux) |
dad92c30 OZ |
3940 | The kernel metric of the route. When multiple same routes are in a |
3941 | kernel routing table, the Linux kernel chooses one with lower metric. | |
4adcb9df OZ |
3942 | Note that preferred way to set kernel metric is to use protocol option |
3943 | <cf/metric/, unless per-route metric values are needed. | |
9ba2798c | 3944 | |
157f6c2a | 3945 | <tag><label id="rta-krt-prefsrc">ip krt_prefsrc</tag> (Linux) |
dad92c30 | 3946 | The preferred source address. Used in source address selection for |
79a4f74a | 3947 | outgoing packets. Has to be one of the IP addresses of the router. |
71ca7716 | 3948 | |
157f6c2a | 3949 | <tag><label id="rta-krt-realm">int krt_realm</tag> (Linux) |
dad92c30 | 3950 | The realm of the route. Can be used for traffic classification. |
6e75d0d2 | 3951 | |
157f6c2a | 3952 | <tag><label id="rta-krt-scope">int krt_scope</tag> (Linux IPv4) |
6e75d0d2 OZ |
3953 | The scope of the route. Valid values are 0-254, although Linux kernel |
3954 | may reject some values depending on route type and nexthop. It is | |
3955 | supposed to represent `indirectness' of the route, where nexthops of | |
3956 | routes are resolved through routes with a higher scope, but in current | |
3957 | kernels anything below <it/link/ (253) is treated as <it/global/ (0). | |
3958 | When not present, global scope is implied for all routes except device | |
3959 | routes, where link scope is used by default. | |
71ca7716 OZ |
3960 | </descrip> |
3961 | ||
6683d42d OZ |
3962 | <p>In Linux, there is also a plenty of obscure route attributes mostly focused |
3963 | on tuning TCP performance of local connections. BIRD supports most of these | |
3964 | attributes, see Linux or iproute2 documentation for their meaning. Attributes | |
225943ea OZ |
3965 | <cf/krt_lock_*/ and <cf/krt_feature_*/ have type bool, <cf/krt_congctl/ has type |
3966 | string, others have type int. Supported attributes are: | |
6683d42d OZ |
3967 | |
3968 | <cf/krt_mtu/, <cf/krt_lock_mtu/, <cf/krt_window/, <cf/krt_lock_window/, | |
3969 | <cf/krt_rtt/, <cf/krt_lock_rtt/, <cf/krt_rttvar/, <cf/krt_lock_rttvar/, | |
5c04f0e2 | 3970 | <cf/krt_ssthresh/, <cf/krt_lock_ssthresh/, <cf/krt_cwnd/, <cf/krt_lock_cwnd/, |
6683d42d OZ |
3971 | <cf/krt_advmss/, <cf/krt_lock_advmss/, <cf/krt_reordering/, <cf/krt_lock_reordering/, |
3972 | <cf/krt_hoplimit/, <cf/krt_lock_hoplimit/, <cf/krt_rto_min/, <cf/krt_lock_rto_min/, | |
e6836390 OZ |
3973 | <cf/krt_initcwnd/, <cf/krt_lock_initcwnd/, <cf/krt_initrwnd/, <cf/krt_lock_initrwnd/, |
3974 | <cf/krt_quickack/, <cf/krt_lock_quickack/, <cf/krt_congctl/, <cf/krt_lock_congctl/, | |
3975 | <cf/krt_fastopen_no_cookie/, <cf/krt_lock_fastopen_no_cookie/, | |
6683d42d OZ |
3976 | <cf/krt_feature_ecn/, <cf/krt_feature_allfrag/ |
3977 | ||
71ca7716 | 3978 | <sect1>Example |
b9864aa8 | 3979 | <label id="krt-exam"> |
71ca7716 | 3980 | |
326e33f5 | 3981 | <p>A simple configuration can look this way: |
0e4789c2 MM |
3982 | |
3983 | <p><code> | |
3984 | protocol kernel { | |
0e4789c2 MM |
3985 | export all; |
3986 | } | |
3987 | </code> | |
3988 | ||
3989 | <p>Or for a system with two routing tables: | |
3990 | ||
3991 | <p><code> | |
3992 | protocol kernel { # Primary routing table | |
3993 | learn; # Learn alien routes from the kernel | |
cab5fce2 | 3994 | persist; # Do not remove routes on bird shutdown |
0e4789c2 | 3995 | scan time 10; # Scan kernel routing table every 10 seconds |
3e52d112 JMM |
3996 | ipv4 { |
3997 | import all; | |
3998 | export all; | |
3999 | }; | |
0e4789c2 MM |
4000 | } |
4001 | ||
4002 | protocol kernel { # Secondary routing table | |
0e4789c2 | 4003 | kernel table 100; |
3e52d112 JMM |
4004 | ipv4 { |
4005 | table auxtable; | |
4006 | export all; | |
4007 | }; | |
a2a3ced8 | 4008 | } |
0e4789c2 MM |
4009 | </code> |
4010 | ||
dad92c30 | 4011 | |
cab5fce2 OZ |
4012 | <sect>L3VPN |
4013 | <label id="l3vpn"> | |
4014 | ||
4015 | <sect1>Introduction | |
4016 | <label id="l3vpn-intro"> | |
4017 | ||
4018 | <p>The L3VPN protocol serves as a translator between IP routes and VPN | |
4019 | routes. It is a component for BGP/MPLS IP VPNs (<rfc id="4364">) and implements | |
4020 | policies defined there. In import direction (VPN -> IP), VPN routes matching | |
4021 | import target specification are stripped of route distinguisher and MPLS labels | |
4022 | and announced as IP routes, In export direction (IP -> VPN), IP routes are | |
4023 | expanded with specific route distinguisher, export target communities and MPLS | |
4024 | label and announced as labeled VPN routes. Unlike the Pipe protocol, the L3VPN | |
4025 | protocol propagates just the best route for each network. | |
4026 | ||
4027 | <p>In BGP/MPLS IP VPNs, route distribution is controlled by Route Targets (RT). | |
4028 | VRFs are associated with one or more RTs. Routes are also associated with one or | |
4029 | more RTs, which are encoded as route target extended communities | |
4030 | in <ref id="rta-bgp-ext-community" name="bgp_ext_community">. A route is then | |
4031 | imported into each VRF that shares an associated Route Target. The L3VPN | |
4032 | protocol implements this mechanism through mandatory <cf/import target/ and | |
4033 | <cf/export target/ protocol options. | |
4034 | ||
4035 | <sect1>Configuration | |
4036 | <label id="l3vpn-config"> | |
4037 | ||
4038 | <p>L3VPN configuration consists of a few mandatory options and multiple channel | |
4039 | definitions. For convenience, the default export filter in L3VPN channels is | |
4040 | <cf/all/, as the primary way to control import and export of routes is through | |
4041 | protocol options <cf/import target/ and <cf/export target/. If custom filters | |
4042 | are used, note that the export filter of the input channel is applied before | |
4043 | the route translation, while the import filter of the output channel is applied | |
4044 | after that. | |
4045 | ||
4046 | <p>In contrast to the Pipe protocol, the L3VPN protocol can handle both IPv4 and | |
4047 | IPv6 routes in one instance, also both IP side and VPN side are represented as | |
4048 | separate channels, although that may change in the future. The L3VPN is always | |
4049 | MPLS-aware protocol, therefore a MPLS channel is mandatory. Altogether, L3VPN | |
4050 | could have up to 5 channels: <cf/ipv4/, <cf/ipv6/, <cf/vpn4/, <cf/vpn6/, and | |
4051 | <cf/mpls/. | |
4052 | ||
4053 | <p><descrip> | |
0bfa216f | 4054 | <tag><label id="l3vpn-route-distinguisher">route distinguisher <m/vpnrd/</tag> |
cab5fce2 OZ |
4055 | The route distinguisher that is attached to routes in the export |
4056 | direction. Mandatory. | |
4057 | ||
0bfa216f OZ |
4058 | <tag><label id="l3vpn-rd">rd <m/vpnrd/</tag> |
4059 | A shorthand for the option <cf/route distinguisher/. | |
4060 | ||
cab5fce2 OZ |
4061 | <tag><label id="l3vpn-import-target">import target <m/ec/|<m/ec-set/</tag> |
4062 | Route target extended communities specifying which routes should be | |
4063 | imported. Either one community or a set. A route is imported if there is | |
4064 | non-empty intersection between extended communities of the route and the | |
4065 | import target of the L3VPN protocol. Mandatory. | |
4066 | ||
4067 | <tag><label id="l3vpn-export-target">export target <m/ec/|<m/ec-set/</tag> | |
4068 | Route target extended communities that are attached to the route in the | |
4069 | export direction. Either one community or a set. Other route target | |
4070 | extended communities are removed. Mandatory. | |
4071 | ||
4072 | <tag><label id="l3vpn-route-target">route target <m/ec/|<m/ec-set/</tag> | |
4073 | A shorthand for both <cf/import target/ and <cf/export target/. | |
4074 | </descrip> | |
4075 | ||
4076 | <sect1>Attributes | |
4077 | <label id="l3vpn-attr"> | |
4078 | ||
4079 | <p>The L3VPN protocol does not define any route attributes. | |
4080 | ||
4081 | <sect1>Example | |
4082 | <label id="l3vpn-exam"> | |
4083 | ||
4084 | <p>Here is an example of L3VPN setup with one VPN and BGP uplink. IP routes | |
4085 | learned from a customer in the VPN are stored in <cf/vrf0vX/ tables, which are | |
4086 | mapped to kernel VRF vrf0. Routes can also be exchanged through BGP with | |
4087 | different sites hosting that VPN. Forwarding of VPN traffic through the network | |
4088 | is handled by MPLS. | |
4089 | ||
4090 | <p>Omitted from the example are some routing protocol to exchange routes with | |
4091 | the customer and some sort of MPLS-aware IGP to resolve next hops for BGP VPN | |
4092 | routes. | |
4093 | ||
4094 | <code> | |
4095 | # MPLS basics | |
4096 | mpls domain mdom; | |
4097 | mpls table mtab; | |
4098 | ||
4099 | protocol kernel krt_mpls { | |
4100 | mpls { table mtab; export all; }; | |
4101 | } | |
4102 | ||
4103 | vpn4 table vpntab4; | |
4104 | vpn6 table vpntab6; | |
4105 | ||
4106 | # Exchange VPN routes through BGP | |
4107 | protocol bgp { | |
4108 | vpn4 { table vpntab4; import all; export all; }; | |
4109 | vpn6 { table vpntab6; import all; export all; }; | |
4110 | mpls { label policy aggregate; }; | |
4111 | local 10.0.0.1 as 10; | |
4112 | neighbor 10.0.0.2 as 10; | |
4113 | } | |
4114 | ||
4115 | # VRF 0 | |
4116 | ipv4 table vrf0v4; | |
4117 | ipv6 table vrf0v6; | |
4118 | ||
4119 | protocol kernel kernel0v4 { | |
4120 | vrf "vrf0"; | |
4121 | ipv4 { table vrf0v4; export all; }; | |
4122 | kernel table 100; | |
4123 | } | |
4124 | ||
4125 | protocol kernel kernel0v6 { | |
4126 | vrf "vrf0"; | |
4127 | ipv6 { table vrf0v6; export all; }; | |
4128 | kernel table 100; | |
4129 | } | |
4130 | ||
4131 | protocol l3vpn l3vpn0 { | |
4132 | vrf "vrf0"; | |
4133 | ipv4 { table vrf0v4; }; | |
4134 | ipv6 { table vrf0v6; }; | |
4135 | vpn4 { table vpntab4; }; | |
4136 | vpn6 { table vpntab6; }; | |
4137 | mpls { label policy vrf; }; | |
4138 | ||
4139 | rd 10:12; | |
4140 | import target [(rt, 10, 32..40)]; | |
4141 | export target [(rt, 10, 30), (rt, 10, 31)]; | |
4142 | } | |
4143 | </code> | |
4144 | ||
4145 | ||
fc1b9333 OZ |
4146 | <sect>MRT |
4147 | <label id="mrt"> | |
4148 | ||
4149 | <sect1>Introduction | |
4150 | <label id="mrt-intro"> | |
4151 | ||
4152 | <p>The MRT protocol is a component responsible for handling the Multi-Threaded | |
4153 | Routing Toolkit (MRT) routing information export format, which is mainly used | |
4154 | for collecting and analyzing of routing information from BGP routers. The MRT | |
4155 | protocol can be configured to do periodic dumps of routing tables, created MRT | |
4156 | files can be analyzed later by other tools. Independent MRT table dumps can also | |
4157 | be requested from BIRD client. There is also a feature to save incoming BGP | |
4158 | messages in MRT files, but it is controlled by <ref id="proto-mrtdump" | |
4159 | name="mrtdump"> options independently of MRT protocol, although that might | |
4160 | change in the future. | |
4161 | ||
4162 | BIRD implements the main MRT format specification as defined in <rfc id="6396"> | |
4163 | and the ADD_PATH extension (<rfc id="8050">). | |
4164 | ||
4165 | <sect1>Configuration | |
4166 | <label id="mrt-config"> | |
4167 | ||
4168 | <p>MRT configuration consists of several statements describing routing table | |
4169 | dumps. Multiple independent periodic dumps can be done as multiple MRT protocol | |
4170 | instances. The MRT protocol does not use channels. There are two mandatory | |
4171 | statements: <cf/filename/ and <cf/period/. | |
4172 | ||
4173 | The behavior can be modified by following configuration parameters: | |
4174 | ||
4175 | <descrip> | |
4176 | <tag><label id="mrt-table">table <m/name/ | "<m/pattern/"</tag> | |
4177 | Specify a routing table (or a set of routing tables described by a | |
4178 | wildcard pattern) that are to be dumped by the MRT protocol instance. | |
4179 | Default: the master table. | |
4180 | ||
4181 | <tag><label id="mrt-filter">filter { <m/filter commands/ }</tag> | |
4182 | The MRT protocol allows to specify a filter that is applied to routes as | |
4183 | they are dumped. Rejected routes are ignored and not saved to the MRT | |
4184 | dump file. Default: no filter. | |
4185 | ||
4186 | <tag><label id="mrt-where">where <m/filter expression/</tag> | |
4187 | An alternative way to specify a filter for the MRT protocol. | |
4188 | ||
4189 | <tag><label id="mrt-filename">filename "<m/filename/"</tag> | |
4190 | Specify a filename for MRT dump files. The filename may contain time | |
4191 | format sequences with <it/strftime(3)/ notation (see <it/man strftime/ | |
4192 | for details), there is also a sequence "%N" that is expanded to the name | |
4193 | of dumped table. Therefore, each periodic dump of each table can be | |
4194 | saved to a different file. Mandatory, see example below. | |
4195 | ||
4196 | <tag><label id="mrt-period">period <m/number/</tag> | |
4197 | Specify the time interval (in seconds) between periodic dumps. | |
4198 | Mandatory. | |
4199 | ||
4200 | <tag><label id="mrt-always-add-path">always add path <m/switch/</tag> | |
4201 | The MRT format uses special records (specified in <rfc id="8050">) for | |
4202 | routes received using BGP ADD_PATH extension to keep Path ID, while | |
4203 | other routes use regular records. This has advantage of better | |
4204 | compatibility with tools that do not know special records, but it loses | |
4205 | information about which route is the best route. When this option is | |
4206 | enabled, both ADD_PATH and non-ADD_PATH routes are stored in ADD_PATH | |
4207 | records and order of routes for network is preserved. Default: disabled. | |
4208 | </descrip> | |
4209 | ||
4210 | <sect1>Example | |
4211 | <label id="mrt-exam"> | |
4212 | ||
4213 | <p><code> | |
4214 | protocol mrt { | |
4215 | table "tab*"; | |
4216 | where source = RTS_BGP; | |
4217 | filename "/var/log/bird/%N_%F_%T.mrt"; | |
4218 | period 300; | |
4219 | } | |
4220 | </code> | |
4221 | ||
4222 | ||
371adba6 | 4223 | <sect>OSPF |
b9864aa8 | 4224 | <label id="ospf"> |
1b55b1a3 | 4225 | |
8fd12e6b | 4226 | <sect1>Introduction |
b9864aa8 | 4227 | <label id="ospf-intro"> |
8fd12e6b | 4228 | |
3ca3e999 | 4229 | <p>Open Shortest Path First (OSPF) is a quite complex interior gateway |
7935b9d2 PT |
4230 | protocol. The current IPv4 version (OSPFv2) is defined in <rfc id="2328"> and |
4231 | the current IPv6 version (OSPFv3) is defined in <rfc id="5340"> It's a link | |
4232 | state (a.k.a. shortest path first) protocol -- each router maintains a database | |
4233 | describing the autonomous system's topology. Each participating router has an | |
4234 | identical copy of the database and all routers run the same algorithm | |
4235 | calculating a shortest path tree with themselves as a root. OSPF chooses the | |
4236 | least cost path as the best path. | |
dad92c30 OZ |
4237 | |
4238 | <p>In OSPF, the autonomous system can be split to several areas in order to | |
4239 | reduce the amount of resources consumed for exchanging the routing information | |
4240 | and to protect the other areas from incorrect routing data. Topology of the area | |
4241 | is hidden to the rest of the autonomous system. | |
4242 | ||
4243 | <p>Another very important feature of OSPF is that it can keep routing information | |
4244 | from other protocols (like Static or BGP) in its link state database as external | |
4245 | routes. Each external route can be tagged by the advertising router, making it | |
4246 | possible to pass additional information between routers on the boundary of the | |
4247 | autonomous system. | |
4248 | ||
4249 | <p>OSPF quickly detects topological changes in the autonomous system (such as | |
4250 | router interface failures) and calculates new loop-free routes after a short | |
4251 | period of convergence. Only a minimal amount of routing traffic is involved. | |
8fd12e6b | 4252 | |
3ca3e999 | 4253 | <p>Each router participating in OSPF routing periodically sends Hello messages |
dad92c30 OZ |
4254 | to all its interfaces. This allows neighbors to be discovered dynamically. Then |
4255 | the neighbors exchange theirs parts of the link state database and keep it | |
4256 | identical by flooding updates. The flooding process is reliable and ensures that | |
4257 | each router detects all changes. | |
8fd12e6b OF |
4258 | |
4259 | <sect1>Configuration | |
b9864aa8 | 4260 | <label id="ospf-config"> |
8fd12e6b | 4261 | |
da3cf9ea OZ |
4262 | <p>First, the desired OSPF version can be specified by using <cf/ospf v2/ or |
4263 | <cf/ospf v3/ as a protocol type. By default, OSPFv2 is used. In the main part of | |
4264 | configuration, there can be multiple definitions of OSPF areas, each with a | |
4265 | different id. These definitions includes many other switches and multiple | |
4266 | definitions of interfaces. Definition of interface may contain many switches and | |
4267 | constant definitions and list of neighbors on nonbroadcast networks. | |
8fd12e6b | 4268 | |
cf3e3845 OZ |
4269 | <p>OSPFv2 needs one IPv4 channel. OSPFv3 needs either one IPv6 channel, or one |
4270 | IPv4 channel (<rfc id="5838">). Therefore, it is possible to use OSPFv3 for both | |
4271 | IPv4 and Pv6 routing, but it is necessary to have two protocol instances anyway. | |
4272 | If no channel is configured, appropriate channel is defined with default | |
4273 | parameters. | |
3e52d112 | 4274 | |
8fd12e6b | 4275 | <code> |
da3cf9ea | 4276 | protocol ospf [v2|v3] <name> { |
1632f1fe | 4277 | rfc1583compat <switch>; |
2d7fb19c | 4278 | rfc5838 <switch>; |
178a197a | 4279 | instance id <num>; |
f623ab98 | 4280 | stub router <switch>; |
62eee823 | 4281 | tick <num>; |
e91f6960 | 4282 | ecmp <switch> [limit <num>]; |
145368f5 | 4283 | merge external <switch>; |
6c0f85d5 OZ |
4284 | graceful restart <switch>|aware; |
4285 | graceful restart time <num>; | |
088bc8ad | 4286 | area <id> { |
2918e610 OZ |
4287 | stub; |
4288 | nssa; | |
bde872bb | 4289 | summary <switch>; |
2918e610 OZ |
4290 | default nssa <switch>; |
4291 | default cost <num>; | |
4292 | default cost2 <num>; | |
bde872bb OZ |
4293 | translator <switch>; |
4294 | translator stability <num>; | |
4295 | ||
16319aeb OF |
4296 | networks { |
4297 | <prefix>; | |
4298 | <prefix> hidden; | |
6c11dbcf | 4299 | }; |
bde872bb OZ |
4300 | external { |
4301 | <prefix>; | |
4302 | <prefix> hidden; | |
4303 | <prefix> tag <num>; | |
6c11dbcf | 4304 | }; |
38675202 OZ |
4305 | stubnet <prefix>; |
4306 | stubnet <prefix> { | |
4307 | hidden <switch>; | |
4308 | summary <switch>; | |
4309 | cost <num>; | |
6c11dbcf | 4310 | }; |
0ec031f7 | 4311 | interface <interface pattern> [instance <num>] { |
088bc8ad | 4312 | cost <num>; |
e3bc10fd | 4313 | stub <switch>; |
088bc8ad | 4314 | hello <num>; |
a190e720 | 4315 | poll <num>; |
088bc8ad OF |
4316 | retransmit <num>; |
4317 | priority <num>; | |
4318 | wait <num>; | |
4319 | dead count <num>; | |
d8c7d9e8 | 4320 | dead <num>; |
48e5f32d | 4321 | secondary <switch>; |
94c42054 | 4322 | rx buffer [normal|large|<num>]; |
48e5f32d | 4323 | tx length <num>; |
919f5411 OZ |
4324 | type [broadcast|bcast|pointopoint|ptp| |
4325 | nonbroadcast|nbma|pointomultipoint|ptmp]; | |
70945cb6 | 4326 | link lsa suppression <switch>; |
a190e720 | 4327 | strict nonbroadcast <switch>; |
95127cbb | 4328 | real broadcast <switch>; |
8df02847 | 4329 | ptp netmask <switch>; |
71e08edd | 4330 | ptp address <switch>; |
e91f6960 | 4331 | check link <switch>; |
1ec52253 | 4332 | bfd <switch>; |
e91f6960 | 4333 | ecmp weight <num>; |
6ac4f87a OZ |
4334 | ttl security [<switch>; | tx only] |
4335 | tx class|dscp <num>; | |
4336 | tx priority <num>; | |
64385aee | 4337 | authentication none|simple|cryptographic; |
088bc8ad | 4338 | password "<text>"; |
b21f68b4 OZ |
4339 | password "<text>" { |
4340 | id <num>; | |
4341 | generate from "<date>"; | |
4342 | generate to "<date>"; | |
4343 | accept from "<date>"; | |
4344 | accept to "<date>"; | |
64385aee PT |
4345 | from "<date>"; |
4346 | to "<date>"; | |
4347 | algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 ); | |
ea357b8b | 4348 | }; |
8fd12e6b | 4349 | neighbors { |
088bc8ad | 4350 | <ip>; |
a190e720 | 4351 | <ip> eligible; |
8fd12e6b OF |
4352 | }; |
4353 | }; | |
0ec031f7 | 4354 | virtual link <id> [instance <num>] { |
98ac6176 | 4355 | hello <num>; |
98ac6176 OF |
4356 | retransmit <num>; |
4357 | wait <num>; | |
4358 | dead count <num>; | |
d8c7d9e8 | 4359 | dead <num>; |
64385aee | 4360 | authentication none|simple|cryptographic; |
98ac6176 | 4361 | password "<text>"; |
64385aee PT |
4362 | password "<text>" { |
4363 | id <num>; | |
4364 | generate from "<date>"; | |
4365 | generate to "<date>"; | |
4366 | accept from "<date>"; | |
4367 | accept to "<date>"; | |
4368 | from "<date>"; | |
4369 | to "<date>"; | |
4370 | algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 ); | |
4371 | }; | |
98ac6176 | 4372 | }; |
8fd12e6b OF |
4373 | }; |
4374 | } | |
4375 | </code> | |
4376 | ||
4377 | <descrip> | |
b9864aa8 | 4378 | <tag><label id="ospf-rfc1583compat">rfc1583compat <M>switch</M></tag> |
dad92c30 | 4379 | This option controls compatibility of routing table calculation with |
7935b9d2 | 4380 | <rfc id="1583">. Default value is no. |
e91f6960 | 4381 | |
2d7fb19c OZ |
4382 | <tag><label id="ospf-rfc5838">rfc5838 <m/switch/</tag> |
4383 | Basic OSPFv3 is limited to IPv6 unicast routing. The <rfc id="5838"> | |
4384 | extension defines support for more address families (IPv4, IPv6, both | |
4385 | unicast and multicast). The extension is enabled by default, but can be | |
4386 | disabled if necessary, as it restricts the range of available instance | |
4387 | IDs. Default value is yes. | |
4388 | ||
b9864aa8 | 4389 | <tag><label id="ospf-instance-id">instance id <m/num/</tag> |
178a197a OZ |
4390 | When multiple OSPF protocol instances are active on the same links, they |
4391 | should use different instance IDs to distinguish their packets. Although | |
4392 | it could be done on per-interface basis, it is often preferred to set | |
4393 | one instance ID to whole OSPF domain/topology (e.g., when multiple | |
4394 | instances are used to represent separate logical topologies on the same | |
2d7fb19c OZ |
4395 | physical network). This option specifies the instance ID for all |
4396 | interfaces of the OSPF instance, but can be overridden by | |
4397 | <cf/interface/ option. Default value is 0 unless OSPFv3-AF extended | |
4398 | address families are used, see <rfc id="5838"> for that case. | |
178a197a | 4399 | |
b9864aa8 | 4400 | <tag><label id="ospf-stub-router">stub router <M>switch</M></tag> |
dad92c30 OZ |
4401 | This option configures the router to be a stub router, i.e., a router |
4402 | that participates in the OSPF topology but does not allow transit | |
4403 | traffic. In OSPFv2, this is implemented by advertising maximum metric | |
178a197a | 4404 | for outgoing links. In OSPFv3, the stub router behavior is announced by |
7935b9d2 PT |
4405 | clearing the R-bit in the router LSA. See <rfc id="6987"> for details. |
4406 | Default value is no. | |
f623ab98 | 4407 | |
b9864aa8 | 4408 | <tag><label id="ospf-tick">tick <M>num</M></tag> |
dad92c30 OZ |
4409 | The routing table calculation and clean-up of areas' databases is not |
4410 | performed when a single link state change arrives. To lower the CPU | |
4411 | utilization, it's processed later at periodical intervals of <m/num/ | |
4412 | seconds. The default value is 1. | |
e91f6960 | 4413 | |
b9864aa8 | 4414 | <tag><label id="ospf-ecmp">ecmp <M>switch</M> [limit <M>number</M>]</tag> |
dad92c30 OZ |
4415 | This option specifies whether OSPF is allowed to generate ECMP |
4416 | (equal-cost multipath) routes. Such routes are used when there are | |
4417 | several directions to the destination, each with the same (computed) | |
8465dccb | 4418 | cost. This option also allows to specify a limit on maximum number of |
cf3e3845 OZ |
4419 | nexthops in one route. By default, ECMP is enabled if supported by |
4420 | Kernel. Default value of the limit is 16. | |
e91f6960 | 4421 | |
b9864aa8 | 4422 | <tag><label id="ospf-merge-external">merge external <M>switch</M></tag> |
145368f5 OZ |
4423 | This option specifies whether OSPF should merge external routes from |
4424 | different routers/LSAs for the same destination. When enabled together | |
4425 | with <cf/ecmp/, equal-cost external routes will be combined to multipath | |
4426 | routes in the same way as regular routes. When disabled, external routes | |
4427 | from different LSAs are treated as separate even if they represents the | |
4428 | same destination. Default value is no. | |
4429 | ||
6c0f85d5 OZ |
4430 | <tag><label id="ospf-graceful-restart">graceful restart <m/switch/|aware</tag> |
4431 | When an OSPF instance is restarted, neighbors break adjacencies and | |
4432 | recalculate their routing tables, which disrupts packet forwarding even | |
4433 | when the forwarding plane of the restarting router remains intact. | |
4434 | <rfc id="3623"> specifies a graceful restart mechanism to alleviate this | |
4435 | issue. For OSPF graceful restart, restarting router originates | |
4436 | Grace-LSAs, announcing intent to do graceful restart. Neighbors | |
4437 | receiving these LSAs enter helper mode, in which they ignore breakdown | |
4438 | of adjacencies, behave as if nothing is happening and keep old routes. | |
4439 | When adjacencies are reestablished, the restarting router flushes | |
4440 | Grace-LSAs and graceful restart is ended. | |
4441 | ||
4442 | This option controls the graceful restart mechanism. It has three | |
4443 | states: Disabled, when no support is provided. Aware, when graceful | |
4444 | restart helper mode is supported, but no local graceful restart is | |
4445 | allowed (i.e. helper-only role). Enabled, when the full graceful restart | |
4446 | support is provided (i.e. both restarting and helper role). Note that | |
4447 | proper support for local graceful restart requires also configuration of | |
4448 | other protocols. Default: aware. | |
4449 | ||
4450 | <tag><label id="ospf-graceful-restart-time">graceful restart time <m/num/</tag> | |
4451 | The restart time is announced in the Grace-LSA and specifies how long | |
4452 | neighbors should wait for proper end of the graceful restart before | |
4453 | exiting helper mode prematurely. Default: 120 seconds. | |
4454 | ||
b9864aa8 | 4455 | <tag><label id="ospf-area">area <M>id</M></tag> |
dad92c30 OZ |
4456 | This defines an OSPF area with given area ID (an integer or an IPv4 |
4457 | address, similarly to a router ID). The most important area is the | |
4458 | backbone (ID 0) to which every other area must be connected. | |
8fd12e6b | 4459 | |
b9864aa8 | 4460 | <tag><label id="ospf-stub">stub</tag> |
dad92c30 OZ |
4461 | This option configures the area to be a stub area. External routes are |
4462 | not flooded into stub areas. Also summary LSAs can be limited in stub | |
4463 | areas (see option <cf/summary/). By default, the area is not a stub | |
4464 | area. | |
bde872bb | 4465 | |
b9864aa8 | 4466 | <tag><label id="ospf-nssa">nssa</tag> |
dad92c30 OZ |
4467 | This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA |
4468 | is a variant of a stub area which allows a limited way of external route | |
4469 | propagation. Global external routes are not propagated into a NSSA, but | |
4470 | an external route can be imported into NSSA as a (area-wide) NSSA-LSA | |
4471 | (and possibly translated and/or aggregated on area boundary). By | |
4472 | default, the area is not NSSA. | |
bde872bb | 4473 | |
b9864aa8 | 4474 | <tag><label id="ospf-summary">summary <M>switch</M></tag> |
dad92c30 OZ |
4475 | This option controls propagation of summary LSAs into stub or NSSA |
4476 | areas. If enabled, summary LSAs are propagated as usual, otherwise just | |
4477 | the default summary route (0.0.0.0/0) is propagated (this is sometimes | |
4478 | called totally stubby area). If a stub area has more area boundary | |
4479 | routers, propagating summary LSAs could lead to more efficient routing | |
4480 | at the cost of larger link state database. Default value is no. | |
bde872bb | 4481 | |
b9864aa8 | 4482 | <tag><label id="ospf-default-nssa">default nssa <M>switch</M></tag> |
dad92c30 OZ |
4483 | When <cf/summary/ option is enabled, default summary route is no longer |
4484 | propagated to the NSSA. In that case, this option allows to originate | |
4485 | default route as NSSA-LSA to the NSSA. Default value is no. | |
2918e610 | 4486 | |
b9864aa8 | 4487 | <tag><label id="ospf-default-cost">default cost <M>num</M></tag> |
dad92c30 OZ |
4488 | This option controls the cost of a default route propagated to stub and |
4489 | NSSA areas. Default value is 1000. | |
bde872bb | 4490 | |
b9864aa8 | 4491 | <tag><label id="ospf-default-cost2">default cost2 <M>num</M></tag> |
dad92c30 OZ |
4492 | When a default route is originated as NSSA-LSA, its cost can use either |
4493 | type 1 or type 2 metric. This option allows to specify the cost of a | |
4494 | default route in type 2 metric. By default, type 1 metric (option | |
4495 | <cf/default cost/) is used. | |
2918e610 | 4496 | |
b9864aa8 | 4497 | <tag><label id="ospf-translator">translator <M>switch</M></tag> |
dad92c30 OZ |
4498 | This option controls translation of NSSA-LSAs into external LSAs. By |
4499 | default, one translator per NSSA is automatically elected from area | |
4500 | boundary routers. If enabled, this area boundary router would | |
4501 | unconditionally translate all NSSA-LSAs regardless of translator | |
4502 | election. Default value is no. | |
bde872bb | 4503 | |
b9864aa8 | 4504 | <tag><label id="ospf-translator-stability">translator stability <M>num</M></tag> |
dad92c30 OZ |
4505 | This option controls the translator stability interval (in seconds). |
4506 | When the new translator is elected, the old one keeps translating until | |
4507 | the interval is over. Default value is 40. | |
8fd12e6b | 4508 | |
b9864aa8 | 4509 | <tag><label id="ospf-networks">networks { <m/set/ }</tag> |
dad92c30 OZ |
4510 | Definition of area IP ranges. This is used in summary LSA origination. |
4511 | Hidden networks are not propagated into other areas. | |
16319aeb | 4512 | |
b9864aa8 | 4513 | <tag><label id="ospf-external">external { <m/set/ }</tag> |
dad92c30 OZ |
4514 | Definition of external area IP ranges for NSSAs. This is used for |
4515 | NSSA-LSA translation. Hidden networks are not translated into external | |
4516 | LSAs. Networks can have configured route tag. | |
bde872bb | 4517 | |
b9864aa8 | 4518 | <tag><label id="ospf-stubnet">stubnet <m/prefix/ { <m/options/ }</tag> |
dad92c30 OZ |
4519 | Stub networks are networks that are not transit networks between OSPF |
4520 | routers. They are also propagated through an OSPF area as a part of a | |
4521 | link state database. By default, BIRD generates a stub network record | |
4522 | for each primary network address on each OSPF interface that does not | |
4523 | have any OSPF neighbors, and also for each non-primary network address | |
4524 | on each OSPF interface. This option allows to alter a set of stub | |
4525 | networks propagated by this router. | |
4526 | ||
4527 | Each instance of this option adds a stub network with given network | |
4528 | prefix to the set of propagated stub network, unless option <cf/hidden/ | |
4529 | is used. It also suppresses default stub networks for given network | |
4530 | prefix. When option <cf/summary/ is used, also default stub networks | |
4531 | that are subnetworks of given stub network are suppressed. This might be | |
4532 | used, for example, to aggregate generated stub networks. | |
178a197a | 4533 | |
b9864aa8 | 4534 | <tag><label id="ospf-iface">interface <M>pattern</M> [instance <m/num/]</tag> |
dad92c30 | 4535 | Defines that the specified interfaces belong to the area being defined. |
b9864aa8 | 4536 | See <ref id="proto-iface" name="interface"> common option for detailed |
d7c06285 | 4537 | description. In OSPFv2, extended interface clauses are used, because |
178a197a OZ |
4538 | each network prefix is handled as a separate virtual interface. |
4539 | ||
4540 | You can specify alternative instance ID for the interface definition, | |
4541 | therefore it is possible to have several instances of that interface | |
7935b9d2 PT |
4542 | with different options or even in different areas. For OSPFv2, instance |
4543 | ID support is an extension (<rfc id="6549">) and is supposed to be set | |
4544 | per-protocol. For OSPFv3, it is an integral feature. | |
0ec031f7 | 4545 | |
b9864aa8 | 4546 | <tag><label id="ospf-virtual-link">virtual link <M>id</M> [instance <m/num/]</tag> |
dad92c30 OZ |
4547 | Virtual link to router with the router id. Virtual link acts as a |
4548 | point-to-point interface belonging to backbone. The actual area is used | |
178a197a OZ |
4549 | as a transport area. This item cannot be in the backbone. Like with |
4550 | <cf/interface/ option, you could also use several virtual links to one | |
4551 | destination with different instance IDs. | |
98ac6176 | 4552 | |
b9864aa8 | 4553 | <tag><label id="ospf-cost">cost <M>num</M></tag> |
dad92c30 | 4554 | Specifies output cost (metric) of an interface. Default value is 10. |
8fd12e6b | 4555 | |
b9864aa8 | 4556 | <tag><label id="ospf-stub-iface">stub <M>switch</M></tag> |
dad92c30 OZ |
4557 | If set to interface it does not listen to any packet and does not send |
4558 | any hello. Default value is no. | |
e3bc10fd | 4559 | |
b9864aa8 | 4560 | <tag><label id="ospf-hello">hello <M>num</M></tag> |
dad92c30 OZ |
4561 | Specifies interval in seconds between sending of Hello messages. Beware, |
4562 | all routers on the same network need to have the same hello interval. | |
4563 | Default value is 10. | |
8fd12e6b | 4564 | |
b9864aa8 | 4565 | <tag><label id="ospf-poll">poll <M>num</M></tag> |
dad92c30 OZ |
4566 | Specifies interval in seconds between sending of Hello messages for some |
4567 | neighbors on NBMA network. Default value is 20. | |
a190e720 | 4568 | |
b9864aa8 | 4569 | <tag><label id="ospf-retransmit">retransmit <M>num</M></tag> |
dad92c30 OZ |
4570 | Specifies interval in seconds between retransmissions of unacknowledged |
4571 | updates. Default value is 5. | |
8fd12e6b | 4572 | |
ee95f281 OZ |
4573 | <tag><label id="ospf-transmit-delay">transmit delay <M>num</M></tag> |
4574 | Specifies estimated transmission delay of link state updates send over | |
4575 | the interface. The value is added to LSA age of LSAs propagated through | |
4576 | it. Default value is 1. | |
4577 | ||
b9864aa8 | 4578 | <tag><label id="ospf-priority">priority <M>num</M></tag> |
0a505706 OZ |
4579 | On every multiple access network (e.g., the Ethernet) Designated Router |
4580 | and Backup Designated router are elected. These routers have some special | |
dad92c30 OZ |
4581 | functions in the flooding process. Higher priority increases preferences |
4582 | in this election. Routers with priority 0 are not eligible. Default | |
4583 | value is 1. | |
8fd12e6b | 4584 | |
b9864aa8 | 4585 | <tag><label id="ospf-wait">wait <M>num</M></tag> |
dad92c30 | 4586 | After start, router waits for the specified number of seconds between |
178a197a OZ |
4587 | starting election and building adjacency. Default value is 4*<m/hello/. |
4588 | ||
b9864aa8 | 4589 | <tag><label id="ospf-dead-count">dead count <M>num</M></tag> |
dad92c30 OZ |
4590 | When the router does not receive any messages from a neighbor in |
4591 | <m/dead count/*<m/hello/ seconds, it will consider the neighbor down. | |
8fd12e6b | 4592 | |
b9864aa8 | 4593 | <tag><label id="ospf-dead">dead <M>num</M></tag> |
dad92c30 OZ |
4594 | When the router does not receive any messages from a neighbor in |
4595 | <m/dead/ seconds, it will consider the neighbor down. If both directives | |
fff7498d | 4596 | <cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precedence. |
48e5f32d | 4597 | |
b9864aa8 | 4598 | <tag><label id="ospf-rx-buffer">rx buffer <M>num</M></tag> |
48e5f32d OZ |
4599 | This option allows to specify the size of buffers used for packet |
4600 | processing. The buffer size should be bigger than maximal size of any | |
4601 | packets. By default, buffers are dynamically resized as needed, but a | |
4602 | fixed value could be specified. Value <cf/large/ means maximal allowed | |
4603 | packet size - 65535. | |
4604 | ||
b9864aa8 | 4605 | <tag><label id="ospf-tx-length">tx length <M>num</M></tag> |
48e5f32d OZ |
4606 | Transmitted OSPF messages that contain large amount of information are |
4607 | segmented to separate OSPF packets to avoid IP fragmentation. This | |
4608 | option specifies the soft ceiling for the length of generated OSPF | |
4609 | packets. Default value is the MTU of the network interface. Note that | |
4610 | larger OSPF packets may still be generated if underlying OSPF messages | |
4611 | cannot be splitted (e.g. when one large LSA is propagated). | |
94c42054 | 4612 | |
b9864aa8 | 4613 | <tag><label id="ospf-type-bcast">type broadcast|bcast</tag> |
dad92c30 OZ |
4614 | BIRD detects a type of a connected network automatically, but sometimes |
4615 | it's convenient to force use of a different type manually. On broadcast | |
4616 | networks (like ethernet), flooding and Hello messages are sent using | |
4617 | multicasts (a single packet for all the neighbors). A designated router | |
4618 | is elected and it is responsible for synchronizing the link-state | |
4619 | databases and originating network LSAs. This network type cannot be used | |
4620 | on physically NBMA networks and on unnumbered networks (networks without | |
4621 | proper IP prefix). | |
919f5411 | 4622 | |
b9864aa8 | 4623 | <tag><label id="ospf-type-ptp">type pointopoint|ptp</tag> |
dad92c30 OZ |
4624 | Point-to-point networks connect just 2 routers together. No election is |
4625 | performed and no network LSA is originated, which makes it simpler and | |
4626 | faster to establish. This network type is useful not only for physically | |
4627 | PtP ifaces (like PPP or tunnels), but also for broadcast networks used | |
4628 | as PtP links. This network type cannot be used on physically NBMA | |
4629 | networks. | |
919f5411 | 4630 | |
b9864aa8 | 4631 | <tag><label id="ospf-type-nbma">type nonbroadcast|nbma</tag> |
dad92c30 OZ |
4632 | On NBMA networks, the packets are sent to each neighbor separately |
4633 | because of lack of multicast capabilities. Like on broadcast networks, | |
4634 | a designated router is elected, which plays a central role in propagation | |
4635 | of LSAs. This network type cannot be used on unnumbered networks. | |
919f5411 | 4636 | |
b9864aa8 | 4637 | <tag><label id="ospf-type-ptmp">type pointomultipoint|ptmp</tag> |
dad92c30 OZ |
4638 | This is another network type designed to handle NBMA networks. In this |
4639 | case the NBMA network is treated as a collection of PtP links. This is | |
4640 | useful if not every pair of routers on the NBMA network has direct | |
4641 | communication, or if the NBMA network is used as an (possibly | |
4642 | unnumbered) PtP link. | |
8fd12e6b | 4643 | |
b9864aa8 | 4644 | <tag><label id="ospf-link-lsa-suppression">link lsa suppression <m/switch/</tag> |
70945cb6 OZ |
4645 | In OSPFv3, link LSAs are generated for each link, announcing link-local |
4646 | IPv6 address of the router to its local neighbors. These are useless on | |
4647 | PtP or PtMP networks and this option allows to suppress the link LSA | |
4648 | origination for such interfaces. The option is ignored on other than PtP | |
4649 | or PtMP interfaces. Default value is no. | |
4650 | ||
b9864aa8 | 4651 | <tag><label id="ospf-strict-nonbroadcast">strict nonbroadcast <m/switch/</tag> |
dad92c30 | 4652 | If set, don't send hello to any undefined neighbor. This switch is |
70945cb6 | 4653 | ignored on other than NBMA or PtMP interfaces. Default value is no. |
8fd12e6b | 4654 | |
b9864aa8 | 4655 | <tag><label id="ospf-real-broadcast">real broadcast <m/switch/</tag> |
dad92c30 OZ |
4656 | In <cf/type broadcast/ or <cf/type ptp/ network configuration, OSPF |
4657 | packets are sent as IP multicast packets. This option changes the | |
4658 | behavior to using old-fashioned IP broadcast packets. This may be useful | |
4659 | as a workaround if IP multicast for some reason does not work or does | |
4660 | not work reliably. This is a non-standard option and probably is not | |
4661 | interoperable with other OSPF implementations. Default value is no. | |
95127cbb | 4662 | |
b9864aa8 | 4663 | <tag><label id="ospf-ptp-netmask">ptp netmask <m/switch/</tag> |
dad92c30 OZ |
4664 | In <cf/type ptp/ network configurations, OSPFv2 implementations should |
4665 | ignore received netmask field in hello packets and should send hello | |
4666 | packets with zero netmask field on unnumbered PtP links. But some OSPFv2 | |
c1632ad0 OZ |
4667 | implementations perform netmask checking even for PtP links. |
4668 | ||
4669 | This option specifies whether real netmask will be used in hello packets | |
4670 | on <cf/type ptp/ interfaces. You should ignore this option unless you | |
4671 | meet some compatibility problems related to this issue. Default value is | |
4672 | no for unnumbered PtP links, yes otherwise. | |
4673 | ||
4674 | <tag><label id="ospf-ptp-address">ptp address <m/switch/</tag> | |
4675 | In <cf/type ptp/ network configurations, OSPFv2 implementations should | |
4676 | use IP address for regular PtP links and interface id for unnumbered PtP | |
4677 | links in data field of link description records in router LSA. This data | |
4678 | field has only local meaning for PtP links, but some broken OSPFv2 | |
4679 | implementations assume there is an IP address and use it as a next hop | |
4680 | in SPF calculations. Note that interface id for unnumbered PtP links is | |
4681 | necessary when graceful restart is enabled to distinguish PtP links with | |
4682 | the same local IP address. | |
4683 | ||
4684 | This option specifies whether an IP address will be used in data field | |
4685 | for <cf/type ptp/ interfaces, it is ignored for other interfaces. You | |
4686 | should ignore this option unless you meet some compatibility problems | |
4687 | related to this issue. Default value is no for unnumbered PtP links when | |
4688 | graceful restart is enabled, yes otherwise. | |
8df02847 | 4689 | |
b9864aa8 | 4690 | <tag><label id="ospf-check-link">check link <M>switch</M></tag> |
dad92c30 OZ |
4691 | If set, a hardware link state (reported by OS) is taken into consideration. |
4692 | When a link disappears (e.g. an ethernet cable is unplugged), neighbors | |
4693 | are immediately considered unreachable and only the address of the iface | |
4694 | (instead of whole network prefix) is propagated. It is possible that | |
4695 | some hardware drivers or platforms do not implement this feature. | |
cf3e3845 | 4696 | Default value is yes. |
e91f6960 | 4697 | |
b9864aa8 | 4698 | <tag><label id="ospf-bfd">bfd <M>switch</M></tag> |
1ec52253 OZ |
4699 | OSPF could use BFD protocol as an advisory mechanism for neighbor |
4700 | liveness and failure detection. If enabled, BIRD setups a BFD session | |
4701 | for each OSPF neighbor and tracks its liveness by it. This has an | |
4702 | advantage of an order of magnitude lower detection times in case of | |
4703 | failure. Note that BFD protocol also has to be configured, see | |
b9864aa8 | 4704 | <ref id="bfd" name="BFD"> section for details. Default value is no. |
1ec52253 | 4705 | |
b9864aa8 | 4706 | <tag><label id="ospf-ttl-security">ttl security [<m/switch/ | tx only]</tag> |
dad92c30 OZ |
4707 | TTL security is a feature that protects routing protocols from remote |
4708 | spoofed packets by using TTL 255 instead of TTL 1 for protocol packets | |
4709 | destined to neighbors. Because TTL is decremented when packets are | |
4710 | forwarded, it is non-trivial to spoof packets with TTL 255 from remote | |
4711 | locations. Note that this option would interfere with OSPF virtual | |
4712 | links. | |
4713 | ||
4714 | If this option is enabled, the router will send OSPF packets with TTL | |
4715 | 255 and drop received packets with TTL less than 255. If this option si | |
4716 | set to <cf/tx only/, TTL 255 is used for sent packets, but is not | |
4717 | checked for received packets. Default value is no. | |
6ac4f87a | 4718 | |
b9864aa8 | 4719 | <tag><label id="ospf-tx-class">tx class|dscp|priority <m/num/</tag> |
dad92c30 | 4720 | These options specify the ToS/DiffServ/Traffic class/Priority of the |
b9864aa8 | 4721 | outgoing OSPF packets. See <ref id="proto-tx-class" name="tx class"> common |
dad92c30 | 4722 | option for detailed description. |
ef4a50be | 4723 | |
b9864aa8 | 4724 | <tag><label id="ospf-ecmp-weight">ecmp weight <M>num</M></tag> |
dad92c30 OZ |
4725 | When ECMP (multipath) routes are allowed, this value specifies a |
4726 | relative weight used for nexthops going through the iface. Allowed | |
4727 | values are 1-256. Default value is 1. | |
391931d4 | 4728 | |
b9864aa8 | 4729 | <tag><label id="ospf-auth-none">authentication none</tag> |
dad92c30 | 4730 | No passwords are sent in OSPF packets. This is the default value. |
8fd12e6b | 4731 | |
b9864aa8 | 4732 | <tag><label id="ospf-auth-simple">authentication simple</tag> |
dad92c30 OZ |
4733 | Every packet carries 8 bytes of password. Received packets lacking this |
4734 | password are ignored. This authentication mechanism is very weak. | |
64385aee | 4735 | This option is not available in OSPFv3. |
8fd12e6b | 4736 | |
b9864aa8 | 4737 | <tag><label id="ospf-auth-cryptographic">authentication cryptographic</tag> |
64385aee PT |
4738 | An authentication code is appended to every packet. The specific |
4739 | cryptographic algorithm is selected by option <cf/algorithm/ for each | |
4740 | key. The default cryptographic algorithm for OSPFv2 keys is Keyed-MD5 | |
4741 | and for OSPFv3 keys is HMAC-SHA-256. Passwords are not sent open via | |
4742 | network, so this mechanism is quite secure. Packets can still be read by | |
4743 | an attacker. | |
ea357b8b | 4744 | |
b9864aa8 | 4745 | <tag><label id="ospf-pass">password "<M>text</M>"</tag> |
64385aee | 4746 | Specifies a password used for authentication. See |
b9864aa8 | 4747 | <ref id="proto-pass" name="password"> common option for detailed |
dad92c30 | 4748 | description. |
8fd12e6b | 4749 | |
b9864aa8 | 4750 | <tag><label id="ospf-neighbors">neighbors { <m/set/ } </tag> |
dad92c30 OZ |
4751 | A set of neighbors to which Hello messages on NBMA or PtMP networks are |
4752 | to be sent. For NBMA networks, some of them could be marked as eligible. | |
4753 | In OSPFv3, link-local addresses should be used, using global ones is | |
4754 | possible, but it is nonstandard and might be problematic. And definitely, | |
4755 | link-local and global addresses should not be mixed. | |
8fd12e6b OF |
4756 | </descrip> |
4757 | ||
4758 | <sect1>Attributes | |
b9864aa8 | 4759 | <label id="ospf-attr"> |
8fd12e6b | 4760 | |
c27b2449 | 4761 | <p>OSPF defines four route attributes. Each internal route has a <cf/metric/. |
8fd12e6b | 4762 | |
dad92c30 OZ |
4763 | <p>Metric is ranging from 1 to infinity (65535). External routes use |
4764 | <cf/metric type 1/ or <cf/metric type 2/. A <cf/metric of type 1/ is comparable | |
4765 | with internal <cf/metric/, a <cf/metric of type 2/ is always longer than any | |
4766 | <cf/metric of type 1/ or any <cf/internal metric/. <cf/Internal metric/ or | |
4767 | <cf/metric of type 1/ is stored in attribute <cf/ospf_metric1/, <cf/metric type | |
feae132e OZ |
4768 | 2/ is stored in attribute <cf/ospf_metric2/. |
4769 | ||
4770 | When both metrics are specified then <cf/metric of type 2/ is used. This is | |
4771 | relevant e.g. when a type 2 external route is propagated from one OSPF domain to | |
4772 | another and <cf/ospf_metric1/ is an internal distance to the original ASBR, | |
4773 | while <cf/ospf_metric2/ stores the type 2 metric. Note that in such cases if | |
4774 | <cf/ospf_metric1/ is non-zero then <cf/ospf_metric2/ is increased by one to | |
4775 | ensure monotonicity of metric, as internal distance is reset to zero when an | |
4776 | external route is announced. | |
dad92c30 OZ |
4777 | |
4778 | <p>Each external route can also carry attribute <cf/ospf_tag/ which is a 32-bit | |
4779 | integer which is used when exporting routes to other protocols; otherwise, it | |
4780 | doesn't affect routing inside the OSPF domain at all. The fourth attribute | |
4781 | <cf/ospf_router_id/ is a router ID of the router advertising that route / | |
4782 | network. This attribute is read-only. Default is <cf/ospf_metric2 = 10000/ and | |
4783 | <cf/ospf_tag = 0/. | |
8fd12e6b | 4784 | |
dad92c30 | 4785 | <sect1>Example |
b9864aa8 | 4786 | <label id="ospf-exam"> |
8fd12e6b | 4787 | |
9637c7c0 | 4788 | <p><code> |
8fd12e6b | 4789 | protocol ospf MyOSPF { |
3e52d112 JMM |
4790 | ipv4 { |
4791 | export filter { | |
4792 | if source = RTS_BGP then { | |
4793 | ospf_metric1 = 100; | |
4794 | accept; | |
4795 | } | |
4796 | reject; | |
4797 | }; | |
f434d191 | 4798 | }; |
8fd12e6b | 4799 | area 0.0.0.0 { |
8fd12e6b OF |
4800 | interface "eth*" { |
4801 | cost 11; | |
4802 | hello 15; | |
4803 | priority 100; | |
4804 | retransmit 7; | |
4805 | authentication simple; | |
4806 | password "aaa"; | |
4807 | }; | |
4808 | interface "ppp*" { | |
4809 | cost 100; | |
3b16080c | 4810 | authentication cryptographic; |
f434d191 OZ |
4811 | password "abc" { |
4812 | id 1; | |
13c10ee0 OZ |
4813 | generate to "2023-04-22 11:00:06"; |
4814 | accept from "2021-01-17 12:01:05"; | |
64385aee | 4815 | algorithm hmac sha384; |
f434d191 OZ |
4816 | }; |
4817 | password "def" { | |
4818 | id 2; | |
13c10ee0 OZ |
4819 | generate to "2025-07-22"; |
4820 | accept from "2021-02-22"; | |
64385aee | 4821 | algorithm hmac sha512; |
3b16080c | 4822 | }; |
8fd12e6b | 4823 | }; |
e3bc10fd OF |
4824 | interface "arc0" { |
4825 | cost 10; | |
4826 | stub yes; | |
4827 | }; | |
3b16080c | 4828 | interface "arc1"; |
8fd12e6b OF |
4829 | }; |
4830 | area 120 { | |
4831 | stub yes; | |
98ac6176 OF |
4832 | networks { |
4833 | 172.16.1.0/24; | |
4834 | 172.16.2.0/24 hidden; | |
6c11dbcf | 4835 | }; |
8fd12e6b OF |
4836 | interface "-arc0" , "arc*" { |
4837 | type nonbroadcast; | |
4838 | authentication none; | |
e3bc10fd | 4839 | strict nonbroadcast yes; |
a190e720 OF |
4840 | wait 120; |
4841 | poll 40; | |
4842 | dead count 8; | |
8fd12e6b | 4843 | neighbors { |
a190e720 | 4844 | 192.168.120.1 eligible; |
8fd12e6b OF |
4845 | 192.168.120.2; |
4846 | 192.168.120.10; | |
4847 | }; | |
4848 | }; | |
4849 | }; | |
4850 | } | |
4851 | </code> | |
4852 | ||
82b74253 MM |
4853 | <sect>Perf |
4854 | <label id="perf"> | |
4855 | ||
4856 | <sect1>Introduction | |
4857 | <label id="perf-intro"> | |
4858 | ||
4859 | <p>The Perf protocol is a generator of fake routes together with a time measurement | |
4860 | framework. Its purpose is to check BIRD performance and to benchmark filters. | |
4861 | ||
4862 | <p>Import mode of this protocol runs in several steps. In each step, it generates 2^x routes, | |
4863 | imports them into the appropriate table and withdraws them. The exponent x is configurable. | |
4864 | It runs the benchmark several times for the same x, then it increases x by one | |
4865 | until it gets too high, then it stops. | |
4866 | ||
4867 | <p>Export mode of this protocol repeats route refresh from table and measures how long it takes. | |
4868 | ||
4869 | <p>Output data is logged on info level. There is a Perl script <cf>proto/perf/parse.pl</cf> | |
4870 | which may be handy to parse the data and draw some plots. | |
4871 | ||
4872 | <p>Implementation of this protocol is experimental. Use with caution and do not keep | |
4873 | any instance of Perf in production configs for long time. The config interface is also unstable | |
4874 | and may change in future versions without warning. | |
4875 | ||
4876 | <sect1>Configuration | |
4877 | <label id="perf-config"> | |
4878 | ||
4879 | <p><descrip> | |
4880 | <tag><label id="perf-mode">mode import|export</tag> | |
4881 | Set perf mode. Default: import | |
4882 | ||
4883 | <tag><label id="perf-repeat">repeat <m/number/</tag> | |
4884 | Run this amount of iterations of the benchmark for every amount step. Default: 4 | |
4885 | ||
4886 | <tag><label id="perf-from">exp from <m/number/</tag> | |
4887 | Begin benchmarking on this exponent for number of generated routes in one step. | |
4888 | Default: 10 | |
4889 | ||
4890 | <tag><label id="perf-to">exp to <m/number/</tag> | |
4891 | Stop benchmarking on this exponent. Default: 20 | |
4892 | ||
4893 | <tag><label id="perf-threshold-min">threshold min <m/time/</tag> | |
4894 | If a run for the given exponent took less than this time for route import, | |
4895 | increase the exponent immediately. Default: 1 ms | |
4896 | ||
4897 | <tag><label id="perf-threshold-max">threshold max <m/time/</tag> | |
4898 | If every run for the given exponent took at least this time for route import, | |
4899 | stop benchmarking. Default: 500 ms | |
4900 | </descrip> | |
dad92c30 | 4901 | |
371adba6 | 4902 | <sect>Pipe |
b9864aa8 | 4903 | <label id="pipe"> |
1b55b1a3 | 4904 | |
371adba6 | 4905 | <sect1>Introduction |
b9864aa8 | 4906 | <label id="pipe-intro"> |
a2a3ced8 | 4907 | |
dad92c30 OZ |
4908 | <p>The Pipe protocol serves as a link between two routing tables, allowing |
4909 | routes to be passed from a table declared as primary (i.e., the one the pipe is | |
4910 | connected to using the <cf/table/ configuration keyword) to the secondary one | |
4911 | (declared using <cf/peer table/) and vice versa, depending on what's allowed by | |
4912 | the filters. Export filters control export of routes from the primary table to | |
3e52d112 JMM |
4913 | the secondary one, import filters control the opposite direction. Both tables |
4914 | must be of the same nettype. | |
dad92c30 | 4915 | |
765f400f OZ |
4916 | <p>The Pipe protocol retransmits all routes from one table to the other table, |
4917 | retaining their original source and attributes. If import and export filters | |
4918 | are set to accept, then both tables would have the same content. | |
f98e2915 | 4919 | |
dad92c30 OZ |
4920 | <p>The primary use of multiple routing tables and the Pipe protocol is for |
4921 | policy routing, where handling of a single packet doesn't depend only on its | |
4922 | destination address, but also on its source address, source interface, protocol | |
4923 | type and other similar parameters. In many systems (Linux being a good example), | |
4924 | the kernel allows to enforce routing policies by defining routing rules which | |
4925 | choose one of several routing tables to be used for a packet according to its | |
4926 | parameters. Setting of these rules is outside the scope of BIRD's work (on | |
4927 | Linux, you can use the <tt/ip/ command), but you can create several routing | |
4928 | tables in BIRD, connect them to the kernel ones, use filters to control which | |
4929 | routes appear in which tables and also you can employ the Pipe protocol for | |
4930 | exporting a selected subset of one table to another one. | |
a2a3ced8 | 4931 | |
371adba6 | 4932 | <sect1>Configuration |
b9864aa8 | 4933 | <label id="pipe-config"> |
a2a3ced8 | 4934 | |
cf3e3845 OZ |
4935 | <p>Essentially, the Pipe protocol is just a channel connected to a table on both |
4936 | sides. Therefore, the configuration block for <cf/protocol pipe/ shall directly | |
4937 | include standard channel config options; see the example below. | |
3e52d112 | 4938 | |
a2a3ced8 | 4939 | <p><descrip> |
b9864aa8 | 4940 | <tag><label id="pipe-peer-table">peer table <m/table/</tag> |
dad92c30 OZ |
4941 | Defines secondary routing table to connect to. The primary one is |
4942 | selected by the <cf/table/ keyword. | |
a2a3ced8 MM |
4943 | </descrip> |
4944 | ||
371adba6 | 4945 | <sect1>Attributes |
b9864aa8 | 4946 | <label id="pipe-attr"> |
a2a3ced8 MM |
4947 | |
4948 | <p>The Pipe protocol doesn't define any route attributes. | |
4949 | ||
371adba6 | 4950 | <sect1>Example |
b9864aa8 | 4951 | <label id="pipe-exam"> |
a2a3ced8 | 4952 | |
dad92c30 OZ |
4953 | <p>Let's consider a router which serves as a boundary router of two different |
4954 | autonomous systems, each of them connected to a subset of interfaces of the | |
4955 | router, having its own exterior connectivity and wishing to use the other AS as | |
4956 | a backup connectivity in case of outage of its own exterior line. | |
4957 | ||
4958 | <p>Probably the simplest solution to this situation is to use two routing tables | |
4959 | (we'll call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that | |
4960 | packets having arrived from interfaces belonging to the first AS will be routed | |
4961 | according to <cf/as1/ and similarly for the second AS. Thus we have split our | |
4962 | router to two logical routers, each one acting on its own routing table, having | |
4963 | its own routing protocols on its own interfaces. In order to use the other AS's | |
4964 | routes for backup purposes, we can pass the routes between the tables through a | |
4965 | Pipe protocol while decreasing their preferences and correcting their BGP paths | |
4966 | to reflect the AS boundary crossing. | |
a2a3ced8 MM |
4967 | |
4968 | <code> | |
cf3e3845 OZ |
4969 | ipv4 table as1; # Define the tables |
4970 | ipv4 table as2; | |
a2a3ced8 MM |
4971 | |
4972 | protocol kernel kern1 { # Synchronize them with the kernel | |
cf3e3845 | 4973 | ipv4 { table as1; export all; }; |
a2a3ced8 MM |
4974 | kernel table 1; |
4975 | } | |
4976 | ||
4977 | protocol kernel kern2 { | |
cf3e3845 | 4978 | ipv4 { table as2; export all; }; |
a2a3ced8 MM |
4979 | kernel table 2; |
4980 | } | |
4981 | ||
4982 | protocol bgp bgp1 { # The outside connections | |
3831b619 | 4983 | ipv4 { table as1; import all; export all; }; |
a2a3ced8 MM |
4984 | local as 1; |
4985 | neighbor 192.168.0.1 as 1001; | |
a2a3ced8 MM |
4986 | } |
4987 | ||
4988 | protocol bgp bgp2 { | |
3831b619 | 4989 | ipv4 { table as2; import all; export all; }; |
a2a3ced8 MM |
4990 | local as 2; |
4991 | neighbor 10.0.0.1 as 1002; | |
a2a3ced8 MM |
4992 | } |
4993 | ||
4994 | protocol pipe { # The Pipe | |
4995 | table as1; | |
4996 | peer table as2; | |
4997 | export filter { | |
4998 | if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks | |
4999 | if preference>10 then preference = preference-10; | |
5000 | if source=RTS_BGP then bgp_path.prepend(1); | |
5001 | accept; | |
5002 | } | |
5003 | reject; | |
5004 | }; | |
5005 | import filter { | |
5006 | if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks | |
5007 | if preference>10 then preference = preference-10; | |
5008 | if source=RTS_BGP then bgp_path.prepend(2); | |
5009 | accept; | |
5010 | } | |
5011 | reject; | |
5012 | }; | |
5013 | } | |
5014 | </code> | |
5015 | ||
dad92c30 | 5016 | |
6bcef225 | 5017 | <sect>RAdv |
b9864aa8 | 5018 | <label id="radv"> |
6bcef225 OZ |
5019 | |
5020 | <sect1>Introduction | |
b9864aa8 | 5021 | <label id="radv-intro"> |
6bcef225 | 5022 | |
dad92c30 OZ |
5023 | <p>The RAdv protocol is an implementation of Router Advertisements, which are |
5024 | used in the IPv6 stateless autoconfiguration. IPv6 routers send (in irregular | |
5025 | time intervals or as an answer to a request) advertisement packets to connected | |
5026 | networks. These packets contain basic information about a local network (e.g. a | |
5027 | list of network prefixes), which allows network hosts to autoconfigure network | |
5028 | addresses and choose a default route. BIRD implements router behavior as defined | |
18352188 MV |
5029 | in <rfc id="4861">, router preferences and specific routes (<rfc id="4191">), |
5030 | and DNS extensions (<rfc id="6106">). | |
6bcef225 | 5031 | |
cf3e3845 | 5032 | <p>The RAdv protocols supports just IPv6 channel. |
3e52d112 | 5033 | |
6bcef225 | 5034 | <sect1>Configuration |
b9864aa8 | 5035 | <label id="radv-config"> |
6bcef225 | 5036 | |
dad92c30 OZ |
5037 | <p>There are several classes of definitions in RAdv configuration -- interface |
5038 | definitions, prefix definitions and DNS definitions: | |
6bcef225 OZ |
5039 | |
5040 | <descrip> | |
9df52a98 | 5041 | <tag><label id="radv-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag> |
6bcef225 OZ |
5042 | Interface definitions specify a set of interfaces on which the |
5043 | protocol is activated and contain interface specific options. | |
b9864aa8 | 5044 | See <ref id="proto-iface" name="interface"> common options for |
6bcef225 OZ |
5045 | detailed description. |
5046 | ||
b9864aa8 | 5047 | <tag><label id="radv-prefix">prefix <m/prefix/ { <m/options/ }</tag> |
dad92c30 OZ |
5048 | Prefix definitions allow to modify a list of advertised prefixes. By |
5049 | default, the advertised prefixes are the same as the network prefixes | |
5050 | assigned to the interface. For each network prefix, the matching prefix | |
5051 | definition is found and its options are used. If no matching prefix | |
5052 | definition is found, the prefix is used with default options. | |
5053 | ||
5054 | Prefix definitions can be either global or interface-specific. The | |
5055 | second ones are part of interface options. The prefix definition | |
5056 | matching is done in the first-match style, when interface-specific | |
5057 | definitions are processed before global definitions. As expected, the | |
5058 | prefix definition is matching if the network prefix is a subnet of the | |
5059 | prefix in prefix definition. | |
0e224d59 | 5060 | |
b9864aa8 | 5061 | <tag><label id="radv-rdnss">rdnss { <m/options/ }</tag> |
dad92c30 OZ |
5062 | RDNSS definitions allow to specify a list of advertised recursive DNS |
5063 | servers together with their options. As options are seldom necessary, | |
5064 | there is also a short variant <cf>rdnss <m/address/</cf> that just | |
5065 | specifies one DNS server. Multiple definitions are cumulative. RDNSS | |
5066 | definitions may also be interface-specific when used inside interface | |
5067 | options. By default, interface uses both global and interface-specific | |
0e224d59 | 5068 | options, but that can be changed by <cf/rdnss local/ option. |
18352188 | 5069 | |
b9864aa8 | 5070 | <tag><label id="radv-dnssl">dnssl { <m/options/ }</tag> |
dad92c30 OZ |
5071 | DNSSL definitions allow to specify a list of advertised DNS search |
5072 | domains together with their options. Like <cf/rdnss/ above, multiple | |
5073 | definitions are cumulative, they can be used also as interface-specific | |
5074 | options and there is a short variant <cf>dnssl <m/domain/</cf> that just | |
5075 | specifies one DNS search domain. | |
36da2857 | 5076 | |
9d8e4b01 | 5077 | <tag><label id="radv-custom-option">custom option type <m/number/ value <m/bytestring/</tag> |
cbb43d6f AZ |
5078 | Custom option definitions allow to define an arbitrary option to |
5079 | advertise. You need to specify the option type number and the binary | |
5080 | payload of the option. The length field is calculated automatically. | |
5081 | Like <cf/rdnss/ above, multiple definitions are cumulative, they can | |
5082 | be used also as interface-specific options. | |
5083 | ||
5084 | The following example advertises PREF64 option (<rfc id="8781">) with | |
5085 | prefix <cf>2001:db8:a:b::/96</cf> and the lifetime of <cf/1 hour/: | |
5086 | ||
5087 | <label id="radv-custom-option-exam"> | |
5088 | <p><code> | |
c5c3a22b | 5089 | custom option type 38 value hex:0e:10:20:01:0d:b8:00:0a:00:0b:00:00:00:00; |
cbb43d6f AZ |
5090 | </code> |
5091 | ||
b9864aa8 | 5092 | <tag><label id="radv-trigger">trigger <m/prefix/</tag> |
dad92c30 OZ |
5093 | RAdv protocol could be configured to change its behavior based on |
5094 | availability of routes. When this option is used, the protocol waits in | |
5095 | suppressed state until a <it/trigger route/ (for the specified network) | |
df092aa1 | 5096 | is exported to the protocol, the protocol also returns to suppressed |
dad92c30 OZ |
5097 | state if the <it/trigger route/ disappears. Note that route export |
5098 | depends on specified export filter, as usual. This option could be used, | |
5099 | e.g., for handling failover in multihoming scenarios. | |
5100 | ||
5101 | During suppressed state, router advertisements are generated, but with | |
5102 | some fields zeroed. Exact behavior depends on which fields are zeroed, | |
5103 | this can be configured by <cf/sensitive/ option for appropriate | |
5104 | fields. By default, just <cf/default lifetime/ (also called <cf/router | |
5105 | lifetime/) is zeroed, which means hosts cannot use the router as a | |
5106 | default router. <cf/preferred lifetime/ and <cf/valid lifetime/ could | |
5107 | also be configured as <cf/sensitive/ for a prefix, which would cause | |
5108 | autoconfigured IPs to be deprecated or even removed. | |
18352188 MV |
5109 | |
5110 | <tag><label id="radv-propagate-routes">propagate routes <m/switch/</tag> | |
5111 | This option controls propagation of more specific routes, as defined in | |
5112 | <rfc id="4191">. If enabled, all routes exported to the RAdv protocol, | |
5113 | with the exception of the trigger prefix, are added to advertisments as | |
5114 | additional options. The lifetime and preference of advertised routes can | |
5115 | be set individually by <cf/ra_lifetime/ and <cf/ra_preference/ route | |
5116 | attributes, or per interface by <cf/route lifetime/ and | |
5117 | <cf/route preference/ options. Default: disabled. | |
5118 | ||
5119 | Note that the RFC discourages from sending more than 17 routes and | |
5120 | recommends the routes to be configured manually. | |
6bcef225 OZ |
5121 | </descrip> |
5122 | ||
5123 | <p>Interface specific options: | |
5124 | ||
5125 | <descrip> | |
b9864aa8 | 5126 | <tag><label id="radv-iface-max-ra-interval">max ra interval <m/expr/</tag> |
dad92c30 OZ |
5127 | Unsolicited router advertisements are sent in irregular time intervals. |
5128 | This option specifies the maximum length of these intervals, in seconds. | |
5129 | Valid values are 4-1800. Default: 600 | |
6bcef225 | 5130 | |
b9864aa8 | 5131 | <tag><label id="radv-iface-min-ra-interval">min ra interval <m/expr/</tag> |
dad92c30 OZ |
5132 | This option specifies the minimum length of that intervals, in seconds. |
5133 | Must be at least 3 and at most 3/4 * <cf/max ra interval/. Default: | |
5134 | about 1/3 * <cf/max ra interval/. | |
6bcef225 | 5135 | |
b9864aa8 | 5136 | <tag><label id="radv-iface-min-delay">min delay <m/expr/</tag> |
dad92c30 OZ |
5137 | The minimum delay between two consecutive router advertisements, in |
5138 | seconds. Default: 3 | |
6bcef225 | 5139 | |
70a4320b OZ |
5140 | <tag><label id="radv-solicited-ra-unicast">solicited ra unicast <m/switch/</tag> |
5141 | Solicited router advertisements are usually sent to all-nodes multicast | |
5142 | group like unsolicited ones, but the router can be configured to send | |
5143 | them as unicast directly to soliciting nodes instead. This is especially | |
5144 | useful on wireless networks (see <rfc id="7772">). Default: no | |
5145 | ||
b9864aa8 | 5146 | <tag><label id="radv-iface-managed">managed <m/switch/</tag> |
dad92c30 OZ |
5147 | This option specifies whether hosts should use DHCPv6 for IP address |
5148 | configuration. Default: no | |
6bcef225 | 5149 | |
b9864aa8 | 5150 | <tag><label id="radv-iface-other-config">other config <m/switch/</tag> |
dad92c30 OZ |
5151 | This option specifies whether hosts should use DHCPv6 to receive other |
5152 | configuration information. Default: no | |
6bcef225 | 5153 | |
b9864aa8 | 5154 | <tag><label id="radv-iface-link-mtu">link mtu <m/expr/</tag> |
dad92c30 OZ |
5155 | This option specifies which value of MTU should be used by hosts. 0 |
5156 | means unspecified. Default: 0 | |
6bcef225 | 5157 | |
b9864aa8 | 5158 | <tag><label id="radv-iface-reachable-time">reachable time <m/expr/</tag> |
dad92c30 OZ |
5159 | This option specifies the time (in milliseconds) how long hosts should |
5160 | assume a neighbor is reachable (from the last confirmation). Maximum is | |
5161 | 3600000, 0 means unspecified. Default 0. | |
6bcef225 | 5162 | |
b9864aa8 | 5163 | <tag><label id="radv-iface-retrans-timer">retrans timer <m/expr/</tag> |
dad92c30 OZ |
5164 | This option specifies the time (in milliseconds) how long hosts should |
5165 | wait before retransmitting Neighbor Solicitation messages. 0 means | |
5166 | unspecified. Default 0. | |
6bcef225 | 5167 | |
b9864aa8 | 5168 | <tag><label id="radv-iface-current-hop-limit">current hop limit <m/expr/</tag> |
dad92c30 OZ |
5169 | This option specifies which value of Hop Limit should be used by |
5170 | hosts. Valid values are 0-255, 0 means unspecified. Default: 64 | |
6bcef225 | 5171 | |
b9864aa8 | 5172 | <tag><label id="radv-iface-default-lifetime">default lifetime <m/expr/ [sensitive <m/switch/]</tag> |
18352188 | 5173 | This option specifies the time (in seconds) how long (since the receipt |
dad92c30 | 5174 | of RA) hosts may use the router as a default router. 0 means do not use |
b9864aa8 | 5175 | as a default router. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">. |
dad92c30 | 5176 | Default: 3 * <cf/max ra interval/, <cf/sensitive/ yes. |
0e224d59 | 5177 | |
18352188 | 5178 | <tag><label id="radv-iface-default-preference">default preference low|medium|high</tag> |
75148289 OZ |
5179 | This option specifies the Default Router Preference value to advertise |
5180 | to hosts. Default: medium. | |
5181 | ||
18352188 MV |
5182 | <tag><label id="radv-iface-route-lifetime">route lifetime <m/expr/ [sensitive <m/switch/]</tag> |
5183 | This option specifies the default value of advertised lifetime for | |
5184 | specific routes; i.e., the time (in seconds) for how long (since the | |
5185 | receipt of RA) hosts should consider these routes valid. A special value | |
5186 | 0xffffffff represents infinity. The lifetime can be overriden on a per | |
5187 | route basis by the <ref id="rta-ra-lifetime" name="ra_lifetime"> route | |
5188 | attribute. Default: 3 * <cf/max ra interval/, <cf/sensitive/ no. | |
5189 | ||
5190 | For the <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">. | |
5191 | If <cf/sensitive/ is enabled, even the routes with the <cf/ra_lifetime/ | |
5192 | attribute become sensitive to the trigger. | |
5193 | ||
5194 | <tag><label id="radv-iface-route-preference">route preference low|medium|high</tag> | |
5195 | This option specifies the default value of advertised route preference | |
5196 | for specific routes. The value can be overriden on a per route basis by | |
5197 | the <ref id="rta-ra-preference" name="ra_preference"> route attribute. | |
5198 | Default: medium. | |
5199 | ||
5200 | <tag><label id="radv-prefix-linger-time">prefix linger time <m/expr/</tag> | |
5201 | When a prefix or a route disappears, it is advertised for some time with | |
5202 | zero lifetime, to inform clients it is no longer valid. This option | |
5203 | specifies the time (in seconds) for how long prefixes are advertised | |
5204 | that way. Default: 3 * <cf/max ra interval/. | |
5205 | ||
5206 | <tag><label id="radv-route-linger-time">route linger time <m/expr/</tag> | |
5207 | When a prefix or a route disappears, it is advertised for some time with | |
5208 | zero lifetime, to inform clients it is no longer valid. This option | |
5209 | specifies the time (in seconds) for how long routes are advertised | |
5210 | that way. Default: 3 * <cf/max ra interval/. | |
5211 | ||
b9864aa8 | 5212 | <tag><label id="radv-iface-rdnss-local">rdnss local <m/switch/</tag> |
0e224d59 | 5213 | Use only local (interface-specific) RDNSS definitions for this |
dad92c30 OZ |
5214 | interface. Otherwise, both global and local definitions are used. Could |
5215 | also be used to disable RDNSS for given interface if no local definitons | |
5216 | are specified. Default: no. | |
0e224d59 | 5217 | |
b9864aa8 | 5218 | <tag><label id="radv-iface-dnssl-local">dnssl local <m/switch/</tag> |
dad92c30 OZ |
5219 | Use only local DNSSL definitions for this interface. See <cf/rdnss local/ |
5220 | option above. Default: no. | |
cbb43d6f AZ |
5221 | |
5222 | <tag><label id="radv-iface-custom-local">custom option local <m/switch/</tag> | |
5223 | Use only local custom option definitions for this interface. See <cf/rdnss local/ | |
5224 | option above. Default: no. | |
6bcef225 OZ |
5225 | </descrip> |
5226 | ||
b9864aa8 | 5227 | <p>Prefix specific options |
6bcef225 OZ |
5228 | |
5229 | <descrip> | |
b9864aa8 | 5230 | <tag><label id="radv-prefix-skip">skip <m/switch/</tag> |
d214ae4f | 5231 | This option allows to specify that given prefix should not be |
dad92c30 OZ |
5232 | advertised. This is useful for making exceptions from a default policy |
5233 | of advertising all prefixes. Note that for withdrawing an already | |
5234 | advertised prefix it is more useful to advertise it with zero valid | |
5235 | lifetime. Default: no | |
d214ae4f | 5236 | |
b9864aa8 | 5237 | <tag><label id="radv-prefix-onlink">onlink <m/switch/</tag> |
dad92c30 OZ |
5238 | This option specifies whether hosts may use the advertised prefix for |
5239 | onlink determination. Default: yes | |
6bcef225 | 5240 | |
b9864aa8 | 5241 | <tag><label id="radv-prefix-autonomous">autonomous <m/switch/</tag> |
dad92c30 OZ |
5242 | This option specifies whether hosts may use the advertised prefix for |
5243 | stateless autoconfiguration. Default: yes | |
6bcef225 | 5244 | |
b9864aa8 | 5245 | <tag><label id="radv-prefix-valid-lifetime">valid lifetime <m/expr/ [sensitive <m/switch/]</tag> |
dad92c30 OZ |
5246 | This option specifies the time (in seconds) how long (after the |
5247 | receipt of RA) the prefix information is valid, i.e., autoconfigured | |
5248 | IP addresses can be assigned and hosts with that IP addresses are | |
5249 | considered directly reachable. 0 means the prefix is no longer | |
b9864aa8 | 5250 | valid. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">. |
dad92c30 | 5251 | Default: 86400 (1 day), <cf/sensitive/ no. |
6bcef225 | 5252 | |
b9864aa8 | 5253 | <tag><label id="radv-prefix-preferred-lifetime">preferred lifetime <m/expr/ [sensitive <m/switch/]</tag> |
dad92c30 OZ |
5254 | This option specifies the time (in seconds) how long (after the |
5255 | receipt of RA) IP addresses generated from the prefix using stateless | |
5256 | autoconfiguration remain preferred. For <cf/sensitive/ option, | |
b9864aa8 | 5257 | see <ref id="radv-trigger" name="trigger">. Default: 14400 (4 hours), |
dad92c30 | 5258 | <cf/sensitive/ no. |
6bcef225 OZ |
5259 | </descrip> |
5260 | ||
0e224d59 OZ |
5261 | <p>RDNSS specific options: |
5262 | ||
5263 | <descrip> | |
b9864aa8 | 5264 | <tag><label id="radv-rdnss-ns">ns <m/address/</tag> |
dad92c30 OZ |
5265 | This option specifies one recursive DNS server. Can be used multiple |
5266 | times for multiple servers. It is mandatory to have at least one | |
5267 | <cf/ns/ option in <cf/rdnss/ definition. | |
0e224d59 | 5268 | |
b9864aa8 | 5269 | <tag><label id="radv-rdnss-lifetime">lifetime [mult] <m/expr/</tag> |
dad92c30 OZ |
5270 | This option specifies the time how long the RDNSS information may be |
5271 | used by clients after the receipt of RA. It is expressed either in | |
5272 | seconds or (when <cf/mult/ is used) in multiples of <cf/max ra | |
5273 | interval/. Note that RDNSS information is also invalidated when | |
5274 | <cf/default lifetime/ expires. 0 means these addresses are no longer | |
5275 | valid DNS servers. Default: 3 * <cf/max ra interval/. | |
0e224d59 OZ |
5276 | </descrip> |
5277 | ||
0e224d59 OZ |
5278 | <p>DNSSL specific options: |
5279 | ||
5280 | <descrip> | |
b9864aa8 | 5281 | <tag><label id="radv-dnssl-domain">domain <m/address/</tag> |
dad92c30 OZ |
5282 | This option specifies one DNS search domain. Can be used multiple times |
5283 | for multiple domains. It is mandatory to have at least one <cf/domain/ | |
5284 | option in <cf/dnssl/ definition. | |
0e224d59 | 5285 | |
b9864aa8 | 5286 | <tag><label id="radv-dnssl-lifetime">lifetime [mult] <m/expr/</tag> |
dad92c30 OZ |
5287 | This option specifies the time how long the DNSSL information may be |
5288 | used by clients after the receipt of RA. Details are the same as for | |
5289 | RDNSS <cf/lifetime/ option above. Default: 3 * <cf/max ra interval/. | |
0e224d59 OZ |
5290 | </descrip> |
5291 | ||
18352188 MV |
5292 | <sect1>Attributes |
5293 | <label id="radv-attr"> | |
5294 | ||
5295 | <p>RAdv defines two route attributes: | |
5296 | ||
5297 | <descrip> | |
157f6c2a | 5298 | <tag><label id="rta-ra-preference">enum ra_preference</tag> |
18352188 MV |
5299 | The preference of the route. The value can be <it/RA_PREF_LOW/, |
5300 | <it/RA_PREF_MEDIUM/ or <it/RA_PREF_HIGH/. If the attribute is not set, | |
5301 | the <ref id="radv-iface-route-preference" name="route preference"> | |
5302 | option is used. | |
5303 | ||
157f6c2a | 5304 | <tag><label id="rta-ra-lifetime">int ra_lifetime</tag> |
18352188 MV |
5305 | The advertised lifetime of the route, in seconds. The special value of |
5306 | 0xffffffff represents infinity. If the attribute is not set, the | |
5307 | <ref id="radv-iface-route-lifetime" name="route lifetime"> | |
5308 | option is used. | |
5309 | </descrip> | |
0e224d59 | 5310 | |
6bcef225 | 5311 | <sect1>Example |
b9864aa8 | 5312 | <label id="radv-exam"> |
6bcef225 OZ |
5313 | |
5314 | <p><code> | |
cf3e3845 | 5315 | ipv6 table radv_routes; # Manually configured routes go here |
18352188 MV |
5316 | |
5317 | protocol static { | |
cf3e3845 | 5318 | ipv6 { table radv_routes; }; |
18352188 MV |
5319 | |
5320 | route 2001:0DB8:4000::/48 unreachable; | |
5321 | route 2001:0DB8:4010::/48 unreachable; | |
5322 | ||
5323 | route 2001:0DB8:4020::/48 unreachable { | |
5324 | ra_preference = RA_PREF_HIGH; | |
5325 | ra_lifetime = 3600; | |
5326 | }; | |
5327 | } | |
5328 | ||
6bcef225 | 5329 | protocol radv { |
18352188 | 5330 | propagate routes yes; # Propagate the routes from the radv_routes table |
cf3e3845 | 5331 | ipv6 { table radv_routes; export all; }; |
18352188 | 5332 | |
6bcef225 OZ |
5333 | interface "eth2" { |
5334 | max ra interval 5; # Fast failover with more routers | |
5335 | managed yes; # Using DHCPv6 on eth2 | |
5336 | prefix ::/0 { | |
5337 | autonomous off; # So do not autoconfigure any IP | |
5338 | }; | |
5339 | }; | |
5340 | ||
5341 | interface "eth*"; # No need for any other options | |
5342 | ||
5343 | prefix 2001:0DB8:1234::/48 { | |
5344 | preferred lifetime 0; # Deprecated address range | |
5345 | }; | |
5346 | ||
5347 | prefix 2001:0DB8:2000::/48 { | |
5348 | autonomous off; # Do not autoconfigure | |
5349 | }; | |
fc06fb62 OZ |
5350 | |
5351 | rdnss 2001:0DB8:1234::10; # Short form of RDNSS | |
5352 | ||
5353 | rdnss { | |
5354 | lifetime mult 10; | |
5355 | ns 2001:0DB8:1234::11; | |
5356 | ns 2001:0DB8:1234::12; | |
5357 | }; | |
5358 | ||
5359 | dnssl { | |
5360 | lifetime 3600; | |
5361 | domain "abc.com"; | |
5362 | domain "xyz.com"; | |
5363 | }; | |
6bcef225 OZ |
5364 | } |
5365 | </code> | |
5366 | ||
cf3e3845 | 5367 | |
1532a244 | 5368 | <sect>RIP |
b9864aa8 | 5369 | <label id="rip"> |
d37f899b | 5370 | |
371adba6 | 5371 | <sect1>Introduction |
b9864aa8 | 5372 | <label id="rip-intro"> |
d37f899b | 5373 | |
dad92c30 OZ |
5374 | <p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, |
5375 | where each router broadcasts (to all its neighbors) distances to all networks it | |
5376 | can reach. When a router hears distance to another network, it increments it and | |
5377 | broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some | |
5378 | network goes unreachable, routers keep telling each other that its distance is | |
5379 | the original distance plus 1 (actually, plus interface metric, which is usually | |
5380 | one). After some time, the distance reaches infinity (that's 15 in RIP) and all | |
5381 | routers know that network is unreachable. RIP tries to minimize situations where | |
5382 | counting to infinity is necessary, because it is slow. Due to infinity being 16, | |
5383 | you can't use RIP on networks where maximal distance is higher than 15 | |
8465dccb OZ |
5384 | hosts. |
5385 | ||
7935b9d2 | 5386 | <p>BIRD supports RIPv1 (<rfc id="1058">), RIPv2 (<rfc id="2453">), RIPng (<rfc |
b729e731 OZ |
5387 | id="2080">), Triggered RIP for demand circuits (<rfc id="2091">), and RIP |
5388 | cryptographic authentication (<rfc id="4822">). | |
440439e3 | 5389 | |
1532a244 | 5390 | <p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow |
dad92c30 OZ |
5391 | convergence, big network load and inability to handle larger networks makes it |
5392 | pretty much obsolete. It is still usable on very small networks. | |
d37f899b | 5393 | |
371adba6 | 5394 | <sect1>Configuration |
b9864aa8 | 5395 | <label id="rip-config"> |
d37f899b | 5396 | |
8465dccb | 5397 | <p>RIP configuration consists mainly of common protocol options and interface |
da3cf9ea OZ |
5398 | definitions, most RIP options are interface specific. RIPng (RIP for IPv6) |
5399 | protocol instance can be configured by using <cf/rip ng/ instead of just | |
5400 | <cf/rip/ as a protocol type. | |
8465dccb | 5401 | |
cf3e3845 OZ |
5402 | <p>RIP needs one IPv4 channel. RIPng needs one IPv6 channel. If no channel is |
5403 | configured, appropriate channel is defined with default parameters. | |
5404 | ||
8465dccb | 5405 | <code> |
da3cf9ea | 5406 | protocol rip [ng] [<name>] { |
8465dccb OZ |
5407 | infinity <number>; |
5408 | ecmp <switch> [limit <number>]; | |
5409 | interface <interface pattern> { | |
5410 | metric <number>; | |
5411 | mode multicast|broadcast; | |
5412 | passive <switch>; | |
5413 | address <ip>; | |
5414 | port <number>; | |
5415 | version 1|2; | |
5416 | split horizon <switch>; | |
5417 | poison reverse <switch>; | |
b729e731 | 5418 | demand circuit <switch>; |
8465dccb OZ |
5419 | check zero <switch>; |
5420 | update time <number>; | |
5421 | timeout time <number>; | |
5422 | garbage time <number>; | |
5423 | ecmp weight <number>; | |
5424 | ttl security <switch>; | tx only; | |
5425 | tx class|dscp <number>; | |
5426 | tx priority <number>; | |
5427 | rx buffer <number>; | |
5428 | tx length <number>; | |
5429 | check link <switch>; | |
5430 | authentication none|plaintext|cryptographic; | |
5431 | password "<text>"; | |
5432 | password "<text>" { | |
5433 | id <num>; | |
5434 | generate from "<date>"; | |
5435 | generate to "<date>"; | |
5436 | accept from "<date>"; | |
5437 | accept to "<date>"; | |
64385aee PT |
5438 | from "<date>"; |
5439 | to "<date>"; | |
5440 | algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 ); | |
8465dccb OZ |
5441 | }; |
5442 | }; | |
5443 | } | |
5444 | </code> | |
d37f899b PM |
5445 | |
5446 | <descrip> | |
b9864aa8 | 5447 | <tag><label id="rip-infinity">infinity <M>number</M></tag> |
8465dccb OZ |
5448 | Selects the distance of infinity. Bigger values will make |
5449 | protocol convergence even slower. The default value is 16. | |
dad92c30 | 5450 | |
b9864aa8 | 5451 | <tag><label id="rip-ecmp">ecmp <M>switch</M> [limit <M>number</M>]</tag> |
8465dccb OZ |
5452 | This option specifies whether RIP is allowed to generate ECMP |
5453 | (equal-cost multipath) routes. Such routes are used when there are | |
5454 | several directions to the destination, each with the same (computed) | |
5455 | cost. This option also allows to specify a limit on maximum number of | |
cf3e3845 OZ |
5456 | nexthops in one route. By default, ECMP is enabled if supported by |
5457 | Kernel. Default value of the limit is 16. | |
8465dccb | 5458 | |
9df52a98 | 5459 | <tag><label id="rip-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag> |
8465dccb OZ |
5460 | Interface definitions specify a set of interfaces on which the |
5461 | protocol is activated and contain interface specific options. | |
b9864aa8 | 5462 | See <ref id="proto-iface" name="interface"> common options for |
8465dccb | 5463 | detailed description. |
d37f899b PM |
5464 | </descrip> |
5465 | ||
8465dccb | 5466 | <p>Interface specific options: |
ef4a50be OZ |
5467 | |
5468 | <descrip> | |
b9864aa8 | 5469 | <tag><label id="rip-iface-metric">metric <m/num/</tag> |
8465dccb OZ |
5470 | This option specifies the metric of the interface. When a route is |
5471 | received from the interface, its metric is increased by this value | |
5472 | before further processing. Valid values are 1-255, but values higher | |
5473 | than infinity has no further meaning. Default: 1. | |
5474 | ||
b9864aa8 | 5475 | <tag><label id="rip-iface-mode">mode multicast|broadcast</tag> |
8465dccb OZ |
5476 | This option selects the mode for RIP to use on the interface. The |
5477 | default is multicast mode for RIPv2 and broadcast mode for RIPv1. | |
5478 | RIPng always uses the multicast mode. | |
5479 | ||
b9864aa8 | 5480 | <tag><label id="rip-iface-passive">passive <m/switch/</tag> |
8465dccb OZ |
5481 | Passive interfaces receive routing updates but do not transmit any |
5482 | messages. Default: no. | |
5483 | ||
b9864aa8 | 5484 | <tag><label id="rip-iface-address">address <m/ip/</tag> |
8465dccb OZ |
5485 | This option specifies a destination address used for multicast or |
5486 | broadcast messages, the default is the official RIP (224.0.0.9) or RIPng | |
5487 | (ff02::9) multicast address, or an appropriate broadcast address in the | |
5488 | broadcast mode. | |
5489 | ||
b9864aa8 | 5490 | <tag><label id="rip-iface-port">port <m/number/</tag> |
8465dccb OZ |
5491 | This option selects an UDP port to operate on, the default is the |
5492 | official RIP (520) or RIPng (521) port. | |
5493 | ||
b9864aa8 | 5494 | <tag><label id="rip-iface-version">version 1|2</tag> |
8465dccb OZ |
5495 | This option selects the version of RIP used on the interface. For RIPv1, |
5496 | automatic subnet aggregation is not implemented, only classful network | |
5497 | routes and host routes are propagated. Note that BIRD allows RIPv1 to be | |
5498 | configured with features that are defined for RIPv2 only, like | |
5499 | authentication or using multicast sockets. The default is RIPv2 for IPv4 | |
5500 | RIP, the option is not supported for RIPng, as no further versions are | |
5501 | defined. | |
5502 | ||
b9864aa8 | 5503 | <tag><label id="rip-iface-version-only">version only <m/switch/</tag> |
43fc6bb0 OZ |
5504 | Regardless of RIP version configured for the interface, BIRD accepts |
5505 | incoming packets of any RIP version. This option restrict accepted | |
5506 | packets to the configured version. Default: no. | |
5507 | ||
b9864aa8 | 5508 | <tag><label id="rip-iface-split-horizon">split horizon <m/switch/</tag> |
8465dccb OZ |
5509 | Split horizon is a scheme for preventing routing loops. When split |
5510 | horizon is active, routes are not regularly propagated back to the | |
5511 | interface from which they were received. They are either not propagated | |
5512 | back at all (plain split horizon) or propagated back with an infinity | |
5513 | metric (split horizon with poisoned reverse). Therefore, other routers | |
5514 | on the interface will not consider the router as a part of an | |
5515 | independent path to the destination of the route. Default: yes. | |
5516 | ||
b9864aa8 | 5517 | <tag><label id="rip-iface-poison-reverse">poison reverse <m/switch/</tag> |
8465dccb OZ |
5518 | When split horizon is active, this option specifies whether the poisoned |
5519 | reverse variant (propagating routes back with an infinity metric) is | |
5520 | used. The poisoned reverse has some advantages in faster convergence, | |
5521 | but uses more network traffic. Default: yes. | |
5522 | ||
b729e731 OZ |
5523 | <tag><label id="rip-iface-demand-circuit">demand circuit <m/switch/</tag> |
5524 | Regular RIP sends periodic full updates on an interface. There is the | |
5525 | Triggered RIP extension for demand circuits (<rfc id="2091">), which | |
5526 | removes periodic updates and introduces update acknowledgments. When | |
5527 | enabled, there is no RIP communication in steady-state network. Note | |
5528 | that in order to work, it must be enabled on both sides. As there are | |
5529 | no hello packets, it depends on hardware link state to detect neighbor | |
5530 | failures. Also, it is designed for PtP links and it does not work | |
5531 | properly with multiple RIP neighbors on an interface. Default: no. | |
5532 | ||
b9864aa8 | 5533 | <tag><label id="rip-iface-check-zero">check zero <m/switch/</tag> |
8465dccb OZ |
5534 | Received RIPv1 packets with non-zero values in reserved fields should |
5535 | be discarded. This option specifies whether the check is performed or | |
5536 | such packets are just processed as usual. Default: yes. | |
5537 | ||
b9864aa8 | 5538 | <tag><label id="rip-iface-update-time">update time <m/number/</tag> |
8465dccb OZ |
5539 | Specifies the number of seconds between periodic updates. A lower number |
5540 | will mean faster convergence but bigger network load. Default: 30. | |
5541 | ||
b9864aa8 | 5542 | <tag><label id="rip-iface-timeout-time">timeout time <m/number/</tag> |
8465dccb OZ |
5543 | Specifies the time interval (in seconds) between the last received route |
5544 | announcement and the route expiration. After that, the network is | |
5545 | considered unreachable, but still is propagated with infinity distance. | |
5546 | Default: 180. | |
5547 | ||
b9864aa8 | 5548 | <tag><label id="rip-iface-garbage-time">garbage time <m/number/</tag> |
8465dccb OZ |
5549 | Specifies the time interval (in seconds) between the route expiration |
5550 | and the removal of the unreachable network entry. The garbage interval, | |
5551 | when a route with infinity metric is propagated, is used for both | |
5552 | internal (after expiration) and external (after withdrawal) routes. | |
5553 | Default: 120. | |
5554 | ||
b9864aa8 | 5555 | <tag><label id="rip-iface-ecmp-weight">ecmp weight <m/number/</tag> |
8465dccb OZ |
5556 | When ECMP (multipath) routes are allowed, this value specifies a |
5557 | relative weight used for nexthops going through the iface. Valid | |
5558 | values are 1-256. Default value is 1. | |
ef4a50be | 5559 | |
b9864aa8 | 5560 | <tag><label id="rip-iface-auth">authentication none|plaintext|cryptographic</tag> |
8465dccb OZ |
5561 | Selects authentication method to be used. <cf/none/ means that packets |
5562 | are not authenticated at all, <cf/plaintext/ means that a plaintext | |
5563 | password is embedded into each packet, and <cf/cryptographic/ means that | |
64385aee PT |
5564 | packets are authenticated using some cryptographic hash function |
5565 | selected by option <cf/algorithm/ for each key. The default | |
5566 | cryptographic algorithm for RIP keys is Keyed-MD5. If you set | |
8465dccb OZ |
5567 | authentication to not-none, it is a good idea to add <cf>password</cf> |
5568 | section. Default: none. | |
5569 | ||
b9864aa8 PT |
5570 | <tag><label id="rip-iface-pass">password "<m/text/"</tag> |
5571 | Specifies a password used for authentication. See <ref id="proto-pass" | |
8465dccb | 5572 | name="password"> common option for detailed description. |
ef4a50be | 5573 | |
b9864aa8 | 5574 | <tag><label id="rip-iface-ttl-security">ttl security [<m/switch/ | tx only]</tag> |
dad92c30 OZ |
5575 | TTL security is a feature that protects routing protocols from remote |
5576 | spoofed packets by using TTL 255 instead of TTL 1 for protocol packets | |
5577 | destined to neighbors. Because TTL is decremented when packets are | |
5578 | forwarded, it is non-trivial to spoof packets with TTL 255 from remote | |
5579 | locations. | |
5580 | ||
5581 | If this option is enabled, the router will send RIP packets with TTL 255 | |
5582 | and drop received packets with TTL less than 255. If this option si set | |
5583 | to <cf/tx only/, TTL 255 is used for sent packets, but is not checked | |
5584 | for received packets. Such setting does not offer protection, but offers | |
5585 | compatibility with neighbors regardless of whether they use ttl | |
5586 | security. | |
5587 | ||
7935b9d2 PT |
5588 | For RIPng, TTL security is a standard behavior (required by <rfc |
5589 | id="2080">) and therefore default value is yes. For IPv4 RIP, default | |
5590 | value is no. | |
6ac4f87a | 5591 | |
b9864aa8 | 5592 | <tag><label id="rip-iface-tx-class">tx class|dscp|priority <m/number/</tag> |
dad92c30 | 5593 | These options specify the ToS/DiffServ/Traffic class/Priority of the |
b9864aa8 | 5594 | outgoing RIP packets. See <ref id="proto-tx-class" name="tx class"> common |
dad92c30 | 5595 | option for detailed description. |
d37f899b | 5596 | |
b9864aa8 | 5597 | <tag><label id="rip-iface-rx-buffer">rx buffer <m/number/</tag> |
8465dccb OZ |
5598 | This option specifies the size of buffers used for packet processing. |
5599 | The buffer size should be bigger than maximal size of received packets. | |
5600 | The default value is 532 for IPv4 RIP and interface MTU value for RIPng. | |
5601 | ||
b9864aa8 | 5602 | <tag><label id="rip-iface-tx-length">tx length <m/number/</tag> |
8465dccb OZ |
5603 | This option specifies the maximum length of generated RIP packets. To |
5604 | avoid IP fragmentation, it should not exceed the interface MTU value. | |
5605 | The default value is 532 for IPv4 RIP and interface MTU value for RIPng. | |
5606 | ||
b9864aa8 | 5607 | <tag><label id="rip-iface-check-link">check link <m/switch/</tag> |
8465dccb OZ |
5608 | If set, the hardware link state (as reported by OS) is taken into |
5609 | consideration. When the link disappears (e.g. an ethernet cable is | |
5610 | unplugged), neighbors are immediately considered unreachable and all | |
5611 | routes received from them are withdrawn. It is possible that some | |
64385aee | 5612 | hardware drivers or platforms do not implement this feature. |
cf3e3845 | 5613 | Default: yes. |
d37f899b PM |
5614 | </descrip> |
5615 | ||
371adba6 | 5616 | <sect1>Attributes |
b9864aa8 | 5617 | <label id="rip-attr"> |
d37f899b | 5618 | |
1b55b1a3 MM |
5619 | <p>RIP defines two route attributes: |
5620 | ||
5621 | <descrip> | |
157f6c2a | 5622 | <tag><label id="rta-rip-metric">int rip_metric</tag> |
65d2a88d | 5623 | RIP metric of the route (ranging from 0 to <cf/infinity/). When routes |
dad92c30 | 5624 | from different RIP instances are available and all of them have the same |
8465dccb OZ |
5625 | preference, BIRD prefers the route with lowest <cf/rip_metric/. When a |
5626 | non-RIP route is exported to RIP, the default metric is 1. | |
dad92c30 | 5627 | |
157f6c2a | 5628 | <tag><label id="rta-rip-tag">int rip_tag</tag> |
dad92c30 OZ |
5629 | RIP route tag: a 16-bit number which can be used to carry additional |
5630 | information with the route (for example, an originating AS number in | |
8465dccb OZ |
5631 | case of external routes). When a non-RIP route is exported to RIP, the |
5632 | default tag is 0. | |
1b55b1a3 MM |
5633 | </descrip> |
5634 | ||
371adba6 | 5635 | <sect1>Example |
b9864aa8 | 5636 | <label id="rip-exam"> |
1b55b1a3 MM |
5637 | |
5638 | <p><code> | |
8465dccb | 5639 | protocol rip { |
cf3e3845 OZ |
5640 | ipv4 { |
5641 | import all; | |
5642 | export all; | |
5643 | }; | |
9be12a7d OZ |
5644 | interface "eth*" { |
5645 | metric 2; | |
5646 | port 1520; | |
5647 | mode multicast; | |
5648 | update time 12; | |
5649 | timeout time 60; | |
5650 | authentication cryptographic; | |
5651 | password "secret" { algorithm hmac sha256; }; | |
5652 | }; | |
d37f899b | 5653 | } |
a0dd1c74 | 5654 | </code> |
d37f899b | 5655 | |
cf3e3845 | 5656 | |
65d2a88d | 5657 | <sect>RPKI |
159d619c | 5658 | <label id="rpki"> |
65d2a88d PT |
5659 | |
5660 | <sect1>Introduction | |
5661 | ||
5662 | <p>The Resource Public Key Infrastructure (RPKI) is mechanism for origin | |
0d1a11cc OZ |
5663 | validation of BGP routes (<rfc id="6480">). BIRD supports only so-called |
5664 | RPKI-based origin validation. There is implemented RPKI to Router (RPKI-RTR) | |
5665 | protocol (<rfc id="6810">). It uses some of the RPKI data to allow a router to | |
5666 | verify that the autonomous system announcing an IP address prefix is in fact | |
5667 | authorized to do so. This is not crypto checked so can be violated. But it | |
5668 | should prevent the vast majority of accidental hijackings on the Internet today, | |
5669 | e.g. the famous Pakistani accidental announcement of YouTube's address space. | |
65d2a88d PT |
5670 | |
5671 | <p>The RPKI-RTR protocol receives and maintains a set of ROAs from a cache | |
0d1a11cc OZ |
5672 | server (also called validator). You can validate routes (<rfc id="6483">, |
5673 | <rfc id="6811">) using function <cf/roa_check()/ in filter and set it as import | |
5674 | filter at the BGP protocol. BIRD offers crude automatic re-validating of | |
5675 | affected routes after RPKI update, see option <ref id="proto-rpki-reload" | |
5676 | name="rpki reload">. Or you can use a BIRD client command <cf>reload in | |
5677 | <m/bgp_protocol_name/</cf> for manual call of revalidation of all routes. | |
65d2a88d PT |
5678 | |
5679 | <sect1>Supported transports | |
71c51aa4 | 5680 | <p> |
65d2a88d PT |
5681 | <itemize> |
5682 | <item>Unprotected transport over TCP uses a port 323. The cache server | |
5683 | and BIRD router should be on the same trusted and controlled network | |
5684 | for security reasons. | |
5685 | <item>SSHv2 encrypted transport connection uses the normal SSH port | |
5686 | 22. | |
5687 | </itemize> | |
5688 | ||
5689 | <sect1>Configuration | |
5690 | ||
5691 | <p>We currently support just one cache server per protocol. However you can | |
5692 | define more RPKI protocols generally. | |
5693 | ||
5694 | <code> | |
5695 | protocol rpki [<name>] { | |
5696 | roa4 { table <tab>; }; | |
5697 | roa6 { table <tab>; }; | |
5698 | remote <ip> | "<domain>" [port <num>]; | |
5699 | port <num>; | |
e2728c80 | 5700 | local address <ip>; |
65d2a88d PT |
5701 | refresh [keep] <num>; |
5702 | retry [keep] <num>; | |
5703 | expire [keep] <num>; | |
5704 | transport tcp; | |
5705 | transport ssh { | |
5706 | bird private key "</path/to/id_rsa>"; | |
5707 | remote public key "</path/to/known_host>"; | |
5708 | user "<name>"; | |
5709 | }; | |
5710 | } | |
5711 | </code> | |
5712 | ||
cf3e3845 OZ |
5713 | <p>Alse note that you have to specify the ROA channel. If you want to import |
5714 | only IPv4 prefixes you have to specify only roa4 channel. Similarly with IPv6 | |
5715 | prefixes only. If you want to fetch both IPv4 and even IPv6 ROAs you have to | |
5716 | specify both channels. | |
65d2a88d PT |
5717 | |
5718 | <sect2>RPKI protocol options | |
71c51aa4 | 5719 | <p> |
65d2a88d PT |
5720 | <descrip> |
5721 | <tag>remote <m/ip/ | "<m/hostname/" [port <m/num/]</tag> Specifies | |
5722 | a destination address of the cache server. Can be specified by an IP | |
5723 | address or by full domain name string. Only one cache can be specified | |
5724 | per protocol. This option is required. | |
5725 | ||
5726 | <tag>port <m/num/</tag> Specifies the port number. The default port | |
5727 | number is 323 for transport without any encryption and 22 for transport | |
5728 | with SSH encryption. | |
5729 | ||
e2728c80 JS |
5730 | <tag>local address <m/ip/</tag> |
5731 | Define local address we should use as a source address for the RTR session. | |
5732 | ||
65d2a88d PT |
5733 | <tag>refresh [keep] <m/num/</tag> Time period in seconds. Tells how |
5734 | long to wait before next attempting to poll the cache using a Serial | |
5735 | Query or a Reset Query packet. Must be lower than 86400 seconds (one | |
5736 | day). Too low value can caused a false positive detection of | |
5737 | network connection problems. A keyword <cf/keep/ suppresses updating | |
5738 | this value by a cache server. | |
5739 | Default: 3600 seconds | |
5740 | ||
5741 | <tag>retry [keep] <m/num/</tag> Time period in seconds between a failed | |
5742 | Serial/Reset Query and a next attempt. Maximum allowed value is 7200 | |
5743 | seconds (two hours). Too low value can caused a false positive | |
5744 | detection of network connection problems. A keyword <cf/keep/ | |
5745 | suppresses updating this value by a cache server. | |
5746 | Default: 600 seconds | |
5747 | ||
5748 | <tag>expire [keep] <m/num/</tag> Time period in seconds. Received | |
5749 | records are deleted if the client was unable to successfully refresh | |
5750 | data for this time period. Must be in range from 600 seconds (ten | |
5751 | minutes) to 172800 seconds (two days). A keyword <cf/keep/ | |
5752 | suppresses updating this value by a cache server. | |
5753 | Default: 7200 seconds | |
5754 | ||
fc1e3211 OZ |
5755 | <tag>ignore max length <m/switch/</tag> |
5756 | Ignore received max length in ROA records and use max value (32 or 128) | |
5757 | instead. This may be useful for implementing loose RPKI check for | |
5758 | blackholes. Default: disabled. | |
5759 | ||
65d2a88d PT |
5760 | <tag>transport tcp</tag> Unprotected transport over TCP. It's a default |
5761 | transport. Should be used only on secure private networks. | |
5762 | Default: tcp | |
5763 | ||
5764 | <tag>transport ssh { <m/SSH transport options.../ }</tag> It enables a | |
5765 | SSHv2 transport encryption. Cannot be combined with a TCP transport. | |
5766 | Default: off | |
5767 | </descrip> | |
5768 | ||
5769 | <sect3>SSH transport options | |
71c51aa4 | 5770 | <p> |
65d2a88d PT |
5771 | <descrip> |
5772 | <tag>bird private key "<m>/path/to/id_rsa</m>"</tag> | |
5773 | A path to the BIRD's private SSH key for authentication. | |
5774 | It can be a <cf><m>id_rsa</m></cf> file. | |
5775 | ||
5776 | <tag>remote public key "<m>/path/to/known_host</m>"</tag> | |
5777 | A path to the cache's public SSH key for verification identity | |
5778 | of the cache server. It could be a path to <cf><m>known_host</m></cf> file. | |
5779 | ||
5780 | <tag>user "<m/name/"</tag> | |
5781 | A SSH user name for authentication. This option is a required. | |
5782 | </descrip> | |
5783 | ||
5784 | <sect1>Examples | |
5785 | <sect2>BGP origin validation | |
5786 | <p>Policy: Don't import <cf/ROA_INVALID/ routes. | |
5787 | <code> | |
5788 | roa4 table r4; | |
5789 | roa6 table r6; | |
5790 | ||
5791 | protocol rpki { | |
5792 | debug all; | |
cf3e3845 | 5793 | |
65d2a88d PT |
5794 | roa4 { table r4; }; |
5795 | roa6 { table r6; }; | |
5796 | ||
5797 | # Please, do not use rpki-validator.realmv6.org in production | |
5798 | remote "rpki-validator.realmv6.org" port 8282; | |
cf3e3845 | 5799 | |
65d2a88d PT |
5800 | retry keep 5; |
5801 | refresh keep 30; | |
5802 | expire 600; | |
5803 | } | |
5804 | ||
cf3e3845 OZ |
5805 | filter peer_in_v4 { |
5806 | if (roa_check(r4, net, bgp_path.last) = ROA_INVALID) then | |
65d2a88d | 5807 | { |
eeb2c616 | 5808 | print "Ignore RPKI invalid ", net, " for ASN ", bgp_path.last; |
65d2a88d PT |
5809 | reject; |
5810 | } | |
5811 | accept; | |
5812 | } | |
5813 | ||
5814 | protocol bgp { | |
5815 | debug all; | |
5816 | local as 65000; | |
5817 | neighbor 192.168.2.1 as 65001; | |
3831b619 OZ |
5818 | ipv4 { |
5819 | import filter peer_in_v4; | |
5820 | export none; | |
5821 | }; | |
65d2a88d PT |
5822 | } |
5823 | </code> | |
5824 | ||
5825 | <sect2>SSHv2 transport encryption | |
71c51aa4 | 5826 | <p> |
65d2a88d PT |
5827 | <code> |
5828 | roa4 table r4; | |
5829 | roa6 table r6; | |
5830 | ||
5831 | protocol rpki { | |
5832 | debug all; | |
cf3e3845 | 5833 | |
65d2a88d PT |
5834 | roa4 { table r4; }; |
5835 | roa6 { table r6; }; | |
cf3e3845 | 5836 | |
65d2a88d PT |
5837 | remote 127.0.0.1 port 2345; |
5838 | transport ssh { | |
5839 | bird private key "/home/birdgeek/.ssh/id_rsa"; | |
5840 | remote public key "/home/birdgeek/.ssh/known_hosts"; | |
5841 | user "birdgeek"; | |
5842 | }; | |
cf3e3845 | 5843 | |
65d2a88d PT |
5844 | # Default interval values |
5845 | } | |
5846 | </code> | |
5847 | ||
5848 | ||
371adba6 | 5849 | <sect>Static |
b9864aa8 | 5850 | <label id="static"> |
1b55b1a3 | 5851 | |
0e4789c2 | 5852 | <p>The Static protocol doesn't communicate with other routers in the network, |
f8e2d916 | 5853 | but instead it allows you to define routes manually. This is often used for |
79a2b697 | 5854 | specifying how to forward packets to parts of the network which don't use |
dad92c30 OZ |
5855 | dynamic routing at all and also for defining sink routes (i.e., those telling to |
5856 | return packets as undeliverable if they are in your IP block, you don't have any | |
5857 | specific destination for them and you don't want to send them out through the | |
5858 | default route to prevent routing loops). | |
5859 | ||
43fc6bb0 OZ |
5860 | <p>There are three classes of definitions in Static protocol configuration -- |
5861 | global options, static route definitions, and per-route options. Usually, the | |
3347aaaf OZ |
5862 | definition of the protocol contains mainly a list of static routes. Static |
5863 | routes have no specific attributes, but <ref id="rta-igp-metric" name="igp_metric"> | |
5864 | attribute is used to compare static routes with the same preference. | |
5865 | ||
5866 | <p>The list of static routes may contain multiple routes for the same network | |
5867 | (usually, but not necessary, distinquished by <cf/preference/ or <cf/igp_metric/), | |
5868 | but only routes of the same network type are allowed, as the static protocol | |
5869 | has just one channel. E.g., to have both IPv4 and IPv6 static routes, define two | |
5870 | static protocols, each with appropriate routes and channel. | |
43fc6bb0 | 5871 | |
8a708856 OZ |
5872 | <p>The Static protocol can be configured as MPLS-aware (by defining both the |
5873 | primary channel and MPLS channel). In that case the Static protocol assigns | |
5874 | labels to IP routes and automatically announces corresponding MPLS route for | |
5875 | each labeled route. | |
5876 | ||
43fc6bb0 OZ |
5877 | <p>Global options: |
5878 | ||
5879 | <descrip> | |
b9864aa8 | 5880 | <tag><label id="static-check-link">check link <m/switch/</tag> |
43fc6bb0 OZ |
5881 | If set, hardware link states of network interfaces are taken into |
5882 | consideration. When link disappears (e.g. ethernet cable is unplugged), | |
5883 | static routes directing to that interface are removed. It is possible | |
5884 | that some hardware drivers or platforms do not implement this feature. | |
5885 | Default: off. | |
5886 | ||
b9864aa8 | 5887 | <tag><label id="static-igp-table">igp table <m/name/</tag> |
43fc6bb0 OZ |
5888 | Specifies a table that is used for route table lookups of recursive |
5889 | routes. Default: the same table as the protocol is connected to. | |
5890 | </descrip> | |
5891 | ||
5892 | <p>Route definitions (each may also contain a block of per-route options): | |
79a2b697 | 5893 | |
71c51aa4 | 5894 | <sect1>Regular routes; MPLS switching rules |
dad92c30 | 5895 | |
71c51aa4 | 5896 | <p>There exist several types of routes; keep in mind that <m/prefix/ syntax is |
3e52d112 | 5897 | <ref id="type-prefix" name="dependent on network type">. |
dad92c30 | 5898 | |
3e52d112 | 5899 | <descrip> |
0bfa216f | 5900 | <tag>route <m/prefix/ [mpls <m/number/] via <m/ip/|<m/"interface"/ [<m/per-nexthop options/] [via ...]</tag> |
8a708856 OZ |
5901 | Regular routes may bear one or more <ref id="route-next-hop" name="next |
5902 | hops">. Every next hop is preceded by <cf/via/ and configured as shown. | |
5903 | ||
5904 | When the Static protocol is MPLS-aware, the optional <cf/mpls/ statement | |
5905 | after <m/prefix/ specifies a static label for the labeled route, instead | |
5906 | of using dynamically allocated label. | |
cf3e3845 | 5907 | |
0bfa216f | 5908 | <tag>route <m/prefix/ [mpls <m/number/] recursive <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag> |
3e52d112 JMM |
5909 | Recursive nexthop resolves the given IP in the configured IGP table and |
5910 | uses that route's next hop. The MPLS stacks are concatenated; on top is | |
5911 | the IGP's nexthop stack and on bottom is this route's stack. | |
cf3e3845 | 5912 | |
0bfa216f | 5913 | <tag>route <m/prefix/ [mpls <m/number/] blackhole|unreachable|prohibit</tag> |
dad92c30 OZ |
5914 | Special routes specifying to silently drop the packet, return it as |
5915 | unreachable or return it as administratively prohibited. First two | |
5916 | targets are also known as <cf/drop/ and <cf/reject/. | |
43fc6bb0 | 5917 | </descrip> |
391931d4 | 5918 | |
3e52d112 JMM |
5919 | <p>When the particular destination is not available (the interface is down or |
5920 | the next hop of the route is not a neighbor at the moment), Static just | |
5921 | uninstalls the route from the table it is connected to and adds it again as soon | |
5922 | as the destination becomes adjacent again. | |
5923 | ||
a141959f OZ |
5924 | <sect2>Per-nexthop options |
5925 | ||
5926 | <p>There are several options that in a case of multipath route are per-nexthop | |
5927 | (i.e., they can be used multiple times for a route, one time for each nexthop). | |
5928 | Syntactically, they are not separate options but just parts of <cf/route/ | |
5929 | statement after each <cf/via/ statement, not separated by semicolons. E.g., | |
ecbae010 AZ |
5930 | statement <cf>route 10.0.0.0/8 via 192.0.2.1 bfd weight 1 via 192.0.2.2 weight |
5931 | 2;</cf> describes a route with two nexthops, the first nexthop has two per-nexthop | |
a141959f OZ |
5932 | options (<cf/bfd/ and <cf/weight 1/), the second nexthop has just <cf/weight 2/. |
5933 | ||
5934 | <descrip> | |
5935 | <tag><label id="static-route-bfd">bfd <m/switch/</tag> | |
5936 | The Static protocol could use BFD protocol for next hop liveness | |
5937 | detection. If enabled, a BFD session to the route next hop is created | |
5938 | and the static route is BFD-controlled -- the static route is announced | |
5939 | only if the next hop liveness is confirmed by BFD. If the BFD session | |
5940 | fails, the static route (or just the affected nexthop from multiple | |
5941 | ones) is removed. Note that this is a bit different compared to other | |
5942 | protocols, which may use BFD as an advisory mechanism for fast failure | |
5943 | detection but ignore it if a BFD session is not even established. Note | |
5944 | that BFD protocol also has to be configured, see <ref id="bfd" name="BFD"> | |
5945 | section for details. Default value is no. | |
5946 | ||
c3335b50 OZ |
5947 | <tag><label id="static-route-dev">dev <m/text/</tag> |
5948 | The outgoing interface associated with the nexthop. Useful for | |
5949 | link-local nexthop addresses or when multiple interfaces use the same | |
5950 | network prefix. By default, the outgoing interface is resolved from the | |
5951 | nexthop address. | |
5952 | ||
a141959f OZ |
5953 | <tag><label id="static-route-mpls">mpls <m/num/[/<m/num/[/<m/num/[...]]]</tag> |
5954 | MPLS labels that should be pushed to packets forwarded by the route. | |
5955 | The option could be used for both IP routes (on MPLS ingress routers) | |
5956 | and MPLS switching rules (on MPLS transit routers). Default value is | |
5957 | no labels. | |
5958 | ||
5959 | <tag><label id="static-route-onlink">onlink <m/switch/</tag> | |
5960 | Onlink flag means that the specified nexthop is accessible on the | |
5961 | (specified) interface regardless of IP prefixes of the interface. The | |
5962 | interface must be attached to nexthop IP address using link-local-scope | |
5963 | format (e.g. <cf/192.0.2.1%eth0/). Default value is no. | |
5964 | ||
5965 | <tag><label id="static-route-weight">weight <m/switch/</tag> | |
5966 | For multipath routes, this value specifies a relative weight of the | |
5967 | nexthop. Allowed values are 1-256. Default value is 1. | |
5968 | </descrip> | |
5969 | ||
3e52d112 JMM |
5970 | <sect1>Route Origin Authorization |
5971 | ||
5972 | <p>The ROA config is just <cf>route <m/prefix/ max <m/int/ as <m/int/</cf> with no nexthop. | |
5973 | ||
08571b20 MM |
5974 | <sect1>Autonomous System Provider Authorization |
5975 | ||
5976 | <p>The ASPA config is <cf>route aspa <m/int/ providers <m/int/ [, <m/int/ ...]</cf> with no nexthop. | |
5977 | The first ASN is client and the following are a list of providers. | |
5978 | For a transit, you can also write <cf>route aspa <m/int/ transit</cf> to get | |
5979 | the no-provider ASPA. | |
5980 | ||
3e52d112 JMM |
5981 | <sect1>Flowspec |
5982 | <label id="flowspec-network-type"> | |
5983 | ||
5984 | <p>The flow specification are rules for routers and firewalls for filtering | |
5985 | purpose. It is described by <rfc id="5575">. There are 3 types of arguments: | |
dd8481cc | 5986 | <m/inet4/ or <m/inet6/ prefixes, numeric matching expressions and bitmask |
3e52d112 JMM |
5987 | matching expressions. |
5988 | ||
dd8481cc | 5989 | Numeric matching is a matching sequence of numbers and ranges separeted by a |
3e52d112 JMM |
5990 | commas (<cf/,/) (e.g. <cf/10,20,30/). Ranges can be written using double dots |
5991 | <cf/../ notation (e.g. <cf/80..90,120..124/). An alternative notation are | |
5992 | sequence of one or more pairs of relational operators and values separated by | |
5993 | logical operators <cf/&&/ or <cf/||/. Allowed relational operators are <cf/=/, | |
5994 | <cf/!=/, <cf/</, <cf/<=/, <cf/>/, <cf/>=/, <cf/true/ and <cf/false/. | |
5995 | ||
dd8481cc OZ |
5996 | Bitmask matching is written using <m/value/<cf>/</cf><m/mask/ or |
5997 | <cf/!/<m/value/<cf>/</cf><m/mask/ pairs. It means that <cf/(/<m/data/ <cf/&/ | |
5998 | <m/mask/<cf/)/ is or is not equal to <m/value/. It is also possible to use | |
5999 | multiple value/mask pairs connected by logical operators <cf/&&/ or <cf/||/. | |
c3c691e9 OZ |
6000 | Note that for negated matches, value must be either zero or equal to bitmask |
6001 | (e.g. !0x0/0xf or !0xf/0xf, but not !0x3/0xf). | |
dd8481cc | 6002 | |
3e52d112 JMM |
6003 | <sect2>IPv4 Flowspec |
6004 | ||
6005 | <p><descrip> | |
6006 | <tag><label id="flow-dst">dst <m/inet4/</tag> | |
6007 | Set a matching destination prefix (e.g. <cf>dst 192.168.0.0/16</cf>). | |
6008 | Only this option is mandatory in IPv4 Flowspec. | |
6009 | ||
6010 | <tag><label id="flow-src">src <m/inet4/</tag> | |
6011 | Set a matching source prefix (e.g. <cf>src 10.0.0.0/8</cf>). | |
6012 | ||
6013 | <tag><label id="flow-proto">proto <m/numbers-match/</tag> | |
6014 | Set a matching IP protocol numbers (e.g. <cf/proto 6/). | |
6015 | ||
6016 | <tag><label id="flow-port">port <m/numbers-match/</tag> | |
6017 | Set a matching source or destination TCP/UDP port numbers (e.g. | |
6018 | <cf>port 1..1023,1194,3306</cf>). | |
6019 | ||
6020 | <tag><label id="flow-dport">dport <m/numbers-match/</tag> | |
207ac485 | 6021 | Set a matching destination port numbers (e.g. <cf>dport 49151</cf>). |
3e52d112 JMM |
6022 | |
6023 | <tag><label id="flow-sport">sport <m/numbers-match/</tag> | |
6024 | Set a matching source port numbers (e.g. <cf>sport = 0</cf>). | |
6025 | ||
6026 | <tag><label id="flow-icmp-type">icmp type <m/numbers-match/</tag> | |
6027 | Set a matching type field number of an ICMP packet (e.g. <cf>icmp type | |
6028 | 3</cf>) | |
6029 | ||
6030 | <tag><label id="flow-icmp-code">icmp code <m/numbers-match/</tag> | |
6031 | Set a matching code field number of an ICMP packet (e.g. <cf>icmp code | |
6032 | 1</cf>) | |
6033 | ||
6034 | <tag><label id="flow-tcp-flags">tcp flags <m/bitmask-match/</tag> | |
6035 | Set a matching bitmask for TCP header flags (aka control bits) (e.g. | |
6036 | <cf>tcp flags 0x03/0x0f;</cf>). The maximum length of mask is 12 bits | |
6037 | (0xfff). | |
6038 | ||
6039 | <tag><label id="flow-length">length <m/numbers-match/</tag> | |
5caf32ef | 6040 | Set a matching packet length (e.g. <cf>length > 1500</cf>) |
3e52d112 JMM |
6041 | |
6042 | <tag><label id="flow-dscp">dscp <m/numbers-match/</tag> | |
5caf32ef | 6043 | Set a matching DiffServ Code Point number (e.g. <cf>dscp 8..15</cf>). |
3e52d112 JMM |
6044 | |
6045 | <tag><label id="flow-fragment">fragment <m/fragmentation-type/</tag> | |
6046 | Set a matching type of packet fragmentation. Allowed fragmentation | |
6047 | types are <cf/dont_fragment/, <cf/is_fragment/, <cf/first_fragment/, | |
6048 | <cf/last_fragment/ (e.g. <cf>fragment is_fragment && | |
6049 | !dont_fragment</cf>). | |
6050 | </descrip> | |
6051 | ||
6052 | <p><code> | |
6053 | protocol static { | |
6054 | flow4; | |
6055 | ||
6056 | route flow4 { | |
6057 | dst 10.0.0.0/8; | |
6058 | port > 24 && < 30 || 40..50,60..70,80 && >= 90; | |
6059 | tcp flags 0x03/0x0f; | |
6060 | length > 1024; | |
6061 | dscp = 63; | |
6062 | fragment dont_fragment, is_fragment || !first_fragment; | |
cf3e3845 | 6063 | }; |
3e52d112 JMM |
6064 | } |
6065 | </code> | |
6066 | ||
6067 | <sect2>Differences for IPv6 Flowspec | |
6068 | ||
6069 | <p>Flowspec IPv6 are same as Flowspec IPv4 with a few exceptions. | |
6070 | <itemize> | |
6071 | <item>Prefixes <m/inet6/ can be specified not only with prefix length, | |
6072 | but with prefix <cf/offset/ <m/num/ too (e.g. | |
6073 | <cf>::1234:5678:9800:0000/101 offset 64</cf>). Offset means to don't | |
6074 | care of <m/num/ first bits. | |
6075 | <item>IPv6 Flowspec hasn't mandatory any flowspec component. | |
6076 | <item>In IPv6 packets, there is a matching the last next header value | |
6077 | for a matching IP protocol number (e.g. <cf>next header 6</cf>). | |
6078 | <item>It is not possible to set <cf>dont_fragment</cf> as a type of | |
6079 | packet fragmentation. | |
6080 | </itemize> | |
6081 | ||
6082 | <p><descrip> | |
6083 | <tag><label id="flow6-dst">dst <m/inet6/ [offset <m/num/]</tag> | |
6084 | Set a matching destination IPv6 prefix (e.g. <cf>dst | |
6085 | ::1c77:3769:27ad:a11a/128 offset 64</cf>). | |
6086 | ||
6087 | <tag><label id="flow6-src">src <m/inet6/ [offset <m/num/]</tag> | |
6088 | Set a matching source IPv6 prefix (e.g. <cf>src fe80::/64</cf>). | |
6089 | ||
6090 | <tag><label id="flow6-next-header">next header <m/numbers-match/</tag> | |
6091 | Set a matching IP protocol numbers (e.g. <cf>next header != 6</cf>). | |
6092 | ||
6093 | <tag><label id="flow6-label">label <m/bitmask-match/</tag> | |
6094 | Set a 20-bit bitmask for matching Flow Label field in IPv6 packets | |
6095 | (e.g. <cf>label 0x8e5/0x8e5</cf>). | |
6096 | </descrip> | |
6097 | ||
6098 | <p><code> | |
6099 | protocol static { | |
6100 | flow6 { table myflow6; }; | |
6101 | ||
6102 | route flow6 { | |
6103 | dst fec0:1122:3344:5566:7788:99aa:bbcc:ddee/128; | |
6104 | src 0000:0000:0000:0001:1234:5678:9800:0000/101 offset 63; | |
6105 | next header = 23; | |
6106 | sport > 24 && < 30 || = 40 || 50,60,70..80; | |
6107 | dport = 50; | |
dd8481cc | 6108 | tcp flags 0x03/0x0f && !0/0xff || 0x33/0x33; |
3e52d112 JMM |
6109 | fragment !is_fragment || !first_fragment; |
6110 | label 0xaaaa/0xaaaa && 0x33/0x33; | |
cf3e3845 | 6111 | }; |
3e52d112 JMM |
6112 | } |
6113 | </code> | |
dad92c30 | 6114 | |
3e52d112 | 6115 | <sect1>Per-route options |
71c51aa4 | 6116 | <p> |
43fc6bb0 | 6117 | <descrip> |
b9864aa8 | 6118 | <tag><label id="static-route-filter"><m/filter expression/</tag> |
43fc6bb0 OZ |
6119 | This is a special option that allows filter expressions to be configured |
6120 | on per-route basis. Can be used multiple times. These expressions are | |
6121 | evaluated when the route is originated, similarly to the import filter | |
6122 | of the static protocol. This is especially useful for configuring route | |
6123 | attributes, e.g., <cf/ospf_metric1 = 100;/ for a route that will be | |
6124 | exported to the OSPF protocol. | |
79a2b697 MM |
6125 | </descrip> |
6126 | ||
a141959f OZ |
6127 | <sect1>Example static configs |
6128 | <label id="static-example"> | |
79a2b697 MM |
6129 | |
6130 | <p><code> | |
6131 | protocol static { | |
3e52d112 | 6132 | ipv4 { table testable; }; # Connect to a non-default routing table |
43fc6bb0 | 6133 | check link; # Advertise routes only if link is up |
9491f9f5 | 6134 | route 0.0.0.0/0 via 198.51.100.130; # Default route |
3e52d112 | 6135 | route 10.0.0.0/8 # Multipath route |
9491f9f5 | 6136 | via 198.51.100.10 weight 2 |
43fc6bb0 | 6137 | via 198.51.100.20 bfd # BFD-controlled next hop |
9491f9f5 | 6138 | via 192.0.2.1; |
a141959f | 6139 | route 203.0.113.0/24 blackhole; # Sink route |
c3335b50 OZ |
6140 | route 10.2.0.0/24 via "arc0"; # Direct route |
6141 | route 10.2.2.0/24 via 192.0.2.1 dev "eth0" onlink; # Route with both nexthop and iface | |
43fc6bb0 OZ |
6142 | route 192.168.10.0/24 via 198.51.100.100 { |
6143 | ospf_metric1 = 20; # Set extended attribute | |
6c11dbcf | 6144 | }; |
a141959f | 6145 | route 192.168.11.0/24 via 198.51.100.100 { |
43fc6bb0 OZ |
6146 | ospf_metric2 = 100; # Set extended attribute |
6147 | ospf_tag = 2; # Set extended attribute | |
6c11dbcf | 6148 | }; |
a141959f | 6149 | route 192.168.12.0/24 via 198.51.100.100 { |
df65d519 NK |
6150 | bgp_community.add((65535, 65281)); # Set extended BGP attribute |
6151 | bgp_large_community.add((64512, 1, 1)); # Set extended BGP attribute | |
6152 | }; | |
79a2b697 | 6153 | } |
a141959f OZ |
6154 | |
6155 | protocol static { | |
6156 | ipv6; # Channel is mandatory | |
6157 | route 2001:db8:10::/48 via 2001:db8:1::1; # Route with global nexthop | |
6158 | route 2001:db8:20::/48 via fe80::10%eth0; # Route with link-local nexthop | |
6159 | route 2001:db8:30::/48 via fe80::20%'eth1.60'; # Iface with non-alphanumeric characters | |
c3335b50 OZ |
6160 | route 2001:db8:40::/48 via fe80::30 dev "eth1"; # Another link-local nexthop |
6161 | route 2001:db8:50::/48 via "eth2"; # Direct route to eth2 | |
a141959f OZ |
6162 | route 2001:db8::/32 unreachable; # Unreachable route |
6163 | route ::/0 via 2001:db8:1::1 bfd; # BFD-controlled default route | |
6164 | } | |
79a2b697 MM |
6165 | </code> |
6166 | ||
cf3e3845 | 6167 | |
96264d4d | 6168 | <chapt>Conclusions |
b9864aa8 | 6169 | <label id="conclusion"> |
96264d4d PM |
6170 | |
6171 | <sect>Future work | |
b9864aa8 | 6172 | <label id="future-work"> |
96264d4d | 6173 | |
dad92c30 OZ |
6174 | <p>Although BIRD supports all the commonly used routing protocols, there are |
6175 | still some features which would surely deserve to be implemented in future | |
6176 | versions of BIRD: | |
96264d4d PM |
6177 | |
6178 | <itemize> | |
55b58d8c | 6179 | <item>Opaque LSA's |
96264d4d | 6180 | <item>Route aggregation and flap dampening |
96264d4d PM |
6181 | <item>Multicast routing protocols |
6182 | <item>Ports to other systems | |
6183 | </itemize> | |
6184 | ||
dad92c30 | 6185 | |
96264d4d | 6186 | <sect>Getting more help |
b9864aa8 | 6187 | <label id="help"> |
96264d4d PM |
6188 | |
6189 | <p>If you use BIRD, you're welcome to join the bird-users mailing list | |
d148d0af | 6190 | (<HTMLURL URL="mailto:bird-users@network.cz" name="bird-users@network.cz">) |
96264d4d | 6191 | where you can share your experiences with the other users and consult |
d148d0af OF |
6192 | your problems with the authors. To subscribe to the list, visit |
6193 | <HTMLURL URL="http://bird.network.cz/?m_list" name="http://bird.network.cz/?m_list">. | |
96264d4d PM |
6194 | The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">. |
6195 | ||
dad92c30 OZ |
6196 | <p>BIRD is a relatively young system and it probably contains some bugs. You can |
6197 | report any problems to the bird-users list and the authors will be glad to solve | |
6198 | them, but before you do so, please make sure you have read the available | |
6199 | documentation and that you are running the latest version (available at | |
6200 | <HTMLURL URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). | |
6201 | (Of course, a patch which fixes the bug is always welcome as an attachment.) | |
6202 | ||
6203 | <p>If you want to understand what is going inside, Internet standards are a good | |
6204 | and interesting reading. You can get them from | |
6205 | <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a | |
6206 | nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" | |
6207 | name="atrey.karlin.mff.cuni.cz:/pub/rfc">). | |
69477cad | 6208 | |
c184d9d0 | 6209 | <p><it/Good luck!/ |
69477cad | 6210 | |
371adba6 | 6211 | </book> |
7581b81b | 6212 | |
a0dd1c74 | 6213 | <!-- |
9b13fa4d | 6214 | LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools |
75317ab8 | 6215 | LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps |
5a203dac | 6216 | LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC |
75317ab8 | 6217 | LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth |
9b13fa4d | 6218 | LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP |
4e8ec666 | 6219 | LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC |
5a203dac | 6220 | LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU |
4e8ec666 | 6221 | LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc |
5a203dac | 6222 | LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats |
64722c98 | 6223 | LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt |
9b13fa4d | 6224 | LocalWords: proto wildcard |
5a64ac70 | 6225 | --> |