]>
Commit | Line | Data |
---|---|---|
04a22949 | 1 | <!doctype birddoc system> |
d37f899b PM |
2 | |
3 | <!-- | |
d150c637 | 4 | BIRD 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 PM |
16 | |
17 | Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later. | |
18 | ||
19 | --> | |
20 | ||
371adba6 | 21 | <book> |
d37f899b | 22 | |
aa185265 | 23 | <title>BIRD User's Guide |
d37f899b | 24 | <author> |
aa185265 MM |
25 | Ondrej Filip <it/<feela@network.cz>/, |
26 | Pavel Machek <it/<pavel@ucw.cz>/, | |
5516a66d OF |
27 | Martin Mares <it/<mj@ucw.cz>/, |
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 |
d37f899b | 42 | |
371adba6 | 43 | <sect>What is BIRD |
d37f899b | 44 | |
897cd7aa | 45 | <p><label id="intro"> |
dad92c30 OZ |
46 | The name `BIRD' is actually an acronym standing for `BIRD Internet Routing |
47 | Daemon'. Let's take a closer look at the meaning of the name: | |
48 | ||
49 | <p><em/BIRD/: Well, we think we have already explained that. It's an acronym | |
50 | standing for `BIRD Internet Routing Daemon', you remember, don't you? :-) | |
51 | ||
52 | <p><em/Internet Routing/: It's a program (well, a daemon, as you are going to | |
53 | discover in a moment) which works as a dynamic router in an Internet type | |
54 | network (that is, in a network running either the IPv4 or the IPv6 protocol). | |
55 | Routers are devices which forward packets between interconnected networks in | |
56 | order to allow hosts not connected directly to the same local area network to | |
57 | communicate with each other. They also communicate with the other routers in the | |
58 | Internet to discover the topology of the network which allows them to find | |
59 | optimal (in terms of some metric) rules for forwarding of packets (which are | |
60 | called routing tables) and to adapt themselves to the changing conditions such | |
61 | as outages of network links, building of new connections and so on. Most of | |
62 | these routers are costly dedicated devices running obscure firmware which is | |
63 | hard to configure and not open to any changes (on the other hand, their special | |
64 | hardware design allows them to keep up with lots of high-speed network | |
65 | interfaces, better than general-purpose computer does). Fortunately, most | |
66 | operating systems of the UNIX family allow an ordinary computer to act as a | |
67 | router and forward packets belonging to the other hosts, but only according to a | |
68 | statically configured table. | |
69 | ||
70 | <p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program | |
71 | running on background which does the dynamic part of Internet routing, that is | |
72 | it communicates with the other routers, calculates routing tables and sends them | |
73 | to the OS kernel which does the actual packet forwarding. There already exist | |
74 | other such routing daemons: routed (RIP only), GateD (non-free), | |
75 | Zebra <HTMLURL URL="http://www.zebra.org"> and | |
76 | MRTD <HTMLURL URL="http://sourceforge.net/projects/mrt">, | |
77 | but their capabilities are limited and they are relatively hard to configure | |
78 | and maintain. | |
897cd7aa MM |
79 | |
80 | <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings, | |
dad92c30 OZ |
81 | to support all the routing technology used in the today's Internet or planned to |
82 | be used in near future and to have a clean extensible architecture allowing new | |
83 | routing protocols to be incorporated easily. Among other features, BIRD | |
84 | supports: | |
897cd7aa MM |
85 | |
86 | <itemize> | |
87 | <item>both IPv4 and IPv6 protocols | |
88 | <item>multiple routing tables | |
89 | <item>the Border Gateway Protocol (BGPv4) | |
96264d4d | 90 | <item>the Routing Information Protocol (RIPv2) |
0c75411b | 91 | <item>the Open Shortest Path First protocol (OSPFv2, OSPFv3) |
6bcef225 | 92 | <item>the Router Advertisements for IPv6 hosts |
dad92c30 OZ |
93 | <item>a virtual protocol for exchange of routes between different |
94 | routing tables on a single host | |
897cd7aa MM |
95 | <item>a command-line interface allowing on-line control and inspection |
96 | of status of the daemon | |
dad92c30 OZ |
97 | <item>soft reconfiguration (no need to use complex online commands to |
98 | change the configuration, just edit the configuration file and | |
99 | notify BIRD to re-read it and it will smoothly switch itself to | |
100 | the new configuration, not disturbing routing protocols unless | |
101 | they are affected by the configuration changes) | |
02357f96 | 102 | <item>a powerful language for route filtering |
897cd7aa MM |
103 | </itemize> |
104 | ||
dad92c30 OZ |
105 | <p>BIRD has been developed at the Faculty of Math and Physics, Charles |
106 | University, Prague, Czech Republic as a student project. It can be freely | |
107 | distributed under the terms of the GNU General Public License. | |
108 | ||
109 | <p>BIRD has been designed to work on all UNIX-like systems. It has been | |
110 | developed and tested under Linux 2.0 to 2.6, and then ported to FreeBSD, NetBSD | |
111 | and OpenBSD, porting to other systems (even non-UNIX ones) should be relatively | |
112 | easy due to its highly modular architecture. | |
897cd7aa | 113 | |
dad92c30 OZ |
114 | <p>BIRD supports either IPv4 or IPv6 protocol, but have to be compiled separately |
115 | for each one. Therefore, a dualstack router would run two instances of BIRD (one | |
116 | for IPv4 and one for IPv6), with completely separate setups (configuration | |
117 | files, tools ...). | |
5adc02a6 | 118 | |
d37f899b | 119 | |
371adba6 | 120 | <sect>Installing BIRD |
440439e3 | 121 | |
dad92c30 OZ |
122 | <p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) |
123 | and Perl, installing BIRD should be as easy as: | |
440439e3 PM |
124 | |
125 | <code> | |
dad92c30 OZ |
126 | ./configure |
127 | make | |
128 | make install | |
129 | vi /usr/local/etc/bird.conf | |
c184d9d0 | 130 | bird |
440439e3 PM |
131 | </code> |
132 | ||
02357f96 | 133 | <p>You can use <tt>./configure --help</tt> to get a list of configure |
dad92c30 OZ |
134 | options. The most important ones are: <tt/--enable-ipv6/ which enables building |
135 | of an IPv6 version of BIRD, <tt/--with-protocols=/ to produce a slightly smaller | |
136 | BIRD executable by configuring out routing protocols you don't use, and | |
137 | <tt/--prefix=/ to install BIRD to a place different from <file>/usr/local</file>. | |
138 | ||
b093c328 | 139 | |
02357f96 | 140 | <sect>Running BIRD |
36032ded | 141 | |
c184d9d0 | 142 | <p>You can pass several command-line options to bird: |
d26524fa | 143 | |
c184d9d0 PM |
144 | <descrip> |
145 | <tag>-c <m/config name/</tag> | |
66701947 | 146 | use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>. |
c184d9d0 PM |
147 | |
148 | <tag>-d</tag> | |
02357f96 | 149 | enable debug messages and run bird in foreground. |
c184d9d0 | 150 | |
02357f96 | 151 | <tag>-D <m/filename of debug log/</tag> |
a4644ed6 OZ |
152 | log debugging information to given file instead of stderr. |
153 | ||
154 | <tag>-p</tag> | |
dad92c30 OZ |
155 | just parse the config file and exit. Return value is zero if the config |
156 | file is valid, nonzero if there are some errors. | |
c184d9d0 PM |
157 | |
158 | <tag>-s <m/name of communication socket/</tag> | |
dad92c30 OZ |
159 | use given filename for a socket for communications with the client, |
160 | default is <it/prefix/<file>/var/run/bird.ctl</file>. | |
0aeac9cb OZ |
161 | |
162 | <tag>-P <m/name of PID file/</tag> | |
9637c7c0 | 163 | create a PID file with given filename. |
e8b89a61 OZ |
164 | |
165 | <tag>-u <m/user/</tag> | |
166 | drop privileges and use that user ID, see the next section for details. | |
167 | ||
168 | <tag>-g <m/group/</tag> | |
169 | use that group ID, see the next section for details. | |
1cd198cf OF |
170 | |
171 | <tag>-f</tag> | |
172 | run bird in foreground. | |
6eda3f13 | 173 | |
f2ae2bad OZ |
174 | <tag>-l</tag> |
175 | look for a configuration file and a communication socket in the current | |
43fc6bb0 | 176 | working directory instead of in default system locations. However, paths |
f2ae2bad OZ |
177 | specified by options <cf/-c/, <cf/-s/ have higher priority. |
178 | ||
6eda3f13 OZ |
179 | <tag>-R</tag> |
180 | apply graceful restart recovery after start. | |
c184d9d0 | 181 | </descrip> |
d26524fa | 182 | |
02357f96 PM |
183 | <p>BIRD writes messages about its work to log files or syslog (according to config). |
184 | ||
dad92c30 | 185 | |
e8b89a61 OZ |
186 | <sect>Privileges |
187 | ||
dad92c30 OZ |
188 | <p>BIRD, as a routing daemon, uses several privileged operations (like setting |
189 | routing table and using raw sockets). Traditionally, BIRD is executed and runs | |
190 | with root privileges, which may be prone to security problems. The recommended | |
191 | way is to use a privilege restriction (options <cf/-u/, <cf/-g/). In that case | |
192 | BIRD is executed with root privileges, but it changes its user and group ID to | |
193 | an unprivileged ones, while using Linux capabilities to retain just required | |
194 | privileges (capabilities CAP_NET_*). Note that the control socket is created | |
195 | before the privileges are dropped, but the config file is read after that. The | |
196 | privilege restriction is not implemented in BSD port of BIRD. | |
197 | ||
fff7498d | 198 | <p>An unprivileged user (as an argument to <cf/-u/ options) may be the user |
dad92c30 OZ |
199 | <cf/nobody/, but it is suggested to use a new dedicated user account (like |
200 | <cf/bird/). The similar considerations apply for the group option, but there is | |
201 | one more condition -- the users in the same group can use <file/birdc/ to | |
202 | control BIRD. | |
203 | ||
204 | <p>Finally, there is a possibility to use external tools to run BIRD in an | |
205 | environment with restricted privileges. This may need some configuration, but it | |
206 | is generally easy -- BIRD needs just the standard library, privileges to read | |
207 | the config file and create the control socket and the CAP_NET_* capabilities. | |
e8b89a61 | 208 | |
6eda3f13 | 209 | |
a852c139 PM |
210 | <chapt>About routing tables |
211 | ||
dad92c30 OZ |
212 | <p>BIRD has one or more routing tables which may or may not be synchronized with |
213 | OS kernel and which may or may not be synchronized with each other (see the Pipe | |
214 | protocol). Each routing table contains a list of known routes. Each route | |
215 | consists of: | |
a852c139 PM |
216 | |
217 | <itemize> | |
dad92c30 OZ |
218 | <item>network prefix this route is for (network address and prefix |
219 | length -- the number of bits forming the network part of the | |
220 | address; also known as a netmask) | |
96264d4d PM |
221 | <item>preference of this route |
222 | <item>IP address of router which told us about this route | |
dad92c30 OZ |
223 | <item>IP address of router we should forward the packets to using this |
224 | route | |
a852c139 | 225 | <item>other attributes common to all routes |
dad92c30 OZ |
226 | <item>dynamic attributes defined by protocols which may or may not be |
227 | present (typically protocol metrics) | |
a852c139 PM |
228 | </itemize> |
229 | ||
dad92c30 OZ |
230 | Routing table maintains multiple entries for a network, but at most one entry |
231 | for one network and one protocol. The entry with the highest preference is used | |
232 | for routing (we will call such an entry the <it/selected route/). If there are | |
233 | more entries with the same preference and they are from the same protocol, the | |
234 | protocol decides (typically according to metrics). If they aren't, an internal | |
235 | ordering is used to break the tie. You can get the list of route attributes in | |
236 | the Route attributes section. | |
237 | ||
238 | <p>Each protocol is connected to a routing table through two filters which can | |
239 | accept, reject and modify the routes. An <it/export/ filter checks routes passed | |
240 | from the routing table to the protocol, an <it/import/ filter checks routes in | |
241 | the opposite direction. When the routing table gets a route from a protocol, it | |
242 | recalculates the selected route and broadcasts it to all protocols connected to | |
243 | the table. The protocols typically send the update to other routers in the | |
244 | network. Note that although most protocols are interested in receiving just | |
245 | selected routes, some protocols (e.g. the <cf/Pipe/ protocol) receive and | |
246 | process all entries in routing tables (accepted by filters). | |
247 | ||
248 | <p><label id="dsc-sorted">Usually, a routing table just chooses a selected route | |
249 | from a list of entries for one network. But if the <cf/sorted/ option is | |
250 | activated, these lists of entries are kept completely sorted (according to | |
251 | preference or some protocol-dependent metric). This is needed for some features | |
252 | of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to | |
253 | accept not just a selected route, but the first route (in the sorted list) that | |
254 | is accepted by filters), but it is incompatible with some other features (e.g. | |
255 | <cf/deterministic med/ option of BGP protocol, which activates a way of choosing | |
256 | selected route that cannot be described using comparison and ordering). Minor | |
257 | advantage is that routes are shown sorted in <cf/show route/, minor disadvantage | |
258 | is that it is slightly more computationally expensive. | |
259 | ||
48cf5e84 | 260 | |
6eda3f13 OZ |
261 | <sect>Graceful restart |
262 | ||
263 | <p>When BIRD is started after restart or crash, it repopulates routing tables in | |
264 | an uncoordinated manner, like after clean start. This may be impractical in some | |
265 | cases, because if the forwarding plane (i.e. kernel routing tables) remains | |
266 | intact, then its synchronization with BIRD would temporarily disrupt packet | |
267 | forwarding until protocols converge. Graceful restart is a mechanism that could | |
268 | help with this issue. Generally, it works by starting protocols and letting them | |
269 | repopulate routing tables while deferring route propagation until protocols | |
270 | acknowledge their convergence. Note that graceful restart behavior have to be | |
271 | configured for all relevant protocols and requires protocol-specific support | |
272 | (currently implemented for Kernel and BGP protocols), it is activated for | |
273 | particular boot by option <cf/-R/. | |
274 | ||
a852c139 | 275 | |
371adba6 | 276 | <chapt>Configuration |
af0b25d2 | 277 | |
371adba6 | 278 | <sect>Introduction |
d37f899b | 279 | |
dad92c30 OZ |
280 | <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads |
281 | <it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option | |
282 | is given). Configuration may be changed at user's request: if you modify the | |
283 | config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new | |
284 | config. Then there's the client which allows you to talk with BIRD in an | |
285 | extensive way. | |
286 | ||
287 | <p>In the config, everything on a line after <cf/#/ or inside <cf>/* */</cf> is | |
288 | a comment, whitespace characters are treated as a single space. If there's a | |
289 | variable number of options, they are grouped using the <cf/{ }/ brackets. Each | |
290 | option is terminated by a <cf/;/. Configuration is case sensitive. There are two | |
fff7498d | 291 | ways how to name symbols (like protocol names, filter names, constants etc.). You |
dad92c30 OZ |
292 | can either use a simple string starting with a letter followed by any |
293 | combination of letters and numbers (e.g. "R123", "myfilter", "bgp5") or you can | |
294 | enclose the name into apostrophes (<cf/'/) and than you can use any combination | |
295 | of numbers, letters. hyphens, dots and colons (e.g. "'1:strange-name'", | |
296 | "'-NAME-'", "'cool::name'"). | |
297 | ||
298 | <p>Here is an example of a simple config file. It enables synchronization of | |
299 | routing tables with OS kernel, scans for new network interfaces every 10 seconds | |
300 | and runs RIP on all network interfaces found. | |
d37f899b | 301 | |
a0dd1c74 | 302 | <code> |
d37f899b | 303 | protocol kernel { |
d150c637 | 304 | persist; # Don't remove routes on BIRD shutdown |
d37f899b PM |
305 | scan time 20; # Scan kernel routing table every 20 seconds |
306 | export all; # Default is export none | |
307 | } | |
308 | ||
309 | protocol device { | |
310 | scan time 10; # Scan interfaces every 10 seconds | |
311 | } | |
312 | ||
313 | protocol rip { | |
314 | export all; | |
315 | import all; | |
f434d191 | 316 | interface "*"; |
d37f899b | 317 | } |
a0dd1c74 | 318 | </code> |
d37f899b | 319 | |
326e33f5 | 320 | |
371adba6 | 321 | <sect>Global options |
af0b25d2 | 322 | |
a0dd1c74 | 323 | <p><descrip> |
523f020b | 324 | <tag>include "<m/filename/"</tag> |
4a5eb284 | 325 | This statement causes inclusion of a new file. <m/Filename/ could also |
0a505706 OZ |
326 | be a wildcard, in that case matching files are included in alphabetic |
327 | order. The maximal depth is 8. Note that this statement could be used | |
328 | anywhere in the config file, not just as a top-level option. | |
48ec367a | 329 | |
523f020b | 330 | <tag><label id="dsc-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag> |
dad92c30 OZ |
331 | Set logging of messages having the given class (either <cf/all/ or |
332 | <cf/{ error, trace }/ etc.) into selected destination (a file specified | |
333 | as a filename string, syslog with optional name argument, or the stderr | |
334 | output). Classes are: | |
1632f1fe | 335 | <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems, |
523f020b OZ |
336 | <cf/debug/ for debugging messages, |
337 | <cf/trace/ when you want to know what happens in the network, | |
338 | <cf/remote/ for messages about misbehavior of remote machines, | |
02357f96 | 339 | <cf/auth/ about authentication failures, |
dad92c30 OZ |
340 | <cf/bug/ for internal BIRD bugs. |
341 | You may specify more than one <cf/log/ line to establish logging to | |
342 | multiple destinations. Default: log everything to the system log. | |
02357f96 | 343 | |
7581b81b | 344 | <tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag> |
dad92c30 OZ |
345 | Set global defaults of protocol debugging options. See <cf/debug/ in the |
346 | following section. Default: off. | |
5a203dac PM |
347 | |
348 | <tag>debug commands <m/number/</tag> | |
dad92c30 OZ |
349 | Control logging of client connections (0 for no logging, 1 for logging |
350 | of connects and disconnects, 2 and higher for logging of all client | |
351 | commands). Default: 0. | |
249d238c | 352 | |
8bcb5fb1 OZ |
353 | <tag>debug latency <m/switch/</tag> |
354 | Activate tracking of elapsed time for internal events. Recent events | |
355 | could be examined using <cf/dump events/ command. Default: off. | |
356 | ||
357 | <tag>debug latency limit <m/time/</tag> | |
358 | If <cf/debug latency/ is enabled, this option allows to specify a limit | |
359 | for elapsed time. Events exceeding the limit are logged. Default: 1 s. | |
360 | ||
361 | <tag>watchdog warning <m/time/</tag> | |
362 | Set time limit for I/O loop cycle. If one iteration took more time to | |
363 | complete, a warning is logged. Default: 5 s. | |
364 | ||
365 | <tag>watchdog timeout <m/time/</tag> | |
366 | Set time limit for I/O loop cycle. If the limit is breached, BIRD is | |
367 | killed by abort signal. The timeout has effective granularity of | |
368 | seconds, zero means disabled. Default: disabled (0). | |
369 | ||
cf31112f | 370 | <tag>mrtdump "<m/filename/"</tag> |
dad92c30 OZ |
371 | Set MRTdump file name. This option must be specified to allow MRTdump |
372 | feature. Default: no dump file. | |
cf31112f OZ |
373 | |
374 | <tag>mrtdump protocols all|off|{ states, messages }</tag> | |
dad92c30 OZ |
375 | Set global defaults of MRTdump options. See <cf/mrtdump/ in the |
376 | following section. Default: off. | |
cf31112f | 377 | |
dad92c30 OZ |
378 | <tag>filter <m/name local variables/{ <m/commands/ }</tag> |
379 | Define a filter. You can learn more about filters in the following | |
380 | chapter. | |
326e33f5 | 381 | |
dad92c30 OZ |
382 | <tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> |
383 | Define a function. You can learn more about functions in the following chapter. | |
523f020b | 384 | |
a7f23f58 | 385 | <tag>protocol rip|ospf|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag> |
dad92c30 OZ |
386 | Define a protocol instance called <cf><m/name/</cf> (or with a name like |
387 | "rip5" generated automatically if you don't specify any | |
388 | <cf><m/name/</cf>). You can learn more about configuring protocols in | |
389 | their own chapters. When <cf>from <m/name2/</cf> expression is used, | |
390 | initial protocol options are taken from protocol or template | |
391 | <cf><m/name2/</cf> You can run more than one instance of most protocols | |
392 | (like RIP or BGP). By default, no instances are configured. | |
a7f23f58 OZ |
393 | |
394 | <tag>template rip|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag> | |
dad92c30 OZ |
395 | Define a protocol template instance called <m/name/ (or with a name like |
396 | "bgp1" generated automatically if you don't specify any <m/name/). | |
397 | Protocol templates can be used to group common options when many | |
398 | similarly configured protocol instances are to be defined. Protocol | |
399 | instances (and other templates) can use templates by using <cf/from/ | |
400 | expression and the name of the template. At the moment templates (and | |
401 | <cf/from/ expression) are not implemented for OSPF protocol. | |
249d238c | 402 | |
f4830d8c | 403 | <tag>define <m/constant/ = <m/expression/</tag> |
dad92c30 OZ |
404 | Define a constant. You can use it later in every place you could use a |
405 | value of the same type. Besides, there are some predefined numeric | |
406 | constants based on /etc/iproute2/rt_* files. A list of defined constants | |
407 | can be seen (together with other symbols) using 'show symbols' command. | |
249d238c | 408 | |
79b4e12e | 409 | <tag>router id <m/IPv4 address/</tag> |
dad92c30 OZ |
410 | Set BIRD's router ID. It's a world-wide unique identification of your |
411 | router, usually one of router's IPv4 addresses. Default: in IPv4 | |
412 | version, the lowest IP address of a non-loopback interface. In IPv6 | |
413 | version, this option is mandatory. | |
79b4e12e OZ |
414 | |
415 | <tag>router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...]</tag> | |
dad92c30 OZ |
416 | Set BIRD's router ID based on an IP address of an interface specified by |
417 | an interface pattern. The option is applicable for IPv4 version only. | |
418 | See <ref id="dsc-iface" name="interface"> section for detailed | |
d7c06285 | 419 | description of interface patterns with extended clauses. |
249d238c | 420 | |
fcf5a4f4 | 421 | <tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag> |
dad92c30 OZ |
422 | This option allows to specify address and port where BGP protocol should |
423 | listen. It is global option as listening socket is common to all BGP | |
424 | instances. Default is to listen on all addresses (0.0.0.0) and port 179. | |
425 | In IPv6 mode, option <cf/dual/ can be used to specify that BGP socket | |
426 | should accept both IPv4 and IPv6 connections (but even in that case, | |
427 | BIRD would accept IPv6 routes only). Such behavior was default in older | |
428 | versions of BIRD. | |
27579857 | 429 | |
6eda3f13 OZ |
430 | <tag>graceful restart wait <m/number/</tag> |
431 | During graceful restart recovery, BIRD waits for convergence of routing | |
432 | protocols. This option allows to specify a timeout for the recovery to | |
433 | prevent waiting indefinitely if some protocols cannot converge. Default: | |
434 | 240 seconds. | |
435 | ||
9be9a264 | 436 | <tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag> |
dad92c30 OZ |
437 | This option allows to specify a format of date/time used by BIRD. The |
438 | first argument specifies for which purpose such format is used. | |
439 | <cf/route/ is a format used in 'show route' command output, | |
440 | <cf/protocol/ is used in 'show protocols' command output, <cf/base/ is | |
441 | used for other commands and <cf/log/ is used in a log file. | |
442 | ||
443 | "<m/format1/" is a format string using <it/strftime(3)/ notation (see | |
444 | <it/man strftime/ for details). <m/limit> and "<m/format2/" allow to | |
445 | specify the second format string for times in past deeper than <m/limit/ | |
446 | seconds. There are few shorthands: <cf/iso long/ is a ISO 8601 date/time | |
447 | format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F %T"/. | |
448 | <cf/iso short/ is a variant of ISO 8601 that uses just the time format | |
449 | (hh:mm:ss) for near times (up to 20 hours in the past) and the date | |
450 | format (YYYY-MM-DD) for far times. This is a shorthand for | |
451 | <cf/"%T" 72000 "%F"/. | |
c37e7851 | 452 | |
90eb5e7a OZ |
453 | By default, BIRD uses the <cf/iso short/ format for <cf/route/ and |
454 | <cf/protocol/ times, and the <cf/iso long/ format for <cf/base/ and | |
455 | <cf/log/ times. | |
456 | ||
dad92c30 OZ |
457 | In pre-1.4.0 versions, BIRD used an short, ad-hoc format for <cf/route/ |
458 | and <cf/protocol/ times, and a <cf/iso long/ similar format (DD-MM-YYYY | |
459 | hh:mm:ss) for <cf/base/ and <cf/log/. These timeformats could be set by | |
460 | <cf/old short/ and <cf/old long/ compatibility shorthands. | |
c37e7851 | 461 | |
48cf5e84 | 462 | <tag>table <m/name/ [sorted]</tag> |
dad92c30 OZ |
463 | Create a new routing table. The default routing table is created |
464 | implicitly, other routing tables have to be added by this command. | |
465 | Option <cf/sorted/ can be used to enable sorting of routes, see | |
466 | <ref id="dsc-sorted" name="sorted table"> description for details. | |
af0b25d2 | 467 | |
48cf5e84 | 468 | <tag>roa table <m/name/ [ { roa table options ... } ]</tag> |
dad92c30 OZ |
469 | Create a new ROA (Route Origin Authorization) table. ROA tables can be |
470 | used to validate route origination of BGP routes. A ROA table contains | |
471 | ROA entries, each consist of a network prefix, a max prefix length and | |
472 | an AS number. A ROA entry specifies prefixes which could be originated | |
473 | by that AS number. ROA tables could be filled with data from RPKI (RFC | |
474 | 6480) or from public databases like Whois. ROA tables are examined by | |
475 | <cf/roa_check()/ operator in filters. | |
476 | ||
477 | Currently, there is just one option, <cf>roa <m/prefix/ max <m/num/ as | |
478 | <m/num/</cf>, which can be used to populate the ROA table with static | |
479 | ROA entries. The option may be used multiple times. Other entries can be | |
480 | added dynamically by <cf/add roa/ command. | |
af582c48 | 481 | |
f8e8fcfa OZ |
482 | <tag>eval <m/expr/</tag> |
483 | Evaluates given filter expression. It is used by us for testing of filters. | |
249d238c PM |
484 | </descrip> |
485 | ||
dad92c30 | 486 | |
371adba6 | 487 | <sect>Protocol options |
bfd71178 | 488 | |
dad92c30 OZ |
489 | <p>For each protocol instance, you can configure a bunch of options. Some of |
490 | them (those described in this section) are generic, some are specific to the | |
491 | protocol (see sections talking about the protocols). | |
7581b81b | 492 | |
dad92c30 OZ |
493 | <p>Several options use a <m/switch/ argument. It can be either <cf/on/, |
494 | <cf/yes/ or a numeric expression with a non-zero value for the option to be | |
495 | enabled or <cf/off/, <cf/no/ or a numeric expression evaluating to zero to | |
496 | disable it. An empty <m/switch/ is equivalent to <cf/on/ ("silence means | |
497 | agreement"). | |
7581b81b | 498 | |
5a203dac | 499 | <descrip> |
dad92c30 OZ |
500 | <tag>preference <m/expr/</tag> |
501 | Sets the preference of routes generated by this protocol. Default: | |
502 | protocol dependent. | |
5a203dac | 503 | |
dad92c30 OZ |
504 | <tag>disabled <m/switch/</tag> |
505 | Disables the protocol. You can change the disable/enable status from the | |
506 | command line interface without needing to touch the configuration. | |
507 | Disabled protocols are not activated. Default: protocol is enabled. | |
5a203dac PM |
508 | |
509 | <tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag> | |
510 | Set protocol debugging options. If asked, each protocol is capable of | |
511 | writing trace messages about its work to the log (with category | |
512 | <cf/trace/). You can either request printing of <cf/all/ trace messages | |
513 | or only of the types selected: <cf/states/ for protocol state changes | |
dad92c30 OZ |
514 | (protocol going up, down, starting, stopping etc.), <cf/routes/ for |
515 | routes exchanged with the routing table, <cf/filters/ for details on | |
516 | route filtering, <cf/interfaces/ for interface change events sent to the | |
517 | protocol, <cf/events/ for events internal to the protocol and <cf/packets/ | |
518 | for packets sent and received by the protocol. Default: off. | |
5a203dac | 519 | |
cf31112f | 520 | <tag>mrtdump all|off|{ states, messages }</tag> |
dad92c30 OZ |
521 | Set protocol MRTdump flags. MRTdump is a standard binary format for |
522 | logging information from routing protocols and daemons. These flags | |
523 | control what kind of information is logged from the protocol to the | |
524 | MRTdump file (which must be specified by global <cf/mrtdump/ option, see | |
525 | the previous section). Although these flags are similar to flags of | |
526 | <cf/debug/ option, their meaning is different and protocol-specific. For | |
527 | BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs | |
528 | received BGP messages. Other protocols does not support MRTdump yet. | |
cf31112f | 529 | |
cff430f3 | 530 | <tag>router id <m/IPv4 address/</tag> |
dad92c30 OZ |
531 | This option can be used to override global router id for a given |
532 | protocol. Default: uses global router id. | |
4cdd0784 | 533 | |
523f020b | 534 | <tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag> |
dad92c30 OZ |
535 | Specify a filter to be used for filtering routes coming from the |
536 | protocol to the routing table. <cf/all/ is shorthand for <cf/where true/ | |
537 | and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/. | |
bfd71178 | 538 | |
bf422073 | 539 | <tag>export <m/filter/</tag> |
dad92c30 OZ |
540 | This is similar to the <cf>import</cf> keyword, except that it works in |
541 | the direction from the routing table to the protocol. Default: <cf/none/. | |
af0b25d2 | 542 | |
6ac4f87a | 543 | <tag>import keep filtered <m/switch/</tag> |
dad92c30 OZ |
544 | Usually, if an import filter rejects a route, the route is forgotten. |
545 | When this option is active, these routes are kept in the routing table, | |
546 | but they are hidden and not propagated to other protocols. But it is | |
547 | possible to show them using <cf/show route filtered/. Note that this | |
548 | option does not work for the pipe protocol. Default: off. | |
cf98be7b | 549 | |
b0a8c7fc | 550 | <tag><label id="import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag> |
dad92c30 OZ |
551 | Specify an import route limit (a maximum number of routes imported from |
552 | the protocol) and optionally the action to be taken when the limit is | |
553 | hit. Warn action just prints warning log message. Block action discards | |
554 | new routes coming from the protocol. Restart and disable actions shut | |
555 | the protocol down like appropriate commands. Disable is the default | |
556 | action if an action is not explicitly specified. Note that limits are | |
557 | reset during protocol reconfigure, reload or restart. Default: <cf/off/. | |
b662290f | 558 | |
0bc3542a | 559 | <tag>receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag> |
dad92c30 OZ |
560 | Specify an receive route limit (a maximum number of routes received from |
561 | the protocol and remembered). It works almost identically to <cf>import | |
562 | limit</cf> option, the only difference is that if <cf/import keep | |
563 | filtered/ option is active, filtered routes are counted towards the | |
564 | limit and blocked routes are forgotten, as the main purpose of the | |
565 | receive limit is to protect routing tables from overflow. Import limit, | |
566 | on the contrary, counts accepted routes only and routes blocked by the | |
567 | limit are handled like filtered routes. Default: <cf/off/. | |
d9b77cc2 | 568 | |
0bc3542a | 569 | <tag>export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag> |
dad92c30 OZ |
570 | Specify an export route limit, works similarly to the <cf>import |
571 | limit</cf> option, but for the routes exported to the protocol. This | |
572 | option is experimental, there are some problems in details of its | |
573 | behavior -- the number of exported routes can temporarily exceed the | |
574 | limit without triggering it during protocol reload, exported routes | |
575 | counter ignores route blocking and block action also blocks route | |
576 | updates of already accepted routes -- and these details will probably | |
577 | change in the future. Default: <cf/off/. | |
ebecb6f6 | 578 | |
fd6cbe90 | 579 | <tag>description "<m/text/"</tag> |
dad92c30 OZ |
580 | This is an optional description of the protocol. It is displayed as a |
581 | part of the output of 'show route all' command. | |
62aa96ca | 582 | |
fd6cbe90 OZ |
583 | <tag>table <m/name/</tag> |
584 | Connect this protocol to a non-default routing table. | |
7581b81b PM |
585 | </descrip> |
586 | ||
a7c9f7c0 | 587 | <p>There are several options that give sense only with certain protocols: |
7581b81b PM |
588 | |
589 | <descrip> | |
f434d191 | 590 | <tag><label id="dsc-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...] [ { <m/option/ ; [...] } ]</tag> |
f434d191 OZ |
591 | Specifies a set of interfaces on which the protocol is activated with |
592 | given interface-specific options. A set of interfaces specified by one | |
dad92c30 OZ |
593 | interface option is described using an interface pattern. The interface |
594 | pattern consists of a sequence of clauses (separated by commas), each | |
d7c06285 OZ |
595 | clause is a mask specified as a shell-like pattern. Interfaces are |
596 | matched by their name. | |
dad92c30 OZ |
597 | |
598 | An interface matches the pattern if it matches any of its clauses. If | |
599 | the clause begins with <cf/-/, matching interfaces are excluded. Patterns | |
d7c06285 | 600 | are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/ |
dad92c30 OZ |
601 | means eth0 and all non-ethernets. |
602 | ||
d7c06285 OZ |
603 | Some protocols (namely OSPFv2 and Direct) support extended clauses that |
604 | may contain a mask, a prefix, or both of them. An interface matches such | |
605 | clause if its name matches the mask (if specified) and its address | |
606 | matches the prefix (if specified). Extended clauses are used when the | |
607 | protocol handles multiple addresses on an interface independently. | |
608 | ||
dad92c30 OZ |
609 | An interface option can be used more times with different interface-specific |
610 | options, in that case for given interface the first matching interface | |
611 | option is used. | |
523f020b | 612 | |
12640c14 OZ |
613 | This option is allowed in Babel, BFD, Direct, OSPF, RAdv and RIP |
614 | protocols, but in OSPF protocol it is used in the <cf/area/ subsection. | |
f434d191 OZ |
615 | |
616 | Default: none. | |
617 | ||
618 | Examples: | |
619 | ||
dad92c30 OZ |
620 | <cf>interface "*" { type broadcast; };</cf> - start the protocol on all |
621 | interfaces with <cf>type broadcast</cf> option. | |
f434d191 | 622 | |
dad92c30 OZ |
623 | <cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the |
624 | protocol on enumerated interfaces with <cf>type ptp</cf> option. | |
523f020b | 625 | |
dad92c30 OZ |
626 | <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol |
627 | on all interfaces that have address from 192.168.0.0/16, but not from | |
628 | 192.168.1.0/24. | |
f434d191 | 629 | |
dad92c30 OZ |
630 | <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol |
631 | on all interfaces that have address from 192.168.0.0/16, but not from | |
632 | 192.168.1.0/24. | |
f434d191 OZ |
633 | |
634 | <cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all | |
635 | ethernet interfaces that have address from 192.168.1.0/24. | |
636 | ||
ef4a50be | 637 | <tag><label id="dsc-prio">tx class|dscp <m/num/</tag> |
dad92c30 OZ |
638 | This option specifies the value of ToS/DS/Class field in IP headers of |
639 | the outgoing protocol packets. This may affect how the protocol packets | |
640 | are processed by the network relative to the other network traffic. With | |
641 | <cf/class/ keyword, the value (0-255) is used for the whole ToS/Class | |
642 | octet (but two bits reserved for ECN are ignored). With <cf/dscp/ | |
643 | keyword, the value (0-63) is used just for the DS field in the octet. | |
644 | Default value is 0xc0 (DSCP 0x30 - CS6). | |
ef4a50be OZ |
645 | |
646 | <tag>tx priority <m/num/</tag> | |
dad92c30 OZ |
647 | This option specifies the local packet priority. This may affect how the |
648 | protocol packets are processed in the local TX queues. This option is | |
649 | Linux specific. Default value is 7 (highest priority, privileged traffic). | |
ef4a50be | 650 | |
f434d191 | 651 | <tag><label id="dsc-pass">password "<m/password/" [ { id <m/num/; generate from <m/time/; generate to <m/time/; accept from <m/time/; accept to <m/time/; } ]</tag> |
dad92c30 OZ |
652 | Specifies a password that can be used by the protocol. Password option |
653 | can be used more times to specify more passwords. If more passwords are | |
f434d191 | 654 | specified, it is a protocol-dependent decision which one is really |
dad92c30 OZ |
655 | used. Specifying passwords does not mean that authentication is enabled, |
656 | authentication can be enabled by separate, protocol-dependent | |
f434d191 | 657 | <cf/authentication/ option. |
523f020b | 658 | |
f434d191 OZ |
659 | This option is allowed in OSPF and RIP protocols. BGP has also |
660 | <cf/password/ option, but it is slightly different and described | |
661 | separately. | |
662 | ||
663 | Default: none. | |
664 | </descrip> | |
665 | ||
666 | <p>Password option can contain section with some (not necessary all) password sub-options: | |
667 | ||
668 | <descrip> | |
669 | <tag>id <M>num</M></tag> | |
0a21c211 | 670 | ID of the password, (1-255). If it is not used, BIRD will choose ID based |
dad92c30 OZ |
671 | on an order of the password item in the interface. For example, second |
672 | password item in one interface will have default ID 2. ID is used by | |
673 | some routing protocols to identify which password was used to | |
674 | authenticate protocol packets. | |
f434d191 OZ |
675 | |
676 | <tag>generate from "<m/time/"</tag> | |
dad92c30 OZ |
677 | The start time of the usage of the password for packet signing. |
678 | The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>. | |
f434d191 OZ |
679 | |
680 | <tag>generate to "<m/time/"</tag> | |
dad92c30 | 681 | The last time of the usage of the password for packet signing. |
f434d191 OZ |
682 | |
683 | <tag>accept from "<m/time/"</tag> | |
dad92c30 | 684 | The start time of the usage of the password for packet verification. |
5a203dac | 685 | |
f434d191 | 686 | <tag>accept to "<m/time/"</tag> |
dad92c30 | 687 | The last time of the usage of the password for packet verification. |
7581b81b | 688 | </descrip> |
d37f899b | 689 | |
5a203dac | 690 | <chapt>Remote control |
36032ded | 691 | |
dad92c30 OZ |
692 | <p>You can use the command-line client <file>birdc</file> to talk with a running |
693 | BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless | |
694 | changed with the <tt/-s/ option given to both the server and the client). The | |
695 | commands can perform simple actions such as enabling/disabling of protocols, | |
696 | telling BIRD to show various information, telling it to show routing table | |
697 | filtered by filter, or asking BIRD to reconfigure. Press <tt/?/ at any time to | |
698 | get online help. Option <tt/-r/ can be used to enable a restricted mode of BIRD | |
699 | client, which allows just read-only commands (<cf/show .../). Option <tt/-v/ can | |
700 | be passed to the client, to make it dump numeric return codes along with the | |
701 | messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your | |
702 | own applications could do that, too -- the format of communication between BIRD | |
703 | and <file/birdc/ is stable (see the programmer's documentation). | |
704 | ||
705 | <p>There is also lightweight variant of BIRD client called <file/birdcl/, which | |
706 | does not support command line editing and history and has minimal dependencies. | |
707 | This is useful for running BIRD in resource constrained environments, where | |
708 | Readline library (required for regular BIRD client) is not available. | |
a5e9f3d2 OZ |
709 | |
710 | <p>Many commands have the <m/name/ of the protocol instance as an argument. | |
f434d191 OZ |
711 | This argument can be omitted if there exists only a single instance. |
712 | ||
5a203dac | 713 | <p>Here is a brief list of supported functions: |
64722c98 PM |
714 | |
715 | <descrip> | |
5a203dac | 716 | <tag>show status</tag> |
dad92c30 OZ |
717 | Show router status, that is BIRD version, uptime and time from last |
718 | reconfiguration. | |
5a203dac | 719 | |
43fc6bb0 OZ |
720 | <tag>show interfaces [summary]</tag> |
721 | Show the list of interfaces. For each interface, print its type, state, | |
722 | MTU and addresses assigned. | |
723 | ||
5a203dac | 724 | <tag>show protocols [all]</tag> |
dad92c30 OZ |
725 | Show list of protocol instances along with tables they are connected to |
726 | and protocol status, possibly giving verbose information, if <cf/all/ is | |
727 | specified. | |
64722c98 | 728 | |
f434d191 OZ |
729 | <tag>show ospf interface [<m/name/] ["<m/interface/"]</tag> |
730 | Show detailed information about OSPF interfaces. | |
731 | ||
732 | <tag>show ospf neighbors [<m/name/] ["<m/interface/"]</tag> | |
733 | Show a list of OSPF neighbors and a state of adjacency to them. | |
734 | ||
0ea8fb4a | 735 | <tag>show ospf state [all] [<m/name/]</tag> |
dad92c30 OZ |
736 | Show detailed information about OSPF areas based on a content of the |
737 | link-state database. It shows network topology, stub networks, | |
738 | aggregated networks and routers from other areas and external routes. | |
739 | The command shows information about reachable network nodes, use option | |
740 | <cf/all/ to show information about all network nodes in the link-state | |
741 | database. | |
0ea8fb4a OZ |
742 | |
743 | <tag>show ospf topology [all] [<m/name/]</tag> | |
dad92c30 OZ |
744 | Show a topology of OSPF areas based on a content of the link-state |
745 | database. It is just a stripped-down version of 'show ospf state'. | |
64722c98 | 746 | |
20ab192b | 747 | <tag>show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag> |
dad92c30 OZ |
748 | Show contents of an OSPF LSA database. Options could be used to filter |
749 | entries. | |
20ab192b | 750 | |
43fc6bb0 OZ |
751 | <tag>show rip interfaces [<m/name/] ["<m/interface/"]</tag> |
752 | Show detailed information about RIP interfaces. | |
753 | ||
754 | <tag>show rip neighbors [<m/name/] ["<m/interface/"]</tag> | |
755 | Show a list of RIP neighbors and associated state. | |
756 | ||
5a203dac | 757 | <tag>show static [<m/name/]</tag> |
f434d191 OZ |
758 | Show detailed information about static routes. |
759 | ||
12201fd8 OZ |
760 | <tag>show bfd sessions [<m/name/]</tag> |
761 | Show information about BFD sessions. | |
762 | ||
89647357 | 763 | <tag>show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag> |
dad92c30 OZ |
764 | Show the list of symbols defined in the configuration (names of |
765 | protocols, routing tables etc.). | |
5a203dac | 766 | |
7aa80901 | 767 | <tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [<m/options/]</tag> |
dad92c30 OZ |
768 | Show contents of a routing table (by default of the main one or the |
769 | table attached to a respective protocol), that is routes, their metrics | |
770 | and (in case the <cf/all/ switch is given) all their attributes. | |
5a203dac PM |
771 | |
772 | <p>You can specify a <m/prefix/ if you want to print routes for a | |
773 | specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get | |
774 | the entry which will be used for forwarding of packets to the given | |
775 | destination. By default, all routes for each network are printed with | |
776 | the selected one at the top, unless <cf/primary/ is given in which case | |
777 | only the selected route is shown. | |
778 | ||
779 | <p>You can also ask for printing only routes processed and accepted by | |
780 | a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ } | |
781 | </cf> or matching a given condition (<cf>where <m/condition/</cf>). | |
7aa80901 OZ |
782 | |
783 | The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for | |
784 | printing of routes that are exported to the specified protocol. | |
785 | With <cf/preexport/, the export filter of the protocol is skipped. | |
786 | With <cf/noexport/, routes rejected by the export filter are printed | |
787 | instead. Note that routes not exported to the protocol for other reasons | |
788 | (e.g. secondary routes or routes imported from that protocol) are not | |
789 | printed even with <cf/noexport/. | |
5a203dac | 790 | |
4d176e14 OF |
791 | <p>You can also select just routes added by a specific protocol. |
792 | <cf>protocol <m/p/</cf>. | |
793 | ||
dad92c30 OZ |
794 | <p>If BIRD is configured to keep filtered routes (see <cf/import keep |
795 | filtered/ option), you can show them instead of routes by using | |
796 | <cf/filtered/ switch. | |
cf98be7b | 797 | |
5a203dac PM |
798 | <p>The <cf/stats/ switch requests showing of route statistics (the |
799 | number of networks, number of routes before and after filtering). If | |
800 | you use <cf/count/ instead, only the statistics will be printed. | |
801 | ||
c47d037e | 802 | <tag>show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag> |
dad92c30 OZ |
803 | Show contents of a ROA table (by default of the first one). You can |
804 | specify a <m/prefix/ to print ROA entries for a specific network. If you | |
805 | use <cf>for <m/prefix/</cf>, you'll get all entries relevant for route | |
806 | validation of the network prefix; i.e., ROA entries whose prefixes cover | |
807 | the network prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA | |
808 | entries covered by the network prefix. You could also use <cf/as/ option | |
af582c48 OZ |
809 | to show just entries for given AS. |
810 | ||
811 | <tag>add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag> | |
dad92c30 OZ |
812 | Add a new ROA entry to a ROA table. Such entry is called <it/dynamic/ |
813 | compared to <it/static/ entries specified in the config file. These | |
814 | dynamic entries survive reconfiguration. | |
af582c48 OZ |
815 | |
816 | <tag>delete roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag> | |
dad92c30 OZ |
817 | Delete the specified ROA entry from a ROA table. Only dynamic ROA |
818 | entries (i.e., the ones added by <cf/add roa/ command) can be deleted. | |
af582c48 OZ |
819 | |
820 | <tag>flush roa [table <m/t/>]</tag> | |
821 | Remove all dynamic ROA entries from a ROA table. | |
822 | ||
a92cf57d | 823 | <tag>configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag> |
dad92c30 OZ |
824 | Reload configuration from a given file. BIRD will smoothly switch itself |
825 | to the new configuration, protocols are reconfigured if possible, | |
826 | restarted otherwise. Changes in filters usually lead to restart of | |
827 | affected protocols. | |
828 | ||
829 | If <cf/soft/ option is used, changes in filters does not cause BIRD to | |
830 | restart affected protocols, therefore already accepted routes (according | |
831 | to old filters) would be still propagated, but new routes would be | |
832 | processed according to the new filters. | |
833 | ||
834 | If <cf/timeout/ option is used, config timer is activated. The new | |
835 | configuration could be either confirmed using <cf/configure confirm/ | |
836 | command, or it will be reverted to the old one when the config timer | |
837 | expires. This is useful for cases when reconfiguration breaks current | |
fff7498d | 838 | routing and a router becomes inaccessible for an administrator. The |
dad92c30 OZ |
839 | config timeout expiration is equivalent to <cf/configure undo/ |
840 | command. The timeout duration could be specified, default is 300 s. | |
a92cf57d OZ |
841 | |
842 | <tag>configure confirm</tag> | |
843 | Deactivate the config undo timer and therefore confirm the current | |
844 | configuration. | |
845 | ||
846 | <tag>configure undo</tag> | |
dad92c30 OZ |
847 | Undo the last configuration change and smoothly switch back to the |
848 | previous (stored) configuration. If the last configuration change was | |
849 | soft, the undo change is also soft. There is only one level of undo, but | |
850 | in some specific cases when several reconfiguration requests are given | |
851 | immediately in a row and the intermediate ones are skipped then the undo | |
852 | also skips them back. | |
a92cf57d OZ |
853 | |
854 | <tag>configure check ["<m/config file/"]</tag> | |
dad92c30 OZ |
855 | Read and parse given config file, but do not use it. useful for checking |
856 | syntactic and some semantic validity of an config file. | |
a92cf57d | 857 | |
bf47fe4b | 858 | <tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag> |
dad92c30 OZ |
859 | Enable, disable or restart a given protocol instance, instances matching |
860 | the <cf><m/pattern/</cf> or <cf/all/ instances. | |
bf47fe4b | 861 | |
8a7fb885 | 862 | <tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag> |
dad92c30 OZ |
863 | Reload a given protocol instance, that means re-import routes from the |
864 | protocol instance and re-export preferred routes to the instance. If | |
865 | <cf/in/ or <cf/out/ options are used, the command is restricted to one | |
866 | direction (re-import or re-export). | |
867 | ||
868 | This command is useful if appropriate filters have changed but the | |
869 | protocol instance was not restarted (or reloaded), therefore it still | |
870 | propagates the old set of routes. For example when <cf/configure soft/ | |
871 | command was used to change filters. | |
872 | ||
873 | Re-export always succeeds, but re-import is protocol-dependent and might | |
874 | fail (for example, if BGP neighbor does not support route-refresh | |
875 | extension). In that case, re-export is also skipped. Note that for the | |
876 | pipe protocol, both directions are always reloaded together (<cf/in/ or | |
877 | <cf/out/ options are ignored in that case). | |
8a7fb885 | 878 | |
5a203dac PM |
879 | <tag/down/ |
880 | Shut BIRD down. | |
64722c98 | 881 | |
a4601845 | 882 | <tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag> |
64722c98 | 883 | Control protocol debugging. |
508d9360 OZ |
884 | |
885 | <tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag> | |
886 | Dump contents of internal data structures to the debugging output. | |
887 | ||
888 | <tag>echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag> | |
889 | Control echoing of log messages to the command-line output. | |
890 | See <ref id="dsc-log" name="log option"> for a list of log classes. | |
891 | ||
892 | <tag>eval <m/expr/</tag> | |
893 | Evaluate given expression. | |
64722c98 | 894 | </descrip> |
36032ded | 895 | |
dad92c30 | 896 | |
371adba6 | 897 | <chapt>Filters |
d37f899b | 898 | |
371adba6 | 899 | <sect>Introduction |
d37f899b | 900 | |
dad92c30 OZ |
901 | <p>BIRD contains a simple programming language. (No, it can't yet read mail :-). |
902 | There are two objects in this language: filters and functions. Filters are | |
903 | interpreted by BIRD core when a route is being passed between protocols and | |
904 | routing tables. The filter language contains control structures such as if's and | |
905 | switches, but it allows no loops. An example of a filter using many features can | |
906 | be found in <file>filter/test.conf</file>. | |
d37f899b | 907 | |
dad92c30 OZ |
908 | <p>Filter gets the route, looks at its attributes and modifies some of them if |
909 | it wishes. At the end, it decides whether to pass the changed route through | |
910 | (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks like | |
911 | this: | |
d37f899b | 912 | |
a0dd1c74 | 913 | <code> |
d37f899b PM |
914 | filter not_too_far |
915 | int var; | |
916 | { | |
917 | if defined( rip_metric ) then | |
918 | var = rip_metric; | |
919 | else { | |
920 | var = 1; | |
921 | rip_metric = 1; | |
922 | } | |
923 | if rip_metric > 10 then | |
924 | reject "RIP metric is too big"; | |
925 | else | |
926 | accept "ok"; | |
927 | } | |
a0dd1c74 | 928 | </code> |
d37f899b | 929 | |
dad92c30 OZ |
930 | <p>As you can see, a filter has a header, a list of local variables, and a body. |
931 | The header consists of the <cf/filter/ keyword followed by a (unique) name of | |
932 | filter. The list of local variables consists of <cf><M>type name</M>;</cf> | |
933 | pairs where each pair defines one local variable. The body consists of <cf> | |
934 | { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You | |
935 | can group several statements to a single compound statement by using braces | |
936 | (<cf>{ <M>statements</M> }</cf>) which is useful if you want to make a bigger | |
937 | block of code conditional. | |
1632f1fe | 938 | |
dad92c30 OZ |
939 | <p>BIRD supports functions, so that you don't have to repeat the same blocks of |
940 | code over and over. Functions can have zero or more parameters and they can have | |
941 | local variables. Recursion is not allowed. Function definitions look like this: | |
0e5373fd PM |
942 | |
943 | <code> | |
944 | function name () | |
945 | int local_variable; | |
946 | { | |
947 | local_variable = 5; | |
948 | } | |
949 | ||
950 | function with_parameters (int parameter) | |
951 | { | |
952 | print parameter; | |
953 | } | |
954 | </code> | |
955 | ||
dad92c30 OZ |
956 | <p>Unlike in C, variables are declared after the <cf/function/ line, but before |
957 | the first <cf/{/. You can't declare variables in nested blocks. Functions are | |
958 | called like in C: <cf>name(); with_parameters(5);</cf>. Function may return | |
959 | values using the <cf>return <m/[expr]/</cf> command. Returning a value exits | |
960 | from current function (this is similar to C). | |
0e5373fd | 961 | |
dad92c30 OZ |
962 | <p>Filters are declared in a way similar to functions except they can't have |
963 | explicit parameters. They get a route table entry as an implicit parameter, it | |
964 | is also passed automatically to any functions called. The filter must terminate | |
965 | with either <cf/accept/ or <cf/reject/ statement. If there's a runtime error in | |
966 | filter, the route is rejected. | |
0e5373fd | 967 | |
dad92c30 OZ |
968 | <p>A nice trick to debug filters is to use <cf>show route filter <m/name/</cf> |
969 | from the command line client. An example session might look like: | |
c184d9d0 PM |
970 | |
971 | <code> | |
972 | pavel@bug:~/bird$ ./birdc -s bird.ctl | |
973 | BIRD 0.0.0 ready. | |
c184d9d0 PM |
974 | bird> show route |
975 | 10.0.0.0/8 dev eth0 [direct1 23:21] (240) | |
976 | 195.113.30.2/32 dev tunl1 [direct1 23:21] (240) | |
977 | 127.0.0.0/8 dev lo [direct1 23:21] (240) | |
978 | bird> show route ? | |
1632f1fe | 979 | show route [<prefix>] [table <t>] [filter <f>] [all] [primary]... |
66701947 | 980 | bird> show route filter { if 127.0.0.5 ˜ net then accept; } |
c184d9d0 PM |
981 | 127.0.0.0/8 dev lo [direct1 23:21] (240) |
982 | bird> | |
983 | </code> | |
984 | ||
dad92c30 | 985 | |
371adba6 | 986 | <sect>Data types |
d37f899b | 987 | |
dad92c30 OZ |
988 | <p>Each variable and each value has certain type. Booleans, integers and enums |
989 | are incompatible with each other (that is to prevent you from shooting in the | |
990 | foot). | |
d37f899b PM |
991 | |
992 | <descrip> | |
dad92c30 OZ |
993 | <tag/bool/ |
994 | This is a boolean type, it can have only two values, <cf/true/ and | |
995 | <cf/false/. Boolean is the only type you can use in <cf/if/ statements. | |
996 | ||
997 | <tag/int/ | |
998 | This is a general integer type. It is an unsigned 32bit type; i.e., you | |
999 | can expect it to store values from 0 to 4294967295. Overflows are not | |
1000 | checked. You can use <cf/0x1234/ syntax to write hexadecimal values. | |
1001 | ||
1002 | <tag/pair/ | |
1003 | This is a pair of two short integers. Each component can have values | |
1004 | from 0 to 65535. Literals of this type are written as <cf/(1234,5678)/. | |
1005 | The same syntax can also be used to construct a pair from two arbitrary | |
1006 | integer expressions (for example <cf/(1+2,a)/). | |
1007 | ||
1008 | <tag/quad/ | |
1009 | This is a dotted quad of numbers used to represent router IDs (and | |
1010 | others). Each component can have a value from 0 to 255. Literals of | |
1011 | this type are written like IPv4 addresses. | |
1012 | ||
1013 | <tag/string/ | |
1014 | This is a string of characters. There are no ways to modify strings in | |
1015 | filters. You can pass them between functions, assign them to variables | |
1016 | of type <cf/string/, print such variables, use standard string | |
1017 | comparison operations (e.g. <cf/=, !=, <, >, <=, >=/), but | |
1018 | you can't concatenate two strings. String literals are written as | |
fff7498d | 1019 | <cf/"This is a string constant"/. Additionally matching <cf/˜/ |
dad92c30 OZ |
1020 | operator could be used to match a string value against a shell pattern |
1021 | (represented also as a string). | |
1022 | ||
1023 | <tag/ip/ | |
1024 | This type can hold a single IP address. Depending on the compile-time | |
1025 | configuration of BIRD you are using, it is either an IPv4 or IPv6 | |
1026 | address. IP addresses are written in the standard notation | |
1027 | (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator | |
1028 | <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out all but | |
1029 | first <cf><M>num</M></cf> bits from the IP address. So | |
1030 | <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. | |
1031 | ||
1032 | <tag/prefix/ | |
1033 | This type can hold a network prefix consisting of IP address and prefix | |
1034 | length. Prefix literals are written as <cf><m/ipaddress//<m/pxlen/</cf>, | |
1035 | or <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special | |
1036 | operators on prefixes: <cf/.ip/ which extracts the IP address from the | |
1037 | pair, and <cf/.len/, which separates prefix length from the pair. | |
90dc0f08 | 1038 | So <cf>1.2.0.0/16.len = 16</cf> is true. |
dad92c30 OZ |
1039 | |
1040 | <tag/ec/ | |
dad92c30 OZ |
1041 | This is a specialized type used to represent BGP extended community |
1042 | values. It is essentially a 64bit value, literals of this type are | |
1043 | usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>, where | |
1044 | <cf/kind/ is a kind of extended community (e.g. <cf/rt/ / <cf/ro/ for a | |
1045 | route target / route origin communities), the format and possible values | |
1046 | of <cf/key/ and <cf/value/ are usually integers, but it depends on the | |
1047 | used kind. Similarly to pairs, ECs can be constructed using expressions | |
1048 | for <cf/key/ and <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where | |
1049 | <cf/myas/ is an integer variable). | |
dcde7ae5 | 1050 | |
dad92c30 OZ |
1051 | <tag/int|pair|quad|ip|prefix|ec|enum set/ |
1052 | Filters recognize four types of sets. Sets are similar to strings: you | |
1053 | can pass them around but you can't modify them. Literals of type <cf>int | |
1054 | set</cf> look like <cf> [ 1, 2, 5..7 ]</cf>. As you can see, both simple | |
1055 | values and ranges are permitted in sets. | |
1056 | ||
1057 | For pair sets, expressions like <cf/(123,*)/ can be used to denote | |
1058 | ranges (in that case <cf/(123,0)..(123,65535)/). You can also use | |
1059 | <cf/(123,5..100)/ for range <cf/(123,5)..(123,100)/. You can also use | |
1060 | <cf/*/ and <cf/a..b/ expressions in the first part of a pair, note that | |
1061 | such expressions are translated to a set of intervals, which may be | |
1062 | memory intensive. E.g. <cf/(*,4..20)/ is translated to <cf/(0,4..20), | |
1063 | (1,4..20), (2,4..20), ... (65535, 4..20)/. | |
1064 | ||
1065 | EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123, | |
1066 | 10..20)/ or <cf/(ro, 123, *)/. Expressions requiring the translation | |
1067 | (like <cf/(rt, *, 3)/) are not allowed (as they usually have 4B range | |
1068 | for ASNs). | |
1069 | ||
1070 | You can also use expressions for int, pair and EC set values. However it | |
1071 | must be possible to evaluate these expressions before daemon boots. So | |
1072 | you can use only constants inside them. E.g. | |
1073 | ||
946dc15c OF |
1074 | <code> |
1075 | define one=1; | |
8815d846 | 1076 | define myas=64500; |
946dc15c OF |
1077 | int set odds; |
1078 | pair set ps; | |
8815d846 | 1079 | ec set es; |
946dc15c | 1080 | |
8815d846 | 1081 | odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ]; |
b54ad333 | 1082 | ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ]; |
8815d846 | 1083 | es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ]; |
946dc15c | 1084 | </code> |
b1a597e0 | 1085 | |
dad92c30 OZ |
1086 | Sets of prefixes are special: their literals does not allow ranges, but |
1087 | allows prefix patterns that are written | |
1088 | as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>. | |
1089 | Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix | |
1090 | pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if the | |
1091 | first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are | |
1092 | identical and <cf>len1 <= ip1 <= len2</cf>. A valid prefix pattern | |
1093 | has to satisfy <cf>low <= high</cf>, but <cf/pxlen/ is not | |
1094 | constrained by <cf/low/ or <cf/high/. Obviously, a prefix matches a | |
1095 | prefix set literal if it matches any prefix pattern in the prefix set | |
1096 | literal. | |
1097 | ||
1098 | There are also two shorthands for prefix patterns: <cf><m/address//<m/len/+</cf> | |
1099 | is a shorthand for <cf><m/address//<m/len/{<m/len/,<m/maxlen/}</cf> | |
1100 | (where <cf><m/maxlen/</cf> is 32 for IPv4 and 128 for IPv6), that means | |
1101 | network prefix <cf><m/address//<m/len/</cf> and all its subnets. | |
1102 | <cf><m/address//<m/len/-</cf> is a shorthand for | |
1103 | <cf><m/address//<m/len/{0,<m/len/}</cf>, that means network prefix | |
1104 | <cf><m/address//<m/len/</cf> and all its supernets (network prefixes | |
1105 | that contain it). | |
1106 | ||
1107 | 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} | |
1108 | ]</cf> matches prefix <cf>1.0.0.0/8</cf>, all subprefixes of | |
1109 | <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes | |
1110 | <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf> | |
1111 | matches all prefixes (regardless of IP address) whose prefix length is | |
1112 | 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP | |
1113 | address <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 ˜ [ 1.0.0.0/8{15,17} ]</cf> | |
1114 | is true, but <cf>1.0.0.0/16 ˜ [ 1.0.0.0/8- ]</cf> is false. | |
1115 | ||
1116 | Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed | |
523f020b | 1117 | in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as |
dad92c30 OZ |
1118 | <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as |
1119 | <cf>192.168.0.0/16{24,32}</cf>. | |
d37f899b PM |
1120 | |
1121 | <tag/enum/ | |
dad92c30 OZ |
1122 | Enumeration types are fixed sets of possibilities. You can't define your |
1123 | own variables of such type, but some route attributes are of enumeration | |
1124 | type. Enumeration types are incompatible with each other. | |
0e5373fd PM |
1125 | |
1126 | <tag/bgppath/ | |
dad92c30 OZ |
1127 | BGP path is a list of autonomous system numbers. You can't write |
1128 | literals of this type. There are several special operators on bgppaths: | |
4cdd0784 | 1129 | |
dad92c30 | 1130 | <cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/. |
4cdd0784 | 1131 | |
dad92c30 | 1132 | <cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/. |
4cdd0784 | 1133 | |
9c9cc35c OZ |
1134 | <cf><m/P/.last_nonaggregated</cf> returns the last ASN in the non-aggregated part of the path <m/P/. |
1135 | ||
dad92c30 OZ |
1136 | Both <cf/first/ and <cf/last/ return zero if there is no appropriate |
1137 | ASN, for example if the path contains an AS set element as the first (or | |
9c9cc35c OZ |
1138 | the last) part. If the path ends with an AS set, <cf/last_nonaggregated/ |
1139 | may be used to get last ASN before any AS set. | |
4cdd0784 | 1140 | |
dad92c30 | 1141 | <cf><m/P/.len</cf> returns the length of path <m/P/. |
4cdd0784 | 1142 | |
dad92c30 OZ |
1143 | <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and |
1144 | returns the result. | |
bff9ce51 | 1145 | |
dad92c30 OZ |
1146 | <cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN <m/A/ from |
1147 | from path <m/P/ and returns the result. <m/A/ may also be an integer | |
1148 | set, in that case the operator deletes all ASNs from path <m/P/ that are | |
1149 | also members of set <m/A/. | |
bff9ce51 | 1150 | |
dad92c30 OZ |
1151 | <cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path <m/P/ that are |
1152 | not members of integer set <m/A/. I.e., <cf/filter/ do the same as | |
1153 | <cf/delete/ with inverted set <m/A/. | |
bff9ce51 | 1154 | |
dad92c30 OZ |
1155 | Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to |
1156 | <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute | |
1157 | (for example <cf/bgp_path/). Similarly for <cf/delete/ and <cf/filter/. | |
4a5bb2bf | 1158 | |
5a203dac | 1159 | <tag/bgpmask/ |
dad92c30 OZ |
1160 | BGP masks are patterns used for BGP path matching (using <cf>path |
1161 | ˜ [= 2 3 5 * =]</cf> syntax). The masks resemble wildcard patterns | |
1162 | as used by UNIX shells. Autonomous system numbers match themselves, | |
1163 | <cf/*/ matches any (even empty) sequence of arbitrary AS numbers and | |
523f020b | 1164 | <cf/?/ matches one arbitrary AS number. For example, if <cf>bgp_path</cf> |
dad92c30 OZ |
1165 | is 4 3 2 1, then: <tt>bgp_path ˜ [= * 4 3 * =]</tt> is true, |
1166 | but <tt>bgp_path ˜ [= * 4 5 * =]</tt> is false. BGP mask | |
1167 | expressions can also contain integer expressions enclosed in parenthesis | |
a0fe1944 OF |
1168 | and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. You can |
1169 | also use ranges, for example <tt>[= * 3..5 2 100..200 * =]</tt>. | |
1170 | There is also old (deprecated) syntax that uses / .. / instead of [= .. =] | |
1171 | and ? instead of *. | |
4cdd0784 | 1172 | |
126683fe | 1173 | <tag/clist/ |
dad92c30 OZ |
1174 | Clist is similar to a set, except that unlike other sets, it can be |
1175 | modified. The type is used for community list (a set of pairs) and for | |
1176 | cluster list (a set of quads). There exist no literals of this type. | |
1177 | There are three special operators on clists: | |
1178 | ||
1179 | <cf><m/C/.len</cf> returns the length of clist <m/C/. | |
1180 | ||
1181 | <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and | |
1182 | returns the result. If item <m/P/ is already in clist <m/C/, it does | |
1183 | nothing. <m/P/ may also be a clist, in that case all its members are | |
1184 | added; i.e., it works as clist union. | |
1185 | ||
1186 | <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad) <m/P/ from clist | |
1187 | <m/C/ and returns the result. If clist <m/C/ does not contain item | |
1188 | <m/P/, it does nothing. <m/P/ may also be a pair (or quad) set, in that | |
1189 | case the operator deletes all items from clist <m/C/ that are also | |
1190 | members of set <m/P/. Moreover, <m/P/ may also be a clist, which works | |
1191 | analogously; i.e., it works as clist difference. | |
1192 | ||
1193 | <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist <m/C/ that are | |
1194 | not members of pair (or quad) set <m/P/. I.e., <cf/filter/ do the same | |
1195 | as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which | |
1196 | works analogously; i.e., it works as clist intersection. | |
1197 | ||
1198 | Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to | |
1199 | <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute (for | |
1200 | example <cf/bgp_community/). Similarly for <cf/delete/ and <cf/filter/. | |
8815d846 OZ |
1201 | |
1202 | <tag/eclist/ | |
dad92c30 OZ |
1203 | Eclist is a data type used for BGP extended community lists. Eclists |
1204 | are very similar to clists, but they are sets of ECs instead of pairs. | |
1205 | The same operations (like <cf/add/, <cf/delete/, or <cf/˜/ | |
1206 | membership operator) can be used to modify or test eclists, with ECs | |
1207 | instead of pairs as arguments. | |
d37f899b PM |
1208 | </descrip> |
1209 | ||
dad92c30 | 1210 | |
a7c9f7c0 | 1211 | <sect>Operators |
d37f899b | 1212 | |
dad92c30 OZ |
1213 | <p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, |
1214 | parentheses <cf/(a*(b+c))/, comparison <cf/(a=b, a!=b, a<b, a>=b)/. | |
1215 | Logical operations include unary not (<cf/!/), and (<cf/&&/) and or | |
1216 | (<cf/||/). Special operators include <cf/˜/ for "is element | |
1217 | of a set" operation - it can be used on element and set of elements of the same | |
1218 | type (returning true if element is contained in the given set), or on two | |
1219 | strings (returning true if first string matches a shell-like pattern stored in | |
1220 | second string) or on IP and prefix (returning true if IP is within the range | |
1221 | defined by that prefix), or on prefix and prefix (returning true if first prefix | |
1222 | is more specific than second one) or on bgppath and bgpmask (returning true if | |
1223 | the path matches the mask) or on number and bgppath (returning true if the | |
1224 | number is in the path) or on bgppath and int (number) set (returning true if any | |
1225 | ASN from the path is in the set) or on pair/quad and clist (returning true if | |
1226 | the pair/quad is element of the clist) or on clist and pair/quad set (returning | |
1227 | true if there is an element of the clist that is also a member of the pair/quad | |
1228 | set). | |
1229 | ||
1230 | <p>There is one operator related to ROA infrastructure - <cf/roa_check()/. It | |
1231 | examines a ROA table and does RFC 6483 route origin validation for a given | |
1232 | network prefix. The basic usage is <cf>roa_check(<m/table/)</cf>, which checks | |
1233 | current route (which should be from BGP to have AS_PATH argument) in the | |
1234 | specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA, | |
1235 | ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant | |
af582c48 | 1236 | ROAs but none of them match. There is also an extended variant |
dad92c30 OZ |
1237 | <cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to specify a |
1238 | prefix and an ASN as arguments. | |
af582c48 | 1239 | |
d37f899b | 1240 | |
371adba6 | 1241 | <sect>Control structures |
d37f899b | 1242 | |
523f020b | 1243 | <p>Filters support two control structures: conditions and case switches. |
a7c9f7c0 | 1244 | |
dad92c30 OZ |
1245 | <p>Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/command1/; |
1246 | else <m/command2/;</cf> and you can use <cf>{ <m/command_1/; <m/command_2/; | |
1247 | <M>...</M> }</cf> instead of either command. The <cf>else</cf> clause may be | |
1248 | omitted. If the <cf><m>boolean expression</m></cf> is true, <m/command1/ is | |
1249 | executed, otherwise <m/command2/ is executed. | |
1250 | ||
1251 | <p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case | |
1252 | <m/expr/ { else: | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ | |
1253 | ... ] }</cf>. The expression after <cf>case</cf> can be of any type which can be | |
1254 | on the left side of the ˜ operator and anything that could be a member of | |
1255 | a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ | |
1256 | grouping. If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements | |
1257 | between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches | |
1258 | neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed. | |
d37f899b | 1259 | |
a7c9f7c0 | 1260 | <p>Here is example that uses <cf/if/ and <cf/case/ structures: |
af0b25d2 PM |
1261 | |
1262 | <code> | |
1263 | case arg1 { | |
1264 | 2: print "two"; print "I can do more commands without {}"; | |
1265 | 3 .. 5: print "three to five"; | |
1266 | else: print "something else"; | |
a7c9f7c0 | 1267 | } |
af0b25d2 | 1268 | |
523f020b OZ |
1269 | if 1234 = i then printn "."; else { |
1270 | print "not 1234"; | |
1271 | print "You need {} around multiple commands"; | |
8798c811 | 1272 | } |
af0b25d2 PM |
1273 | </code> |
1274 | ||
dad92c30 | 1275 | |
371adba6 | 1276 | <sect>Route attributes |
0e5373fd | 1277 | |
dad92c30 OZ |
1278 | <p>A filter is implicitly passed a route, and it can access its attributes just |
1279 | like it accesses variables. Attempts to access undefined attribute result in a | |
1280 | runtime error; you can check if an attribute is defined by using the | |
1281 | <cf>defined( <m>attribute</m> )</cf> operator. One notable exception to this | |
1282 | rule are attributes of clist type, where undefined value is regarded as empty | |
1283 | clist for most purposes. | |
a7c9f7c0 | 1284 | |
36032ded | 1285 | <descrip> |
cd4fecb6 | 1286 | <tag><m/prefix/ net</tag> |
dad92c30 OZ |
1287 | Network the route is talking about. Read-only. (See the chapter about |
1288 | routing tables.) | |
a7c9f7c0 PM |
1289 | |
1290 | <tag><m/enum/ scope</tag> | |
dad92c30 OZ |
1291 | The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes |
1292 | local to this host, <cf/SCOPE_LINK/ for those specific for a physical | |
1293 | link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private routes and | |
1294 | <cf/SCOPE_UNIVERSE/ for globally visible routes. This attribute is not | |
1295 | interpreted by BIRD and can be used to mark routes in filters. The | |
1296 | default value for new routes is <cf/SCOPE_UNIVERSE/. | |
0e5373fd | 1297 | |
cd4fecb6 | 1298 | <tag><m/int/ preference</tag> |
dad92c30 OZ |
1299 | Preference of the route. Valid values are 0-65535. (See the chapter |
1300 | about routing tables.) | |
c184d9d0 | 1301 | |
cd4fecb6 | 1302 | <tag><m/ip/ from</tag> |
00192d5a | 1303 | The router which the route has originated from. |
523f020b | 1304 | |
cd4fecb6 | 1305 | <tag><m/ip/ gw</tag> |
a7c9f7c0 | 1306 | Next hop packets routed using this route should be forwarded to. |
0e5373fd | 1307 | |
e29fa06e | 1308 | <tag><m/string/ proto</tag> |
dad92c30 OZ |
1309 | The name of the protocol which the route has been imported from. |
1310 | Read-only. | |
e29fa06e | 1311 | |
cd4fecb6 | 1312 | <tag><m/enum/ source</tag> |
dad92c30 OZ |
1313 | what protocol has told me about this route. Possible values: |
1314 | <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/, | |
1315 | <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/, | |
1316 | <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/, | |
12640c14 | 1317 | <cf/RTS_PIPE/, <cf/RTS_BABEL/. |
c184d9d0 | 1318 | |
cd4fecb6 | 1319 | <tag><m/enum/ cast</tag> |
ff2857b0 | 1320 | Route type (Currently <cf/RTC_UNICAST/ for normal routes, |
dad92c30 OZ |
1321 | <cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will be used in |
1322 | the future for broadcast, multicast and anycast routes). Read-only. | |
c184d9d0 | 1323 | |
cd4fecb6 | 1324 | <tag><m/enum/ dest</tag> |
182a7895 OZ |
1325 | Type of destination the packets should be sent to |
1326 | (<cf/RTD_ROUTER/ for forwarding to a neighboring router, | |
1327 | <cf/RTD_DEVICE/ for routing to a directly-connected network, | |
1328 | <cf/RTD_MULTIPATH/ for multipath destinations, | |
1329 | <cf/RTD_BLACKHOLE/ for packets to be silently discarded, | |
dad92c30 OZ |
1330 | <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be |
1331 | returned with ICMP host unreachable / ICMP administratively prohibited | |
1332 | messages). Can be changed, but only to <cf/RTD_BLACKHOLE/, | |
1333 | <cf/RTD_UNREACHABLE/ or <cf/RTD_PROHIBIT/. | |
b74f45f8 | 1334 | |
a5fc5958 | 1335 | <tag><m/string/ ifname</tag> |
dad92c30 OZ |
1336 | Name of the outgoing interface. Sink routes (like blackhole, unreachable |
1337 | or prohibit) and multipath routes have no interface associated with | |
1338 | them, so <cf/ifname/ returns an empty string for such routes. Read-only. | |
a5fc5958 OZ |
1339 | |
1340 | <tag><m/int/ ifindex</tag> | |
dad92c30 OZ |
1341 | Index of the outgoing interface. System wide index of the interface. May |
1342 | be used for interface matching, however indexes might change on interface | |
1343 | creation/removal. Zero is returned for routes with undefined outgoing | |
a5fc5958 OZ |
1344 | interfaces. Read-only. |
1345 | ||
b74f45f8 | 1346 | <tag><m/int/ igp_metric</tag> |
dad92c30 OZ |
1347 | The optional attribute that can be used to specify a distance to the |
1348 | network for routes that do not have a native protocol metric attribute | |
1349 | (like <cf/ospf_metric1/ for OSPF routes). It is used mainly by BGP to | |
1350 | compare internal distances to boundary routers (see below). It is also | |
1351 | used when the route is exported to OSPF as a default value for OSPF type | |
1352 | 1 metric. | |
ba1dda49 | 1353 | </descrip> |
0e5373fd | 1354 | |
dad92c30 OZ |
1355 | <p>There also exist some protocol-specific attributes which are described in the |
1356 | corresponding protocol sections. | |
1357 | ||
0e5373fd | 1358 | |
1632f1fe | 1359 | <sect>Other statements |
69477cad | 1360 | |
a7c9f7c0 | 1361 | <p>The following statements are available: |
69477cad PM |
1362 | |
1363 | <descrip> | |
dad92c30 OZ |
1364 | <tag><m/variable/ = <m/expr/</tag> |
1365 | Set variable to a given value. | |
326e33f5 | 1366 | |
dad92c30 OZ |
1367 | <tag>accept|reject [ <m/expr/ ]</tag> |
1368 | Accept or reject the route, possibly printing <cf><m>expr</m></cf>. | |
326e33f5 | 1369 | |
dad92c30 OZ |
1370 | <tag>return <m/expr/</tag> |
1371 | Return <cf><m>expr</m></cf> from the current function, the function ends | |
1372 | at this point. | |
326e33f5 | 1373 | |
a7c9f7c0 | 1374 | <tag>print|printn <m/expr/ [<m/, expr.../]</tag> |
dad92c30 OZ |
1375 | Prints given expressions; useful mainly while debugging filters. The |
1376 | <cf/printn/ variant does not terminate the line. | |
69477cad PM |
1377 | |
1378 | <tag>quitbird</tag> | |
1632f1fe | 1379 | Terminates BIRD. Useful when debugging the filter interpreter. |
69477cad PM |
1380 | </descrip> |
1381 | ||
dad92c30 | 1382 | |
371adba6 | 1383 | <chapt>Protocols |
d37f899b | 1384 | |
937e75d8 OZ |
1385 | <sect>Babel |
1386 | ||
1387 | <sect1>Introduction | |
1388 | ||
1389 | <p>The Babel protocol (RFC6126) is a loop-avoiding distance-vector routing | |
1390 | protocol that is robust and efficient both in ordinary wired networks and in | |
1391 | wireless mesh networks. Babel is conceptually very simple in its operation and | |
1392 | "just works" in its default configuration, though some configuration is possible | |
1393 | and in some cases desirable. | |
1394 | ||
1395 | <p>While the Babel protocol is dual stack (i.e., can carry both IPv4 and IPv6 | |
1396 | routes over the same IPv6 transport), BIRD presently implements only the IPv6 | |
1397 | subset of the protocol. No Babel extensions are implemented, but the BIRD | |
1398 | implementation can coexist with implementations using the extensions (and will | |
1399 | just ignore extension messages). | |
1400 | ||
1401 | <p>The Babel protocol implementation in BIRD is currently in alpha stage. | |
1402 | ||
1403 | <sect1>Configuration | |
1404 | ||
1405 | <p>Babel supports no global configuration options apart from those common to all | |
1406 | other protocols, but supports the following per-interface configuration options: | |
1407 | ||
1408 | <code> | |
1409 | protocol babel [<name>] { | |
1410 | interface <interface pattern> { | |
1411 | type <wired|wireless>; | |
1412 | rxcost <number>; | |
1413 | hello interval <number>; | |
1414 | update interval <number>; | |
1415 | port <number>; | |
1416 | tx class|dscp <number>; | |
1417 | tx priority <number>; | |
1418 | rx buffer <number>; | |
1419 | tx length <number>; | |
1420 | check link <switch>; | |
1421 | }; | |
1422 | } | |
1423 | </code> | |
1424 | ||
1425 | <descrip> | |
1426 | <tag>type wired|wireless </tag> | |
1427 | This option specifies the interface type: Wired or wireless. Wired | |
1428 | interfaces are considered more reliable, and so the default hello | |
1429 | interval is higher, and a neighbour is considered unreachable after only | |
1430 | a small number of "hello" packets are lost. On wireless interfaces, | |
1431 | hello packets are sent more often, and the ETX link quality estimation | |
1432 | technique is used to compute the metrics of routes discovered over this | |
1433 | interface. This technique will gradually degrade the metric of routes | |
1434 | when packets are lost rather than the more binary up/down mechanism of | |
1435 | wired type links. Default: <cf/wired/. | |
1436 | ||
1437 | <tag>rxcost <m/num/</tag> | |
1438 | This specifies the RX cost of the interface. The route metrics will be | |
1439 | computed from this value with a mechanism determined by the interface | |
1440 | <cf/type/. Default: 96 for wired interfaces, 256 for wireless. | |
1441 | ||
1442 | <tag>hello interval <m/num/</tag> | |
1443 | Interval at which periodic "hello" messages are sent on this interface, | |
1444 | in seconds. Default: 4 seconds. | |
1445 | ||
1446 | <tag>update interval <m/num/</tag> | |
1447 | Interval at which periodic (full) updates are sent. Default: 4 times the | |
1448 | hello interval. | |
1449 | ||
1450 | <tag>port <m/number/</tag> | |
1451 | This option selects an UDP port to operate on. The default is to operate | |
1452 | on port 6696 as specified in the Babel RFC. | |
1453 | ||
1454 | <tag>tx class|dscp|priority <m/number/</tag> | |
1455 | These options specify the ToS/DiffServ/Traffic class/Priority of the | |
1456 | outgoing Babel packets. See <ref id="dsc-prio" name="tx class"> common | |
1457 | option for detailed description. | |
1458 | ||
1459 | <tag>rx buffer <m/number/</tag> | |
1460 | This option specifies the size of buffers used for packet processing. | |
1461 | The buffer size should be bigger than maximal size of received packets. | |
1462 | The default value is the interface MTU, and the value will be clamped to a | |
1463 | minimum of 512 bytes + IP packet overhead. | |
1464 | ||
1465 | <tag>tx length <m/number/</tag> | |
1466 | This option specifies the maximum length of generated Babel packets. To | |
1467 | avoid IP fragmentation, it should not exceed the interface MTU value. | |
1468 | The default value is the interface MTU value, and the value will be | |
1469 | clamped to a minimum of 512 bytes + IP packet overhead. | |
1470 | ||
1471 | <tag>check link <m/switch/</tag> | |
1472 | If set, the hardware link state (as reported by OS) is taken into | |
1473 | consideration. When the link disappears (e.g. an ethernet cable is | |
1474 | unplugged), neighbors are immediately considered unreachable and all | |
1475 | routes received from them are withdrawn. It is possible that some | |
1476 | hardware drivers or platforms do not implement this feature. Default: | |
1477 | yes. | |
1478 | </descrip> | |
1479 | ||
12640c14 OZ |
1480 | <sect1>Attributes |
1481 | ||
1482 | <p>Babel defines just one attribute: the internal babel metric of the route. It | |
1483 | is exposed as the <cf/babel_metric/ attribute and has range from 1 to infinity | |
1484 | (65535). | |
1485 | ||
1486 | <sect1>Example | |
1487 | ||
1488 | <p><code> | |
1489 | protocol babel { | |
1490 | interface "eth*" { | |
1491 | type wired; | |
1492 | }; | |
1493 | interface "wlan0", "wlan1" { | |
1494 | type wireless; | |
1495 | hello interval 1; | |
1496 | rxcost 512; | |
1497 | }; | |
1498 | interface "tap0"; | |
1499 | ||
1500 | # This matches the default of babeld: redistribute all addresses | |
1501 | # configured on local interfaces, plus re-distribute all routes received | |
1502 | # from other babel peers. | |
1503 | ||
1504 | export where (source = RTS_DEVICE) || (source = RTS_BABEL); | |
1505 | } | |
1506 | </code> | |
1507 | ||
937e75d8 | 1508 | |
1ec52253 OZ |
1509 | <sect><label id="sect-bfd">BFD |
1510 | ||
1511 | <sect1>Introduction | |
1512 | ||
1513 | <p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it | |
1514 | is an independent tool providing liveness and failure detection. Routing | |
1515 | protocols like OSPF and BGP use integrated periodic "hello" messages to monitor | |
1516 | liveness of neighbors, but detection times of these mechanisms are high (e.g. 40 | |
1517 | seconds by default in OSPF, could be set down to several seconds). BFD offers | |
1518 | universal, fast and low-overhead mechanism for failure detection, which could be | |
1519 | attached to any routing protocol in an advisory role. | |
1520 | ||
1521 | <p>BFD consists of mostly independent BFD sessions. Each session monitors an | |
1522 | unicast bidirectional path between two BFD-enabled routers. This is done by | |
1523 | periodically sending control packets in both directions. BFD does not handle | |
1524 | neighbor discovery, BFD sessions are created on demand by request of other | |
1525 | protocols (like OSPF or BGP), which supply appropriate information like IP | |
1526 | addresses and associated interfaces. When a session changes its state, these | |
1527 | protocols are notified and act accordingly (e.g. break an OSPF adjacency when | |
1528 | the BFD session went down). | |
1529 | ||
1530 | <p>BIRD implements basic BFD behavior as defined in | |
1531 | RFC 5880<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5880.txt"> | |
1532 | (some advanced features like the echo mode or authentication are not implemented), | |
1533 | IP transport for BFD as defined in | |
1534 | RFC 5881<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5881.txt"> and | |
1535 | RFC 5883<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5883.txt"> | |
1536 | and interaction with client protocols as defined in | |
1537 | RFC 5882<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5882.txt">. | |
1538 | ||
1539 | <p>Note that BFD implementation in BIRD is currently a new feature in | |
1540 | development, expect some rough edges and possible UI and configuration changes | |
1541 | in the future. Also note that we currently support at most one protocol instance. | |
1542 | ||
d96ec7f6 OZ |
1543 | <p>BFD packets are sent with a dynamic source port number. Linux systems use by |
1544 | default a bit different dynamic port range than the IANA approved one | |
1545 | (49152-65535). If you experience problems with compatibility, please adjust | |
1546 | <cf>/proc/sys/net/ipv4/ip_local_port_range</cf> | |
1547 | ||
1ec52253 OZ |
1548 | <sect1>Configuration |
1549 | ||
1550 | <p>BFD configuration consists mainly of multiple definitions of interfaces. | |
1551 | Most BFD config options are session specific. When a new session is requested | |
1552 | and dynamically created, it is configured from one of these definitions. For | |
1553 | sessions to directly connected neighbors, <cf/interface/ definitions are chosen | |
1554 | based on the interface associated with the session, while <cf/multihop/ | |
1555 | definition is used for multihop sessions. If no definition is relevant, the | |
1556 | session is just created with the default configuration. Therefore, an empty BFD | |
1557 | configuration is often sufficient. | |
1558 | ||
1559 | <p>Note that to use BFD for other protocols like OSPF or BGP, these protocols | |
1560 | also have to be configured to request BFD sessions, usually by <cf/bfd/ option. | |
1561 | ||
1562 | <p>Some of BFD session options require <m/time/ value, which has to be specified | |
1563 | with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds | |
1564 | are allowed as units, practical minimum values are usually in order of tens of | |
1565 | milliseconds. | |
1566 | ||
1567 | <code> | |
1568 | protocol bfd [<name>] { | |
1569 | interface <interface pattern> { | |
1570 | interval <time>; | |
1571 | min rx interval <time>; | |
1572 | min tx interval <time>; | |
1573 | idle tx interval <time>; | |
1574 | multiplier <num>; | |
1575 | passive <switch>; | |
1576 | }; | |
1577 | multihop { | |
1578 | interval <time>; | |
1579 | min rx interval <time>; | |
1580 | min tx interval <time>; | |
1581 | idle tx interval <time>; | |
1582 | multiplier <num>; | |
1583 | passive <switch>; | |
1584 | }; | |
1585 | neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>]; | |
1586 | } | |
1587 | </code> | |
1588 | ||
1589 | <descrip> | |
dad92c30 | 1590 | <tag>interface <m/pattern [, ...]/ { <m/options/ }</tag> |
1ec52253 OZ |
1591 | Interface definitions allow to specify options for sessions associated |
1592 | with such interfaces and also may contain interface specific options. | |
1593 | See <ref id="dsc-iface" name="interface"> common option for a detailed | |
1594 | description of interface patterns. Note that contrary to the behavior of | |
1595 | <cf/interface/ definitions of other protocols, BFD protocol would accept | |
1596 | sessions (in default configuration) even on interfaces not covered by | |
1597 | such definitions. | |
1598 | ||
1599 | <tag>multihop { <m/options/ }</tag> | |
1600 | Multihop definitions allow to specify options for multihop BFD sessions, | |
1601 | in the same manner as <cf/interface/ definitions are used for directly | |
1602 | connected sessions. Currently only one such definition (for all multihop | |
1603 | sessions) could be used. | |
1604 | ||
1605 | <tag>neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag> | |
1606 | BFD sessions are usually created on demand as requested by other | |
1607 | protocols (like OSPF or BGP). This option allows to explicitly add | |
1608 | a BFD session to the specified neighbor regardless of such requests. | |
523f020b | 1609 | |
1ec52253 | 1610 | The session is identified by the IP address of the neighbor, with |
dad92c30 | 1611 | optional specification of used interface and local IP. By default |
fff7498d | 1612 | the neighbor must be directly connected, unless the session is |
1ec52253 OZ |
1613 | configured as multihop. Note that local IP must be specified for |
1614 | multihop sessions. | |
1615 | </descrip> | |
1616 | ||
1617 | <p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions): | |
1618 | ||
1619 | <descrip> | |
1620 | <tag>interval <m/time/</tag> | |
1621 | BFD ensures availability of the forwarding path associated with the | |
1622 | session by periodically sending BFD control packets in both | |
1623 | directions. The rate of such packets is controlled by two options, | |
1624 | <cf/min rx interval/ and <cf/min tx interval/ (see below). This option | |
1625 | is just a shorthand to set both of these options together. | |
1626 | ||
1627 | <tag>min rx interval <m/time/</tag> | |
1628 | This option specifies the minimum RX interval, which is announced to the | |
1629 | neighbor and used there to limit the neighbor's rate of generated BFD | |
1630 | control packets. Default: 10 ms. | |
1631 | ||
1632 | <tag>min tx interval <m/time/</tag> | |
1633 | This option specifies the desired TX interval, which controls the rate | |
1634 | of generated BFD control packets (together with <cf/min rx interval/ | |
1635 | announced by the neighbor). Note that this value is used only if the BFD | |
1636 | session is up, otherwise the value of <cf/idle tx interval/ is used | |
1637 | instead. Default: 100 ms. | |
1638 | ||
1639 | <tag>idle tx interval <m/time/</tag> | |
1640 | In order to limit unnecessary traffic in cases where a neighbor is not | |
1641 | available or not running BFD, the rate of generated BFD control packets | |
1642 | is lower when the BFD session is not up. This option specifies the | |
1643 | desired TX interval in such cases instead of <cf/min tx interval/. | |
1644 | Default: 1 s. | |
1645 | ||
1646 | <tag>multiplier <m/num/</tag> | |
1647 | Failure detection time for BFD sessions is based on established rate of | |
1648 | BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this | |
1649 | multiplier, which is essentially (ignoring jitter) a number of missed | |
1650 | packets after which the session is declared down. Note that rates and | |
1651 | multipliers could be different in each direction of a BFD session. | |
1652 | Default: 5. | |
1653 | ||
1654 | <tag>passive <m/switch/</tag> | |
fff7498d | 1655 | Generally, both BFD session endpoints try to establish the session by |
1ec52253 OZ |
1656 | sending control packets to the other side. This option allows to enable |
1657 | passive mode, which means that the router does not send BFD packets | |
1658 | until it has received one from the other side. Default: disabled. | |
1659 | </descrip> | |
1660 | ||
1661 | <sect1>Example | |
1662 | ||
1663 | <p><code> | |
1664 | protocol bfd { | |
1665 | interface "eth*" { | |
1666 | min rx interval 20 ms; | |
1667 | min tx interval 50 ms; | |
1668 | idle tx interval 300 ms; | |
1669 | }; | |
1670 | interface "gre*" { | |
1671 | interval 200 ms; | |
1672 | multiplier 10; | |
1673 | passive; | |
1674 | }; | |
1675 | multihop { | |
1676 | interval 200 ms; | |
1677 | multiplier 10; | |
1678 | }; | |
1679 | ||
1680 | neighbor 192.168.1.10; | |
1681 | neighbor 192.168.2.2 dev "eth2"; | |
1682 | neighbor 192.168.10.1 local 192.168.1.1 multihop; | |
1683 | } | |
1684 | </code> | |
1685 | ||
dad92c30 | 1686 | |
371adba6 | 1687 | <sect>BGP |
1b55b1a3 | 1688 | |
dad92c30 OZ |
1689 | <p>The Border Gateway Protocol is the routing protocol used for backbone level |
1690 | routing in the today's Internet. Contrary to other protocols, its convergence | |
1691 | does not rely on all routers following the same rules for route selection, | |
1692 | making it possible to implement any routing policy at any router in the network, | |
1693 | the only restriction being that if a router advertises a route, it must accept | |
1694 | and forward packets according to it. | |
1695 | ||
1696 | <p>BGP works in terms of autonomous systems (often abbreviated as AS). Each AS | |
1697 | is a part of the network with common management and common routing policy. It is | |
1698 | identified by a unique 16-bit number (ASN). Routers within each AS usually | |
1699 | exchange AS-internal routing information with each other using an interior | |
1700 | gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of | |
1701 | the AS communicate global (inter-AS) network reachability information with their | |
1702 | neighbors in the neighboring AS'es via exterior BGP (eBGP) and redistribute | |
1703 | received information to other routers in the AS via interior BGP (iBGP). | |
1704 | ||
1705 | <p>Each BGP router sends to its neighbors updates of the parts of its routing | |
1706 | table it wishes to export along with complete path information (a list of AS'es | |
1707 | the packet will travel through if it uses the particular route) in order to | |
1708 | avoid routing loops. | |
56ab03c7 | 1709 | |
5459fac6 | 1710 | <p>BIRD supports all requirements of the BGP4 standard as defined in |
1adc17b4 OZ |
1711 | RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt"> |
1712 | It also supports the community attributes | |
1713 | (RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">), | |
1714 | capability negotiation | |
06e0d1b6 | 1715 | (RFC 5492<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5492.txt">), |
1adc17b4 OZ |
1716 | MD5 password authentication |
1717 | (RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">), | |
8815d846 OZ |
1718 | extended communities |
1719 | (RFC 4360<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt">), | |
523f020b | 1720 | route reflectors |
1adc17b4 | 1721 | (RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">), |
6eda3f13 OZ |
1722 | graceful restart |
1723 | (RFC 4724<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4724.txt">), | |
e8ba557c OZ |
1724 | multiprotocol extensions |
1725 | (RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">), | |
523f020b | 1726 | 4B AS numbers |
8815d846 OZ |
1727 | (RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">), |
1728 | and 4B AS numbers in extended communities | |
1729 | (RFC 5668<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt">). | |
1adc17b4 OZ |
1730 | |
1731 | ||
5459fac6 | 1732 | For IPv6, it uses the standard multiprotocol extensions defined in |
6eda3f13 | 1733 | RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt"> |
5459fac6 MM |
1734 | and applied to IPv6 according to |
1735 | RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">. | |
1736 | ||
371adba6 | 1737 | <sect1>Route selection rules |
5459fac6 MM |
1738 | |
1739 | <p>BGP doesn't have any simple metric, so the rules for selection of an optimal | |
1740 | route among multiple BGP routes with the same preference are a bit more complex | |
dad92c30 OZ |
1741 | and they are implemented according to the following algorithm. It starts the |
1742 | first rule, if there are more "best" routes, then it uses the second rule to | |
1743 | choose among them and so on. | |
5459fac6 MM |
1744 | |
1745 | <itemize> | |
5a203dac | 1746 | <item>Prefer route with the highest Local Preference attribute. |
5459fac6 | 1747 | <item>Prefer route with the shortest AS path. |
b74f45f8 | 1748 | <item>Prefer IGP origin over EGP and EGP origin over incomplete. |
5459fac6 | 1749 | <item>Prefer the lowest value of the Multiple Exit Discriminator. |
b74f45f8 OZ |
1750 | <item>Prefer routes received via eBGP over ones received via iBGP. |
1751 | <item>Prefer routes with lower internal distance to a boundary router. | |
5a203dac | 1752 | <item>Prefer the route with the lowest value of router ID of the |
5459fac6 MM |
1753 | advertising router. |
1754 | </itemize> | |
56ab03c7 | 1755 | |
b74f45f8 OZ |
1756 | <sect1>IGP routing table |
1757 | ||
dad92c30 OZ |
1758 | <p>BGP is mainly concerned with global network reachability and with routes to |
1759 | other autonomous systems. When such routes are redistributed to routers in the | |
1760 | AS via BGP, they contain IP addresses of a boundary routers (in route attribute | |
1761 | NEXT_HOP). BGP depends on existing IGP routing table with AS-internal routes to | |
1762 | determine immediate next hops for routes and to know their internal distances to | |
1763 | boundary routers for the purpose of BGP route selection. In BIRD, there is | |
1764 | usually one routing table used for both IGP routes and BGP routes. | |
b74f45f8 | 1765 | |
371adba6 | 1766 | <sect1>Configuration |
56ab03c7 | 1767 | |
dad92c30 OZ |
1768 | <p>Each instance of the BGP corresponds to one neighboring router. This allows |
1769 | to set routing policy and all the other parameters differently for each neighbor | |
1770 | using the following configuration parameters: | |
5459fac6 MM |
1771 | |
1772 | <descrip> | |
dad92c30 OZ |
1773 | <tag>local [<m/ip/] as <m/number/</tag> |
1774 | Define which AS we are part of. (Note that contrary to other IP routers, | |
1775 | BIRD is able to act as a router located in multiple AS'es simultaneously, | |
1776 | but in such cases you need to tweak the BGP paths manually in the filters | |
1777 | to get consistent behavior.) Optional <cf/ip/ argument specifies a source | |
1778 | address, equivalent to the <cf/source address/ option (see below). This | |
f3e59178 OZ |
1779 | parameter is mandatory. |
1780 | ||
a1beb8f3 | 1781 | <tag>neighbor [<m/ip/] [port <m/number/] [as <m/number/]</tag> |
dad92c30 | 1782 | Define neighboring router this instance will be talking to and what AS |
a1beb8f3 OZ |
1783 | it is located in. In case the neighbor is in the same AS as we are, we |
1784 | automatically switch to iBGP. Optionally, the remote port may also be | |
1785 | specified. The parameter may be used multiple times with different | |
1786 | sub-options (e.g., both <cf/neighbor 10.0.0.1 as 65000;/ and | |
1787 | <cf/neighbor 10.0.0.1; neighbor as 65000;/ are valid). This parameter is | |
1788 | mandatory. | |
1789 | ||
1790 | <tag>interface <m/string/</tag> | |
1791 | Define interface we should use for link-local BGP IPv6 sessions. | |
1792 | Interface can also be specified as a part of <cf/neighbor address/ | |
1793 | (e.g., <cf/neighbor fe80::1234%eth0 as 65000;/). It is an error to use | |
1794 | this parameter for non link-local sessions. | |
dad92c30 OZ |
1795 | |
1796 | <tag>direct</tag> | |
1797 | Specify that the neighbor is directly connected. The IP address of the | |
1798 | neighbor must be from a directly reachable IP range (i.e. associated | |
1799 | with one of your router's interfaces), otherwise the BGP session | |
1800 | wouldn't start but it would wait for such interface to appear. The | |
1801 | alternative is the <cf/multihop/ option. Default: enabled for eBGP. | |
1802 | ||
1803 | <tag>multihop [<m/number/]</tag> | |
1804 | Configure multihop BGP session to a neighbor that isn't directly | |
1805 | connected. Accurately, this option should be used if the configured | |
1806 | neighbor IP address does not match with any local network subnets. Such | |
1807 | IP address have to be reachable through system routing table. The | |
1808 | alternative is the <cf/direct/ option. For multihop BGP it is | |
1809 | recommended to explicitly configure the source address to have it | |
1810 | stable. Optional <cf/number/ argument can be used to specify the number | |
1811 | of hops (used for TTL). Note that the number of networks (edges) in a | |
1812 | path is counted; i.e., if two BGP speakers are separated by one router, | |
1813 | the number of hops is 2. Default: enabled for iBGP. | |
1814 | ||
1815 | <tag>source address <m/ip/</tag> | |
1816 | Define local address we should use for next hop calculation and as a | |
1817 | source address for the BGP session. Default: the address of the local | |
9be9a264 OZ |
1818 | end of the interface our neighbor is connected to. |
1819 | ||
dad92c30 OZ |
1820 | <tag>next hop self</tag> |
1821 | Avoid calculation of the Next Hop attribute and always advertise our own | |
1822 | source address as a next hop. This needs to be used only occasionally to | |
1823 | circumvent misconfigurations of other routers. Default: disabled. | |
1824 | ||
1825 | <tag>next hop keep</tag> | |
1826 | Forward the received Next Hop attribute even in situations where the | |
1827 | local address should be used instead, like when the route is sent to an | |
1828 | interface with a different subnet. Default: disabled. | |
1829 | ||
1830 | <tag>missing lladdr self|drop|ignore</tag> | |
1831 | Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6 | |
1832 | address, but sometimes it has to contain both global and link-local IPv6 | |
1833 | addresses. This option specifies what to do if BIRD have to send both | |
1834 | addresses but does not know link-local address. This situation might | |
1835 | happen when routes from other protocols are exported to BGP, or when | |
1836 | improper updates are received from BGP peers. <cf/self/ means that BIRD | |
1837 | advertises its own local address instead. <cf/drop/ means that BIRD | |
1838 | skips that prefixes and logs error. <cf/ignore/ means that BIRD ignores | |
1839 | the problem and sends just the global address (and therefore forms | |
1840 | improper BGP update). Default: <cf/self/, unless BIRD is configured as a | |
1841 | route server (option <cf/rs client/), in that case default is <cf/ignore/, | |
1842 | because route servers usually do not forward packets themselves. | |
1843 | ||
1844 | <tag>gateway direct|recursive</tag> | |
1845 | For received routes, their <cf/gw/ (immediate next hop) attribute is | |
1846 | computed from received <cf/bgp_next_hop/ attribute. This option | |
1847 | specifies how it is computed. Direct mode means that the IP address from | |
1848 | <cf/bgp_next_hop/ is used if it is directly reachable, otherwise the | |
1849 | neighbor IP address is used. Recursive mode means that the gateway is | |
1850 | computed by an IGP routing table lookup for the IP address from | |
6683d42d OZ |
1851 | <cf/bgp_next_hop/. Note that there is just one level of indirection in |
1852 | recursive mode - the route obtained by the lookup must not be recursive | |
1853 | itself, to prevent mutually recursive routes. | |
1854 | ||
1855 | Recursive mode is the behavior specified by the BGP | |
dad92c30 OZ |
1856 | standard. Direct mode is simpler, does not require any routes in a |
1857 | routing table, and was used in older versions of BIRD, but does not | |
1858 | handle well nontrivial iBGP setups and multihop. Recursive mode is | |
1859 | incompatible with <ref id="dsc-sorted" name="sorted tables">. Default: | |
1860 | <cf/direct/ for direct sessions, <cf/recursive/ for multihop sessions. | |
1861 | ||
1862 | <tag>igp table <m/name/</tag> | |
1863 | Specifies a table that is used as an IGP routing table. Default: the | |
1864 | same as the table BGP is connected to. | |
1ec52253 | 1865 | |
523f020b OZ |
1866 | <tag>check link <M>switch</M></tag> |
1867 | BGP could use hardware link state into consideration. If enabled, | |
1868 | BIRD tracks the link state of the associated interface and when link | |
1869 | disappears (e.g. an ethernet cable is unplugged), the BGP session is | |
1870 | immediately shut down. Note that this option cannot be used with | |
1871 | multihop BGP. Default: disabled. | |
1872 | ||
1ec52253 OZ |
1873 | <tag>bfd <M>switch</M></tag> |
1874 | BGP could use BFD protocol as an advisory mechanism for neighbor | |
1875 | liveness and failure detection. If enabled, BIRD setups a BFD session | |
1876 | for the BGP neighbor and tracks its liveness by it. This has an | |
1877 | advantage of an order of magnitude lower detection times in case of | |
1878 | failure. Note that BFD protocol also has to be configured, see | |
1879 | <ref id="sect-bfd" name="BFD"> section for details. Default: disabled. | |
1880 | ||
dad92c30 OZ |
1881 | <tag>ttl security <m/switch/</tag> |
1882 | Use GTSM (RFC 5082 - the generalized TTL security mechanism). GTSM | |
1883 | protects against spoofed packets by ignoring received packets with a | |
1884 | smaller than expected TTL. To work properly, GTSM have to be enabled on | |
1885 | both sides of a BGP session. If both <cf/ttl security/ and <cf/multihop/ | |
1886 | options are enabled, <cf/multihop/ option should specify proper hop | |
1887 | value to compute expected TTL. Kernel support required: Linux: 2.6.34+ | |
1888 | (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only. Note that full | |
1889 | (ICMP protection, for example) RFC 5082 support is provided by Linux | |
b1b19433 | 1890 | only. Default: disabled. |
523f020b | 1891 | |
dad92c30 | 1892 | <tag>password <m/string/</tag> |
a7baa098 OZ |
1893 | Use this password for MD5 authentication of BGP sessions (RFC 2385). |
1894 | When used on BSD systems, see also <cf/setkey/ option below. Default: | |
1895 | no authentication. | |
1896 | ||
1897 | <tag>setkey <m/switch/</tag> | |
1898 | On BSD systems, keys for TCP MD5 authentication are stored in the global | |
1899 | SA/SP database, which can be accessed by external utilities (e.g. | |
1900 | setkey(8)). BIRD configures security associations in the SA/SP database | |
1901 | automatically based on <cf/password/ options (see above), this option | |
1902 | allows to disable automatic updates by BIRD when manual configuration by | |
1903 | external utilities is preferred. Note that automatic SA/SP database | |
1904 | updates are currently implemented only for FreeBSD. Passwords have to be | |
1905 | set manually by an external utility on NetBSD and OpenBSD. Default: | |
1906 | enabled (ignored on non-FreeBSD). | |
dad92c30 OZ |
1907 | |
1908 | <tag>passive <m/switch/</tag> | |
1909 | Standard BGP behavior is both initiating outgoing connections and | |
1910 | accepting incoming connections. In passive mode, outgoing connections | |
1911 | are not initiated. Default: off. | |
1912 | ||
1913 | <tag>rr client</tag> | |
1914 | Be a route reflector and treat the neighbor as a route reflection | |
1915 | client. Default: disabled. | |
1916 | ||
1917 | <tag>rr cluster id <m/IPv4 address/</tag> | |
1918 | Route reflectors use cluster id to avoid route reflection loops. When | |
1919 | there is one route reflector in a cluster it usually uses its router id | |
1920 | as a cluster id, but when there are more route reflectors in a cluster, | |
1921 | these need to be configured (using this option) to use a common cluster | |
1922 | id. Clients in a cluster need not know their cluster id and this option | |
1923 | is not allowed for them. Default: the same as router id. | |
1924 | ||
523f020b | 1925 | <tag>rs client</tag> |
dad92c30 OZ |
1926 | Be a route server and treat the neighbor as a route server client. |
1927 | A route server is used as a replacement for full mesh EBGP routing in | |
1928 | Internet exchange points in a similar way to route reflectors used in | |
1929 | IBGP routing. BIRD does not implement obsoleted RFC 1863, but uses | |
1930 | ad-hoc implementation, which behaves like plain EBGP but reduces | |
1931 | modifications to advertised route attributes to be transparent (for | |
1932 | example does not prepend its AS number to AS PATH attribute and keeps | |
1933 | MED attribute). Default: disabled. | |
1934 | ||
1935 | <tag>secondary <m/switch/</tag> | |
1936 | Usually, if an export filter rejects a selected route, no other route is | |
1937 | propagated for that network. This option allows to try the next route in | |
1938 | order until one that is accepted is found or all routes for that network | |
1939 | are rejected. This can be used for route servers that need to propagate | |
1940 | different tables to each client but do not want to have these tables | |
1941 | explicitly (to conserve memory). This option requires that the connected | |
1942 | routing table is <ref id="dsc-sorted" name="sorted">. Default: off. | |
48cf5e84 | 1943 | |
10115b1d OZ |
1944 | <tag>add paths <m/switch/|rx|tx</tag> |
1945 | Standard BGP can propagate only one path (route) per destination network | |
1946 | (usually the selected one). This option controls the add-path protocol | |
1947 | extension, which allows to advertise any number of paths to a | |
1948 | destination. Note that to be active, add-path has to be enabled on both | |
1949 | sides of the BGP session, but it could be enabled separately for RX and | |
1950 | TX direction. When active, all available routes accepted by the export | |
1951 | filter are advertised to the neighbor. Default: off. | |
1952 | ||
523f020b | 1953 | <tag>allow local as [<m/number/]</tag> |
dad92c30 OZ |
1954 | BGP prevents routing loops by rejecting received routes with the local |
1955 | AS number in the AS path. This option allows to loose or disable the | |
1956 | check. Optional <cf/number/ argument can be used to specify the maximum | |
1957 | number of local ASNs in the AS path that is allowed for received | |
1958 | routes. When the option is used without the argument, the check is | |
1959 | completely disabled and you should ensure loop-free behavior by some | |
1960 | other means. Default: 0 (no local AS number allowed). | |
1961 | ||
1962 | <tag>enable route refresh <m/switch/</tag> | |
9aed29e6 OZ |
1963 | After the initial route exchange, BGP protocol uses incremental updates |
1964 | to keep BGP speakers synchronized. Sometimes (e.g., if BGP speaker | |
1965 | changes its import filter, or if there is suspicion of inconsistency) it | |
1966 | is necessary to do a new complete route exchange. BGP protocol extension | |
1967 | Route Refresh (RFC 2918) allows BGP speaker to request re-advertisement | |
1968 | of all routes from its neighbor. BGP protocol extension Enhanced Route | |
1969 | Refresh (RFC 7313) specifies explicit begin and end for such exchanges, | |
1970 | therefore the receiver can remove stale routes that were not advertised | |
1971 | during the exchange. This option specifies whether BIRD advertises these | |
1972 | capabilities and supports related procedures. Note that even when | |
1973 | disabled, BIRD can send route refresh requests. Default: on. | |
bf47fe4b | 1974 | |
6eda3f13 OZ |
1975 | <tag>graceful restart <m/switch/|aware</tag> |
1976 | When a BGP speaker restarts or crashes, neighbors will discard all | |
1977 | received paths from the speaker, which disrupts packet forwarding even | |
1978 | when the forwarding plane of the speaker remains intact. RFC 4724 | |
1979 | specifies an optional graceful restart mechanism to alleviate this | |
1980 | issue. This option controls the mechanism. It has three states: | |
1981 | Disabled, when no support is provided. Aware, when the graceful restart | |
1982 | support is announced and the support for restarting neighbors is | |
1983 | provided, but no local graceful restart is allowed (i.e. receiving-only | |
1984 | role). Enabled, when the full graceful restart support is provided | |
1985 | (i.e. both restarting and receiving role). Note that proper support for | |
1986 | local graceful restart requires also configuration of other protocols. | |
1987 | Default: aware. | |
1988 | ||
1989 | <tag>graceful restart time <m/number/</tag> | |
1990 | The restart time is announced in the BGP graceful restart capability | |
1991 | and specifies how long the neighbor would wait for the BGP session to | |
1992 | re-establish after a restart before deleting stale routes. Default: | |
1993 | 120 seconds. | |
1994 | ||
dad92c30 OZ |
1995 | <tag>interpret communities <m/switch/</tag> |
1996 | RFC 1997 demands that BGP speaker should process well-known communities | |
1997 | like no-export (65535, 65281) or no-advertise (65535, 65282). For | |
1998 | example, received route carrying a no-adverise community should not be | |
1999 | advertised to any of its neighbors. If this option is enabled (which is | |
2000 | by default), BIRD has such behavior automatically (it is evaluated when | |
2001 | a route is exported to the BGP protocol just before the export filter). | |
2002 | Otherwise, this integrated processing of well-known communities is | |
2003 | disabled. In that case, similar behavior can be implemented in the | |
2004 | export filter. Default: on. | |
2005 | ||
2006 | <tag>enable as4 <m/switch/</tag> | |
2007 | BGP protocol was designed to use 2B AS numbers and was extended later to | |
2008 | allow 4B AS number. BIRD supports 4B AS extension, but by disabling this | |
2009 | option it can be persuaded not to advertise it and to maintain old-style | |
2010 | sessions with its neighbors. This might be useful for circumventing bugs | |
2011 | in neighbor's implementation of 4B AS extension. Even when disabled | |
2012 | (off), BIRD behaves internally as AS4-aware BGP router. Default: on. | |
2013 | ||
79a4f74a PT |
2014 | <tag>enable extended messages <m/switch/</tag> |
2015 | The BGP protocol uses maximum message length of 4096 bytes. This option | |
2016 | provides an extension to allow extended messages with length up | |
2017 | to 65535 bytes. Default: off. | |
2018 | ||
dad92c30 OZ |
2019 | <tag>capabilities <m/switch/</tag> |
2020 | Use capability advertisement to advertise optional capabilities. This is | |
2021 | standard behavior for newer BGP implementations, but there might be some | |
2022 | older BGP implementations that reject such connection attempts. When | |
2023 | disabled (off), features that request it (4B AS support) are also | |
2024 | disabled. Default: on, with automatic fallback to off when received | |
2025 | capability-related error. | |
2026 | ||
2027 | <tag>advertise ipv4 <m/switch/</tag> | |
2028 | Advertise IPv4 multiprotocol capability. This is not a correct behavior | |
2029 | according to the strict interpretation of RFC 4760, but it is widespread | |
2030 | and required by some BGP implementations (Cisco and Quagga). This option | |
2031 | is relevant to IPv4 mode with enabled capability advertisement | |
2032 | only. Default: on. | |
2033 | ||
2034 | <tag>route limit <m/number/</tag> | |
2035 | The maximal number of routes that may be imported from the protocol. If | |
2036 | the route limit is exceeded, the connection is closed with an error. | |
2037 | Limit is currently implemented as <cf>import limit <m/number/ action | |
2038 | restart</cf>. This option is obsolete and it is replaced by | |
2039 | <ref id="import-limit" name="import limit option">. Default: no limit. | |
2040 | ||
2041 | <tag>disable after error <m/switch/</tag> | |
2042 | When an error is encountered (either locally or by the other side), | |
2043 | disable the instance automatically and wait for an administrator to fix | |
2044 | the problem manually. Default: off. | |
2045 | ||
2046 | <tag>hold time <m/number/</tag> | |
2047 | Time in seconds to wait for a Keepalive message from the other side | |
2048 | before considering the connection stale. Default: depends on agreement | |
2049 | with the neighboring router, we prefer 240 seconds if the other side is | |
2050 | willing to accept it. | |
2051 | ||
2052 | <tag>startup hold time <m/number/</tag> | |
2053 | Value of the hold timer used before the routers have a chance to exchange | |
2054 | open messages and agree on the real value. Default: 240 seconds. | |
2055 | ||
2056 | <tag>keepalive time <m/number/</tag> | |
2057 | Delay in seconds between sending of two consecutive Keepalive messages. | |
2058 | Default: One third of the hold time. | |
2059 | ||
6cf72d7a OZ |
2060 | <tag>connect delay time <m/number/</tag> |
2061 | Delay in seconds between protocol startup and the first attempt to | |
2062 | connect. Default: 5 seconds. | |
2063 | ||
dad92c30 OZ |
2064 | <tag>connect retry time <m/number/</tag> |
2065 | Time in seconds to wait before retrying a failed attempt to connect. | |
2066 | Default: 120 seconds. | |
2067 | ||
dad92c30 OZ |
2068 | <tag>error wait time <m/number/,<m/number/</tag> |
2069 | Minimum and maximum delay in seconds between a protocol failure (either | |
2070 | local or reported by the peer) and automatic restart. Doesn't apply | |
2071 | when <cf/disable after error/ is configured. If consecutive errors | |
2072 | happen, the delay is increased exponentially until it reaches the | |
2073 | maximum. Default: 60, 300. | |
2074 | ||
2075 | <tag>error forget time <m/number/</tag> | |
2076 | Maximum time in seconds between two protocol failures to treat them as a | |
2077 | error sequence which makes <cf/error wait time/ increase exponentially. | |
2078 | Default: 300 seconds. | |
2079 | ||
2080 | <tag>path metric <m/switch/</tag> | |
2081 | Enable comparison of path lengths when deciding which BGP route is the | |
2082 | best one. Default: on. | |
2083 | ||
2084 | <tag>med metric <m/switch/</tag> | |
2085 | Enable comparison of MED attributes (during best route selection) even | |
2086 | between routes received from different ASes. This may be useful if all | |
2087 | MED attributes contain some consistent metric, perhaps enforced in | |
2088 | import filters of AS boundary routers. If this option is disabled, MED | |
2089 | attributes are compared only if routes are received from the same AS | |
2090 | (which is the standard behavior). Default: off. | |
2091 | ||
2092 | <tag>deterministic med <m/switch/</tag> | |
2093 | BGP route selection algorithm is often viewed as a comparison between | |
2094 | individual routes (e.g. if a new route appears and is better than the | |
2095 | current best one, it is chosen as the new best one). But the proper | |
2096 | route selection, as specified by RFC 4271, cannot be fully implemented | |
2097 | in that way. The problem is mainly in handling the MED attribute. BIRD, | |
2098 | by default, uses an simplification based on individual route comparison, | |
2099 | which in some cases may lead to temporally dependent behavior (i.e. the | |
2100 | selection is dependent on the order in which routes appeared). This | |
2101 | option enables a different (and slower) algorithm implementing proper | |
2102 | RFC 4271 route selection, which is deterministic. Alternative way how to | |
2103 | get deterministic behavior is to use <cf/med metric/ option. This option | |
2104 | is incompatible with <ref id="dsc-sorted" name="sorted tables">. | |
48cf5e84 | 2105 | Default: off. |
be4cd99a | 2106 | |
dad92c30 OZ |
2107 | <tag>igp metric <m/switch/</tag> |
2108 | Enable comparison of internal distances to boundary routers during best | |
2109 | route selection. Default: on. | |
2110 | ||
2111 | <tag>prefer older <m/switch/</tag> | |
2112 | Standard route selection algorithm breaks ties by comparing router IDs. | |
2113 | This changes the behavior to prefer older routes (when both are external | |
2114 | and from different peer). For details, see RFC 5004. Default: off. | |
2115 | ||
2116 | <tag>default bgp_med <m/number/</tag> | |
2117 | Value of the Multiple Exit Discriminator to be used during route | |
2118 | selection when the MED attribute is missing. Default: 0. | |
2119 | ||
2120 | <tag>default bgp_local_pref <m/number/</tag> | |
2121 | A default value for the Local Preference attribute. It is used when | |
2122 | a new Local Preference attribute is attached to a route by the BGP | |
2123 | protocol itself (for example, if a route is received through eBGP and | |
2124 | therefore does not have such attribute). Default: 100 (0 in pre-1.2.0 | |
2125 | versions of BIRD). | |
5459fac6 MM |
2126 | </descrip> |
2127 | ||
371adba6 | 2128 | <sect1>Attributes |
56ab03c7 | 2129 | |
dad92c30 OZ |
2130 | <p>BGP defines several route attributes. Some of them (those marked with |
2131 | `<tt/I/' in the table below) are available on internal BGP connections only, | |
2132 | some of them (marked with `<tt/O/') are optional. | |
5459fac6 MM |
2133 | |
2134 | <descrip> | |
dad92c30 OZ |
2135 | <tag>bgppath <cf/bgp_path/</tag> |
2136 | Sequence of AS numbers describing the AS path the packet will travel | |
2137 | through when forwarded according to the particular route. In case of | |
2138 | internal BGP it doesn't contain the number of the local AS. | |
2139 | ||
2140 | <tag>int <cf/bgp_local_pref/ [I]</tag> | |
2141 | Local preference value used for selection among multiple BGP routes (see | |
2142 | the selection rules above). It's used as an additional metric which is | |
2143 | propagated through the whole local AS. | |
2144 | ||
2145 | <tag>int <cf/bgp_med/ [O]</tag> | |
2146 | The Multiple Exit Discriminator of the route is an optional attribute | |
2147 | which is used on external (inter-AS) links to convey to an adjacent AS | |
2148 | the optimal entry point into the local AS. The received attribute is | |
2149 | also propagated over internal BGP links. The attribute value is zeroed | |
2150 | when a route is exported to an external BGP instance to ensure that the | |
2151 | attribute received from a neighboring AS is not propagated to other | |
2152 | neighboring ASes. A new value might be set in the export filter of an | |
2153 | external BGP instance. See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt"> | |
b6bf284a | 2154 | for further discussion of BGP MED attribute. |
5a203dac | 2155 | |
dad92c30 OZ |
2156 | <tag>enum <cf/bgp_origin/</tag> |
2157 | Origin of the route: either <cf/ORIGIN_IGP/ if the route has originated | |
2158 | in an interior routing protocol or <cf/ORIGIN_EGP/ if it's been imported | |
2159 | from the <tt>EGP</tt> protocol (nowadays it seems to be obsolete) or | |
2160 | <cf/ORIGIN_INCOMPLETE/ if the origin is unknown. | |
5a203dac | 2161 | |
dad92c30 OZ |
2162 | <tag>ip <cf/bgp_next_hop/</tag> |
2163 | Next hop to be used for forwarding of packets to this destination. On | |
2164 | internal BGP connections, it's an address of the originating router if | |
2165 | it's inside the local AS or a boundary router the packet will leave the | |
2166 | AS through if it's an exterior route, so each BGP speaker within the AS | |
2167 | has a chance to use the shortest interior path possible to this point. | |
5a203dac | 2168 | |
dad92c30 OZ |
2169 | <tag>void <cf/bgp_atomic_aggr/ [O]</tag> |
2170 | This is an optional attribute which carries no value, but the sole | |
2171 | presence of which indicates that the route has been aggregated from | |
2172 | multiple routes by some router on the path from the originator. | |
5a203dac | 2173 | |
5459fac6 MM |
2174 | <!-- we don't handle aggregators right since they are of a very obscure type |
2175 | <tag>bgp_aggregator</tag> | |
2176 | --> | |
dad92c30 OZ |
2177 | <tag>clist <cf/bgp_community/ [O]</tag> |
2178 | List of community values associated with the route. Each such value is a | |
2179 | pair (represented as a <cf/pair/ data type inside the filters) of 16-bit | |
2180 | integers, the first of them containing the number of the AS which | |
2181 | defines the community and the second one being a per-AS identifier. | |
2182 | There are lots of uses of the community mechanism, but generally they | |
2183 | are used to carry policy information like "don't export to USA peers". | |
2184 | As each AS can define its own routing policy, it also has a complete | |
2185 | freedom about which community attributes it defines and what will their | |
2186 | semantics be. | |
2187 | ||
2188 | <tag>eclist <cf/bgp_ext_community/ [O]</tag> | |
2189 | List of extended community values associated with the route. Extended | |
2190 | communities have similar usage as plain communities, but they have an | |
2191 | extended range (to allow 4B ASNs) and a nontrivial structure with a type | |
2192 | field. Individual community values are represented using an <cf/ec/ data | |
2193 | type inside the filters. | |
2194 | ||
2195 | <tag>quad <cf/bgp_originator_id/ [I, O]</tag> | |
2196 | This attribute is created by the route reflector when reflecting the | |
2197 | route and contains the router ID of the originator of the route in the | |
2198 | local AS. | |
2199 | ||
2200 | <tag>clist <cf/bgp_cluster_list/ [I, O]</tag> | |
2201 | This attribute contains a list of cluster IDs of route reflectors. Each | |
2202 | route reflector prepends its cluster ID when reflecting the route. | |
5459fac6 MM |
2203 | </descrip> |
2204 | ||
371adba6 | 2205 | <sect1>Example |
56ab03c7 | 2206 | |
5459fac6 MM |
2207 | <p><code> |
2208 | protocol bgp { | |
96264d4d | 2209 | local as 65000; # Use a private AS number |
9491f9f5 | 2210 | neighbor 198.51.100.130 as 64496; # Our neighbor ... |
6bcef225 | 2211 | multihop; # ... which is connected indirectly |
96264d4d PM |
2212 | export filter { # We use non-trivial export rules |
2213 | if source = RTS_STATIC then { # Export only static routes | |
79a4f74a | 2214 | # Assign our community |
9491f9f5 | 2215 | bgp_community.add((65000,64501)); |
a852c139 | 2216 | # Artificially increase path length |
5a203dac | 2217 | # by advertising local AS number twice |
9491f9f5 OZ |
2218 | if bgp_path ~ [= 65000 =] then |
2219 | bgp_path.prepend(65000); | |
5459fac6 MM |
2220 | accept; |
2221 | } | |
2222 | reject; | |
2223 | }; | |
2224 | import all; | |
9491f9f5 | 2225 | source address 198.51.100.14; # Use a non-standard source address |
5459fac6 MM |
2226 | } |
2227 | </code> | |
2228 | ||
dad92c30 | 2229 | |
371adba6 | 2230 | <sect>Device |
1b55b1a3 | 2231 | |
dad92c30 OZ |
2232 | <p>The Device protocol is not a real routing protocol. It doesn't generate any |
2233 | routes and it only serves as a module for getting information about network | |
79a2b697 MM |
2234 | interfaces from the kernel. |
2235 | ||
dad92c30 OZ |
2236 | <p>Except for very unusual circumstances, you probably should include this |
2237 | protocol in the configuration since almost all other protocols require network | |
2238 | interfaces to be defined for them to work with. | |
79a2b697 | 2239 | |
6f5603ba | 2240 | <sect1>Configuration |
79a2b697 MM |
2241 | |
2242 | <p><descrip> | |
dad92c30 OZ |
2243 | |
2244 | <tag>scan time <m/number/</tag> | |
dad92c30 OZ |
2245 | Time in seconds between two scans of the network interface list. On |
2246 | systems where we are notified about interface status changes | |
2247 | asynchronously (such as newer versions of Linux), we need to scan the | |
2248 | list only in order to avoid confusion by lost notification messages, | |
2249 | so the default time is set to a large value. | |
2250 | ||
2251 | <tag>primary [ "<m/mask/" ] <m/prefix/</tag> | |
2252 | If a network interface has more than one network address, BIRD has to | |
2253 | choose one of them as a primary one. By default, BIRD chooses the | |
2254 | lexicographically smallest address as the primary one. | |
2255 | ||
2256 | This option allows to specify which network address should be chosen as | |
2257 | a primary one. Network addresses that match <m/prefix/ are preferred to | |
2258 | non-matching addresses. If more <cf/primary/ options are used, the first | |
2259 | one has the highest preference. If "<m/mask/" is specified, then such | |
2260 | <cf/primary/ option is relevant only to matching network interfaces. | |
2261 | ||
2262 | In all cases, an address marked by operating system as secondary cannot | |
2263 | be chosen as the primary one. | |
79a2b697 MM |
2264 | </descrip> |
2265 | ||
79a2b697 | 2266 | <p>As the Device protocol doesn't generate any routes, it cannot have |
6f5603ba | 2267 | any attributes. Example configuration looks like this: |
79a2b697 MM |
2268 | |
2269 | <p><code> | |
2270 | protocol device { | |
2271 | scan time 10; # Scan the interfaces often | |
6f5603ba OZ |
2272 | primary "eth0" 192.168.1.1; |
2273 | primary 192.168.0.0/16; | |
79a2b697 MM |
2274 | } |
2275 | </code> | |
2276 | ||
dad92c30 | 2277 | |
371adba6 | 2278 | <sect>Direct |
1b55b1a3 | 2279 | |
79a2b697 | 2280 | <p>The Direct protocol is a simple generator of device routes for all the |
dad92c30 OZ |
2281 | directly connected networks according to the list of interfaces provided by the |
2282 | kernel via the Device protocol. | |
2283 | ||
2284 | <p>The question is whether it is a good idea to have such device routes in BIRD | |
2285 | routing table. OS kernel usually handles device routes for directly connected | |
2286 | networks by itself so we don't need (and don't want) to export these routes to | |
2287 | the kernel protocol. OSPF protocol creates device routes for its interfaces | |
2288 | itself and BGP protocol is usually used for exporting aggregate routes. Although | |
2289 | there are some use cases that use the direct protocol (like abusing eBGP as an | |
2290 | IGP routing protocol), in most cases it is not needed to have these device | |
c429d4a4 | 2291 | routes in BIRD routing table and to use the direct protocol. |
79a2b697 | 2292 | |
dad92c30 OZ |
2293 | <p>There is one notable case when you definitely want to use the direct protocol |
2294 | -- running BIRD on BSD systems. Having high priority device routes for directly | |
2295 | connected networks from the direct protocol protects kernel device routes from | |
2296 | being overwritten or removed by IGP routes during some transient network | |
2297 | conditions, because a lower priority IGP route for the same network is not | |
2298 | exported to the kernel routing table. This is an issue on BSD systems only, as | |
2299 | on Linux systems BIRD cannot change non-BIRD route in the kernel routing table. | |
cf3a704b | 2300 | |
e90dd656 | 2301 | <p>There are just few configuration options for the Direct protocol: |
79a2b697 MM |
2302 | |
2303 | <p><descrip> | |
dad92c30 OZ |
2304 | <tag>interface <m/pattern [, ...]/</tag> |
2305 | By default, the Direct protocol will generate device routes for all the | |
2306 | interfaces available. If you want to restrict it to some subset of | |
d7c06285 OZ |
2307 | interfaces or addresses (e.g. if you're using multiple routing tables |
2308 | for policy routing and some of the policy domains don't contain all | |
2309 | interfaces), just use this clause. See <ref id="dsc-iface" name="interface"> | |
2310 | common option for detailed description. The Direct protocol uses | |
2311 | extended interface clauses. | |
e90dd656 OZ |
2312 | |
2313 | <tag>check link <m/switch/</tag> | |
2314 | If enabled, a hardware link state (reported by OS) is taken into | |
2315 | consideration. Routes for directly connected networks are generated only | |
2316 | if link up is reported and they are withdrawn when link disappears | |
2317 | (e.g., an ethernet cable is unplugged). Default value is no. | |
79a2b697 MM |
2318 | </descrip> |
2319 | ||
79a2b697 MM |
2320 | <p>Direct device routes don't contain any specific attributes. |
2321 | ||
4f88ac47 | 2322 | <p>Example config might look like this: |
79a2b697 MM |
2323 | |
2324 | <p><code> | |
2325 | protocol direct { | |
2326 | interface "-arc*", "*"; # Exclude the ARCnets | |
2327 | } | |
2328 | </code> | |
2329 | ||
dad92c30 | 2330 | |
371adba6 | 2331 | <sect>Kernel |
1b55b1a3 | 2332 | |
0e4789c2 | 2333 | <p>The Kernel protocol is not a real routing protocol. Instead of communicating |
c429d4a4 | 2334 | with other routers in the network, it performs synchronization of BIRD's routing |
dad92c30 OZ |
2335 | tables with the OS kernel. Basically, it sends all routing table updates to the |
2336 | kernel and from time to time it scans the kernel tables to see whether some | |
2337 | routes have disappeared (for example due to unnoticed up/down transition of an | |
2338 | interface) or whether an `alien' route has been added by someone else (depending | |
2339 | on the <cf/learn/ switch, such routes are either ignored or accepted to our | |
f8e2d916 | 2340 | table). |
0e4789c2 | 2341 | |
dad92c30 OZ |
2342 | <p>Unfortunately, there is one thing that makes the routing table synchronization |
2343 | a bit more complicated. In the kernel routing table there are also device routes | |
2344 | for directly connected networks. These routes are usually managed by OS itself | |
2345 | (as a part of IP address configuration) and we don't want to touch that. They | |
2346 | are completely ignored during the scan of the kernel tables and also the export | |
2347 | of device routes from BIRD tables to kernel routing tables is restricted to | |
2348 | prevent accidental interference. This restriction can be disabled using | |
c429d4a4 OZ |
2349 | <cf/device routes/ switch. |
2350 | ||
dad92c30 OZ |
2351 | <p>If your OS supports only a single routing table, you can configure only one |
2352 | instance of the Kernel protocol. If it supports multiple tables (in order to | |
2353 | allow policy routing; such an OS is for example Linux), you can run as many | |
2354 | instances as you want, but each of them must be connected to a different BIRD | |
2355 | routing table and to a different kernel table. | |
0e4789c2 | 2356 | |
dad92c30 OZ |
2357 | <p>Because the kernel protocol is partially integrated with the connected |
2358 | routing table, there are two limitations - it is not possible to connect more | |
2359 | kernel protocols to the same routing table and changing route destination | |
2360 | (gateway) in an export filter of a kernel protocol does not work. Both | |
2361 | limitations can be overcome using another routing table and the pipe protocol. | |
71ca7716 | 2362 | |
371adba6 | 2363 | <sect1>Configuration |
0e4789c2 MM |
2364 | |
2365 | <p><descrip> | |
6eda3f13 OZ |
2366 | <tag>persist <m/switch/</tag> |
2367 | Tell BIRD to leave all its routes in the routing tables when it exits | |
2368 | (instead of cleaning them up). | |
2369 | ||
2370 | <tag>scan time <m/number/</tag> | |
2371 | Time in seconds between two consecutive scans of the kernel routing | |
2372 | table. | |
2373 | ||
2374 | <tag>learn <m/switch/</tag> | |
2375 | Enable learning of routes added to the kernel routing tables by other | |
2376 | routing daemons or by the system administrator. This is possible only on | |
2377 | systems which support identification of route authorship. | |
2378 | ||
2379 | <tag>device routes <m/switch/</tag> | |
2380 | Enable export of device routes to the kernel routing table. By default, | |
2381 | such routes are rejected (with the exception of explicitly configured | |
2382 | device routes from the static protocol) regardless of the export filter | |
2383 | to protect device routes in kernel routing table (managed by OS itself) | |
2384 | from accidental overwriting or erasing. | |
2385 | ||
2386 | <tag>kernel table <m/number/</tag> | |
2387 | Select which kernel table should this particular instance of the Kernel | |
2388 | protocol work with. Available only on systems supporting multiple | |
2389 | routing tables. | |
2390 | ||
2391 | <tag>graceful restart <m/switch/</tag> | |
2392 | Participate in graceful restart recovery. If this option is enabled and | |
2393 | a graceful restart recovery is active, the Kernel protocol will defer | |
2394 | synchronization of routing tables until the end of the recovery. Note | |
2395 | that import of kernel routes to BIRD is not affected. | |
8d9eef17 OZ |
2396 | |
2397 | <tag>merge paths <M>switch</M> [limit <M>number</M>]</tag> | |
2398 | Usually, only best routes are exported to the kernel protocol. With path | |
2399 | merging enabled, both best routes and equivalent non-best routes are | |
2400 | merged during export to generate one ECMP (equal-cost multipath) route | |
2401 | for each network. This is useful e.g. for BGP multipath. Note that best | |
2402 | routes are still pivotal for route export (responsible for most | |
2403 | properties of resulting ECMP routes), while exported non-best routes are | |
2404 | responsible just for additional multipath next hops. This option also | |
2405 | allows to specify a limit on maximal number of nexthops in one route. By | |
2406 | default, multipath merging is disabled. If enabled, default value of the | |
2407 | limit is 16. | |
0e4789c2 MM |
2408 | </descrip> |
2409 | ||
71ca7716 OZ |
2410 | <sect1>Attributes |
2411 | ||
dad92c30 OZ |
2412 | <p>The Kernel protocol defines several attributes. These attributes are |
2413 | translated to appropriate system (and OS-specific) route attributes. We support | |
2414 | these attributes: | |
71ca7716 OZ |
2415 | |
2416 | <descrip> | |
dad92c30 OZ |
2417 | <tag>int <cf/krt_source/</tag> |
2418 | The original source of the imported kernel route. The value is | |
2419 | system-dependent. On Linux, it is a value of the protocol field of the | |
2420 | route. See /etc/iproute2/rt_protos for common values. On BSD, it is | |
72aed1a0 OZ |
2421 | based on STATIC and PROTOx flags. The attribute is read-only. |
2422 | ||
dad92c30 OZ |
2423 | <tag>int <cf/krt_metric/</tag> |
2424 | The kernel metric of the route. When multiple same routes are in a | |
2425 | kernel routing table, the Linux kernel chooses one with lower metric. | |
9ba2798c | 2426 | |
dad92c30 OZ |
2427 | <tag>ip <cf/krt_prefsrc/</tag> (Linux) |
2428 | The preferred source address. Used in source address selection for | |
79a4f74a | 2429 | outgoing packets. Has to be one of the IP addresses of the router. |
71ca7716 | 2430 | |
dad92c30 OZ |
2431 | <tag>int <cf/krt_realm/</tag> (Linux) |
2432 | The realm of the route. Can be used for traffic classification. | |
71ca7716 OZ |
2433 | </descrip> |
2434 | ||
6683d42d OZ |
2435 | <p>In Linux, there is also a plenty of obscure route attributes mostly focused |
2436 | on tuning TCP performance of local connections. BIRD supports most of these | |
2437 | attributes, see Linux or iproute2 documentation for their meaning. Attributes | |
2438 | <cf/krt_lock_*/ and <cf/krt_feature_*/ have type bool, others have type int. | |
2439 | Supported attributes are: | |
2440 | ||
2441 | <cf/krt_mtu/, <cf/krt_lock_mtu/, <cf/krt_window/, <cf/krt_lock_window/, | |
2442 | <cf/krt_rtt/, <cf/krt_lock_rtt/, <cf/krt_rttvar/, <cf/krt_lock_rttvar/, | |
2443 | <cf/krt_sstresh/, <cf/krt_lock_sstresh/, <cf/krt_cwnd/, <cf/krt_lock_cwnd/, | |
2444 | <cf/krt_advmss/, <cf/krt_lock_advmss/, <cf/krt_reordering/, <cf/krt_lock_reordering/, | |
2445 | <cf/krt_hoplimit/, <cf/krt_lock_hoplimit/, <cf/krt_rto_min/, <cf/krt_lock_rto_min/, | |
2446 | <cf/krt_initcwnd/, <cf/krt_initrwnd/, <cf/krt_quickack/, | |
2447 | <cf/krt_feature_ecn/, <cf/krt_feature_allfrag/ | |
2448 | ||
71ca7716 OZ |
2449 | <sect1>Example |
2450 | ||
326e33f5 | 2451 | <p>A simple configuration can look this way: |
0e4789c2 MM |
2452 | |
2453 | <p><code> | |
2454 | protocol kernel { | |
0e4789c2 MM |
2455 | export all; |
2456 | } | |
2457 | </code> | |
2458 | ||
2459 | <p>Or for a system with two routing tables: | |
2460 | ||
2461 | <p><code> | |
2462 | protocol kernel { # Primary routing table | |
2463 | learn; # Learn alien routes from the kernel | |
2464 | persist; # Don't remove routes on bird shutdown | |
2465 | scan time 10; # Scan kernel routing table every 10 seconds | |
2466 | import all; | |
2467 | export all; | |
2468 | } | |
2469 | ||
2470 | protocol kernel { # Secondary routing table | |
2471 | table auxtable; | |
2472 | kernel table 100; | |
2473 | export all; | |
a2a3ced8 | 2474 | } |
0e4789c2 MM |
2475 | </code> |
2476 | ||
dad92c30 | 2477 | |
371adba6 | 2478 | <sect>OSPF |
1b55b1a3 | 2479 | |
8fd12e6b OF |
2480 | <sect1>Introduction |
2481 | ||
3ca3e999 | 2482 | <p>Open Shortest Path First (OSPF) is a quite complex interior gateway |
dad92c30 OZ |
2483 | protocol. The current IPv4 version (OSPFv2) is defined in RFC 2328 |
2484 | <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt"> | |
2485 | and the current IPv6 version (OSPFv3) is defined in RFC 5340 | |
2486 | <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt"> | |
2487 | It's a link state (a.k.a. shortest path first) protocol -- each router maintains | |
2488 | a database describing the autonomous system's topology. Each participating | |
2489 | router has an identical copy of the database and all routers run the same | |
2490 | algorithm calculating a shortest path tree with themselves as a root. OSPF | |
2491 | chooses the least cost path as the best path. | |
2492 | ||
2493 | <p>In OSPF, the autonomous system can be split to several areas in order to | |
2494 | reduce the amount of resources consumed for exchanging the routing information | |
2495 | and to protect the other areas from incorrect routing data. Topology of the area | |
2496 | is hidden to the rest of the autonomous system. | |
2497 | ||
2498 | <p>Another very important feature of OSPF is that it can keep routing information | |
2499 | from other protocols (like Static or BGP) in its link state database as external | |
2500 | routes. Each external route can be tagged by the advertising router, making it | |
2501 | possible to pass additional information between routers on the boundary of the | |
2502 | autonomous system. | |
2503 | ||
2504 | <p>OSPF quickly detects topological changes in the autonomous system (such as | |
2505 | router interface failures) and calculates new loop-free routes after a short | |
2506 | period of convergence. Only a minimal amount of routing traffic is involved. | |
8fd12e6b | 2507 | |
3ca3e999 | 2508 | <p>Each router participating in OSPF routing periodically sends Hello messages |
dad92c30 OZ |
2509 | to all its interfaces. This allows neighbors to be discovered dynamically. Then |
2510 | the neighbors exchange theirs parts of the link state database and keep it | |
2511 | identical by flooding updates. The flooding process is reliable and ensures that | |
2512 | each router detects all changes. | |
8fd12e6b OF |
2513 | |
2514 | <sect1>Configuration | |
2515 | ||
dad92c30 OZ |
2516 | <p>In the main part of configuration, there can be multiple definitions of OSPF |
2517 | areas, each with a different id. These definitions includes many other switches | |
2518 | and multiple definitions of interfaces. Definition of interface may contain many | |
2519 | switches and constant definitions and list of neighbors on nonbroadcast | |
2520 | networks. | |
8fd12e6b OF |
2521 | |
2522 | <code> | |
088bc8ad | 2523 | protocol ospf <name> { |
1632f1fe | 2524 | rfc1583compat <switch>; |
178a197a | 2525 | instance id <num>; |
f623ab98 | 2526 | stub router <switch>; |
62eee823 | 2527 | tick <num>; |
e91f6960 | 2528 | ecmp <switch> [limit <num>]; |
145368f5 | 2529 | merge external <switch>; |
088bc8ad | 2530 | area <id> { |
2918e610 OZ |
2531 | stub; |
2532 | nssa; | |
bde872bb | 2533 | summary <switch>; |
2918e610 OZ |
2534 | default nssa <switch>; |
2535 | default cost <num>; | |
2536 | default cost2 <num>; | |
bde872bb OZ |
2537 | translator <switch>; |
2538 | translator stability <num>; | |
2539 | ||
16319aeb OF |
2540 | networks { |
2541 | <prefix>; | |
2542 | <prefix> hidden; | |
2543 | } | |
bde872bb OZ |
2544 | external { |
2545 | <prefix>; | |
2546 | <prefix> hidden; | |
2547 | <prefix> tag <num>; | |
2548 | } | |
38675202 OZ |
2549 | stubnet <prefix>; |
2550 | stubnet <prefix> { | |
2551 | hidden <switch>; | |
2552 | summary <switch>; | |
2553 | cost <num>; | |
2554 | } | |
0ec031f7 | 2555 | interface <interface pattern> [instance <num>] { |
088bc8ad | 2556 | cost <num>; |
e3bc10fd | 2557 | stub <switch>; |
088bc8ad | 2558 | hello <num>; |
a190e720 | 2559 | poll <num>; |
088bc8ad OF |
2560 | retransmit <num>; |
2561 | priority <num>; | |
2562 | wait <num>; | |
2563 | dead count <num>; | |
d8c7d9e8 | 2564 | dead <num>; |
48e5f32d | 2565 | secondary <switch>; |
94c42054 | 2566 | rx buffer [normal|large|<num>]; |
48e5f32d | 2567 | tx length <num>; |
919f5411 OZ |
2568 | type [broadcast|bcast|pointopoint|ptp| |
2569 | nonbroadcast|nbma|pointomultipoint|ptmp]; | |
70945cb6 | 2570 | link lsa suppression <switch>; |
a190e720 | 2571 | strict nonbroadcast <switch>; |
95127cbb | 2572 | real broadcast <switch>; |
8df02847 | 2573 | ptp netmask <switch>; |
e91f6960 | 2574 | check link <switch>; |
1ec52253 | 2575 | bfd <switch>; |
e91f6960 | 2576 | ecmp weight <num>; |
6ac4f87a OZ |
2577 | ttl security [<switch>; | tx only] |
2578 | tx class|dscp <num>; | |
2579 | tx priority <num>; | |
3242ab43 | 2580 | authentication [none|simple|cryptographic]; |
088bc8ad | 2581 | password "<text>"; |
b21f68b4 OZ |
2582 | password "<text>" { |
2583 | id <num>; | |
2584 | generate from "<date>"; | |
2585 | generate to "<date>"; | |
2586 | accept from "<date>"; | |
2587 | accept to "<date>"; | |
ea357b8b | 2588 | }; |
8fd12e6b | 2589 | neighbors { |
088bc8ad | 2590 | <ip>; |
a190e720 | 2591 | <ip> eligible; |
8fd12e6b OF |
2592 | }; |
2593 | }; | |
0ec031f7 | 2594 | virtual link <id> [instance <num>] { |
98ac6176 | 2595 | hello <num>; |
98ac6176 OF |
2596 | retransmit <num>; |
2597 | wait <num>; | |
2598 | dead count <num>; | |
d8c7d9e8 | 2599 | dead <num>; |
3242ab43 | 2600 | authentication [none|simple|cryptographic]; |
98ac6176 OF |
2601 | password "<text>"; |
2602 | }; | |
8fd12e6b OF |
2603 | }; |
2604 | } | |
2605 | </code> | |
2606 | ||
2607 | <descrip> | |
1632f1fe | 2608 | <tag>rfc1583compat <M>switch</M></tag> |
dad92c30 OZ |
2609 | This option controls compatibility of routing table calculation with |
2610 | RFC 1583 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. | |
2611 | Default value is no. | |
e91f6960 | 2612 | |
178a197a OZ |
2613 | <tag>instance id <m/num/</tag> |
2614 | When multiple OSPF protocol instances are active on the same links, they | |
2615 | should use different instance IDs to distinguish their packets. Although | |
2616 | it could be done on per-interface basis, it is often preferred to set | |
2617 | one instance ID to whole OSPF domain/topology (e.g., when multiple | |
2618 | instances are used to represent separate logical topologies on the same | |
2619 | physical network). This option specifies the default instance ID for all | |
2620 | interfaces of the OSPF instance. Note that this option, if used, must | |
2621 | precede interface definitions. Default value is 0. | |
2622 | ||
f623ab98 | 2623 | <tag>stub router <M>switch</M></tag> |
dad92c30 OZ |
2624 | This option configures the router to be a stub router, i.e., a router |
2625 | that participates in the OSPF topology but does not allow transit | |
2626 | traffic. In OSPFv2, this is implemented by advertising maximum metric | |
178a197a OZ |
2627 | for outgoing links. In OSPFv3, the stub router behavior is announced by |
2628 | clearing the R-bit in the router LSA. See RFC 6987 | |
2629 | <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6987.txt"> for | |
2630 | details. Default value is no. | |
f623ab98 | 2631 | |
e91f6960 | 2632 | <tag>tick <M>num</M></tag> |
dad92c30 OZ |
2633 | The routing table calculation and clean-up of areas' databases is not |
2634 | performed when a single link state change arrives. To lower the CPU | |
2635 | utilization, it's processed later at periodical intervals of <m/num/ | |
2636 | seconds. The default value is 1. | |
e91f6960 OZ |
2637 | |
2638 | <tag>ecmp <M>switch</M> [limit <M>number</M>]</tag> | |
dad92c30 OZ |
2639 | This option specifies whether OSPF is allowed to generate ECMP |
2640 | (equal-cost multipath) routes. Such routes are used when there are | |
2641 | several directions to the destination, each with the same (computed) | |
8465dccb | 2642 | cost. This option also allows to specify a limit on maximum number of |
dad92c30 OZ |
2643 | nexthops in one route. By default, ECMP is disabled. If enabled, |
2644 | default value of the limit is 16. | |
e91f6960 | 2645 | |
145368f5 OZ |
2646 | <tag>merge external <M>switch</M></tag> |
2647 | This option specifies whether OSPF should merge external routes from | |
2648 | different routers/LSAs for the same destination. When enabled together | |
2649 | with <cf/ecmp/, equal-cost external routes will be combined to multipath | |
2650 | routes in the same way as regular routes. When disabled, external routes | |
2651 | from different LSAs are treated as separate even if they represents the | |
2652 | same destination. Default value is no. | |
2653 | ||
8fd12e6b | 2654 | <tag>area <M>id</M></tag> |
dad92c30 OZ |
2655 | This defines an OSPF area with given area ID (an integer or an IPv4 |
2656 | address, similarly to a router ID). The most important area is the | |
2657 | backbone (ID 0) to which every other area must be connected. | |
8fd12e6b | 2658 | |
2918e610 | 2659 | <tag>stub</tag> |
dad92c30 OZ |
2660 | This option configures the area to be a stub area. External routes are |
2661 | not flooded into stub areas. Also summary LSAs can be limited in stub | |
2662 | areas (see option <cf/summary/). By default, the area is not a stub | |
2663 | area. | |
bde872bb | 2664 | |
2918e610 | 2665 | <tag>nssa</tag> |
dad92c30 OZ |
2666 | This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA |
2667 | is a variant of a stub area which allows a limited way of external route | |
2668 | propagation. Global external routes are not propagated into a NSSA, but | |
2669 | an external route can be imported into NSSA as a (area-wide) NSSA-LSA | |
2670 | (and possibly translated and/or aggregated on area boundary). By | |
2671 | default, the area is not NSSA. | |
bde872bb OZ |
2672 | |
2673 | <tag>summary <M>switch</M></tag> | |
dad92c30 OZ |
2674 | This option controls propagation of summary LSAs into stub or NSSA |
2675 | areas. If enabled, summary LSAs are propagated as usual, otherwise just | |
2676 | the default summary route (0.0.0.0/0) is propagated (this is sometimes | |
2677 | called totally stubby area). If a stub area has more area boundary | |
2678 | routers, propagating summary LSAs could lead to more efficient routing | |
2679 | at the cost of larger link state database. Default value is no. | |
bde872bb | 2680 | |
2918e610 | 2681 | <tag>default nssa <M>switch</M></tag> |
dad92c30 OZ |
2682 | When <cf/summary/ option is enabled, default summary route is no longer |
2683 | propagated to the NSSA. In that case, this option allows to originate | |
2684 | default route as NSSA-LSA to the NSSA. Default value is no. | |
2918e610 OZ |
2685 | |
2686 | <tag>default cost <M>num</M></tag> | |
dad92c30 OZ |
2687 | This option controls the cost of a default route propagated to stub and |
2688 | NSSA areas. Default value is 1000. | |
bde872bb | 2689 | |
2918e610 | 2690 | <tag>default cost2 <M>num</M></tag> |
dad92c30 OZ |
2691 | When a default route is originated as NSSA-LSA, its cost can use either |
2692 | type 1 or type 2 metric. This option allows to specify the cost of a | |
2693 | default route in type 2 metric. By default, type 1 metric (option | |
2694 | <cf/default cost/) is used. | |
2918e610 | 2695 | |
bde872bb | 2696 | <tag>translator <M>switch</M></tag> |
dad92c30 OZ |
2697 | This option controls translation of NSSA-LSAs into external LSAs. By |
2698 | default, one translator per NSSA is automatically elected from area | |
2699 | boundary routers. If enabled, this area boundary router would | |
2700 | unconditionally translate all NSSA-LSAs regardless of translator | |
2701 | election. Default value is no. | |
bde872bb OZ |
2702 | |
2703 | <tag>translator stability <M>num</M></tag> | |
dad92c30 OZ |
2704 | This option controls the translator stability interval (in seconds). |
2705 | When the new translator is elected, the old one keeps translating until | |
2706 | the interval is over. Default value is 40. | |
8fd12e6b | 2707 | |
16319aeb | 2708 | <tag>networks { <m/set/ }</tag> |
dad92c30 OZ |
2709 | Definition of area IP ranges. This is used in summary LSA origination. |
2710 | Hidden networks are not propagated into other areas. | |
16319aeb | 2711 | |
bde872bb | 2712 | <tag>external { <m/set/ }</tag> |
dad92c30 OZ |
2713 | Definition of external area IP ranges for NSSAs. This is used for |
2714 | NSSA-LSA translation. Hidden networks are not translated into external | |
2715 | LSAs. Networks can have configured route tag. | |
bde872bb | 2716 | |
38675202 | 2717 | <tag>stubnet <m/prefix/ { <m/options/ }</tag> |
dad92c30 OZ |
2718 | Stub networks are networks that are not transit networks between OSPF |
2719 | routers. They are also propagated through an OSPF area as a part of a | |
2720 | link state database. By default, BIRD generates a stub network record | |
2721 | for each primary network address on each OSPF interface that does not | |
2722 | have any OSPF neighbors, and also for each non-primary network address | |
2723 | on each OSPF interface. This option allows to alter a set of stub | |
2724 | networks propagated by this router. | |
2725 | ||
2726 | Each instance of this option adds a stub network with given network | |
2727 | prefix to the set of propagated stub network, unless option <cf/hidden/ | |
2728 | is used. It also suppresses default stub networks for given network | |
2729 | prefix. When option <cf/summary/ is used, also default stub networks | |
2730 | that are subnetworks of given stub network are suppressed. This might be | |
2731 | used, for example, to aggregate generated stub networks. | |
178a197a | 2732 | |
0ec031f7 | 2733 | <tag>interface <M>pattern</M> [instance <m/num/]</tag> |
dad92c30 OZ |
2734 | Defines that the specified interfaces belong to the area being defined. |
2735 | See <ref id="dsc-iface" name="interface"> common option for detailed | |
d7c06285 | 2736 | description. In OSPFv2, extended interface clauses are used, because |
178a197a OZ |
2737 | each network prefix is handled as a separate virtual interface. |
2738 | ||
2739 | You can specify alternative instance ID for the interface definition, | |
2740 | therefore it is possible to have several instances of that interface | |
2741 | with different options or even in different areas. For OSPFv2, | |
2742 | instance ID support is an extension (RFC 6549 | |
2743 | <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6549.txt">) and is | |
2744 | supposed to be set per-protocol. For OSPFv3, it is an integral feature. | |
0ec031f7 OZ |
2745 | |
2746 | <tag>virtual link <M>id</M> [instance <m/num/]</tag> | |
dad92c30 OZ |
2747 | Virtual link to router with the router id. Virtual link acts as a |
2748 | point-to-point interface belonging to backbone. The actual area is used | |
178a197a OZ |
2749 | as a transport area. This item cannot be in the backbone. Like with |
2750 | <cf/interface/ option, you could also use several virtual links to one | |
2751 | destination with different instance IDs. | |
98ac6176 | 2752 | |
8fd12e6b | 2753 | <tag>cost <M>num</M></tag> |
dad92c30 | 2754 | Specifies output cost (metric) of an interface. Default value is 10. |
8fd12e6b | 2755 | |
e3bc10fd | 2756 | <tag>stub <M>switch</M></tag> |
dad92c30 OZ |
2757 | If set to interface it does not listen to any packet and does not send |
2758 | any hello. Default value is no. | |
e3bc10fd | 2759 | |
8fd12e6b | 2760 | <tag>hello <M>num</M></tag> |
dad92c30 OZ |
2761 | Specifies interval in seconds between sending of Hello messages. Beware, |
2762 | all routers on the same network need to have the same hello interval. | |
2763 | Default value is 10. | |
8fd12e6b | 2764 | |
a190e720 | 2765 | <tag>poll <M>num</M></tag> |
dad92c30 OZ |
2766 | Specifies interval in seconds between sending of Hello messages for some |
2767 | neighbors on NBMA network. Default value is 20. | |
a190e720 | 2768 | |
8fd12e6b | 2769 | <tag>retransmit <M>num</M></tag> |
dad92c30 OZ |
2770 | Specifies interval in seconds between retransmissions of unacknowledged |
2771 | updates. Default value is 5. | |
8fd12e6b | 2772 | |
dad92c30 | 2773 | <tag>priority <M>num</M></tag> |
0a505706 OZ |
2774 | On every multiple access network (e.g., the Ethernet) Designated Router |
2775 | and Backup Designated router are elected. These routers have some special | |
dad92c30 OZ |
2776 | functions in the flooding process. Higher priority increases preferences |
2777 | in this election. Routers with priority 0 are not eligible. Default | |
2778 | value is 1. | |
8fd12e6b OF |
2779 | |
2780 | <tag>wait <M>num</M></tag> | |
dad92c30 | 2781 | After start, router waits for the specified number of seconds between |
178a197a OZ |
2782 | starting election and building adjacency. Default value is 4*<m/hello/. |
2783 | ||
8fd12e6b | 2784 | <tag>dead count <M>num</M></tag> |
dad92c30 OZ |
2785 | When the router does not receive any messages from a neighbor in |
2786 | <m/dead count/*<m/hello/ seconds, it will consider the neighbor down. | |
8fd12e6b | 2787 | |
d8c7d9e8 | 2788 | <tag>dead <M>num</M></tag> |
dad92c30 OZ |
2789 | When the router does not receive any messages from a neighbor in |
2790 | <m/dead/ seconds, it will consider the neighbor down. If both directives | |
fff7498d | 2791 | <cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precedence. |
48e5f32d OZ |
2792 | |
2793 | <tag>secondary <M>switch</M></tag> | |
2794 | On BSD systems, older versions of BIRD supported OSPFv2 only for the | |
2795 | primary IP address of an interface, other IP ranges on the interface | |
2796 | were handled as stub networks. Since v1.4.1, regular operation on | |
2797 | secondary IP addresses is supported, but disabled by default for | |
2798 | compatibility. This option allows to enable it. The option is a | |
2799 | transitional measure, will be removed in the next major release as the | |
2800 | behavior will be changed. On Linux systems, the option is irrelevant, as | |
2801 | operation on non-primary addresses is already the regular behavior. | |
d8c7d9e8 | 2802 | |
94c42054 | 2803 | <tag>rx buffer <M>num</M></tag> |
48e5f32d OZ |
2804 | This option allows to specify the size of buffers used for packet |
2805 | processing. The buffer size should be bigger than maximal size of any | |
2806 | packets. By default, buffers are dynamically resized as needed, but a | |
2807 | fixed value could be specified. Value <cf/large/ means maximal allowed | |
2808 | packet size - 65535. | |
2809 | ||
2810 | <tag>tx length <M>num</M></tag> | |
2811 | Transmitted OSPF messages that contain large amount of information are | |
2812 | segmented to separate OSPF packets to avoid IP fragmentation. This | |
2813 | option specifies the soft ceiling for the length of generated OSPF | |
2814 | packets. Default value is the MTU of the network interface. Note that | |
2815 | larger OSPF packets may still be generated if underlying OSPF messages | |
2816 | cannot be splitted (e.g. when one large LSA is propagated). | |
94c42054 | 2817 | |
919f5411 | 2818 | <tag>type broadcast|bcast</tag> |
dad92c30 OZ |
2819 | BIRD detects a type of a connected network automatically, but sometimes |
2820 | it's convenient to force use of a different type manually. On broadcast | |
2821 | networks (like ethernet), flooding and Hello messages are sent using | |
2822 | multicasts (a single packet for all the neighbors). A designated router | |
2823 | is elected and it is responsible for synchronizing the link-state | |
2824 | databases and originating network LSAs. This network type cannot be used | |
2825 | on physically NBMA networks and on unnumbered networks (networks without | |
2826 | proper IP prefix). | |
919f5411 OZ |
2827 | |
2828 | <tag>type pointopoint|ptp</tag> | |
dad92c30 OZ |
2829 | Point-to-point networks connect just 2 routers together. No election is |
2830 | performed and no network LSA is originated, which makes it simpler and | |
2831 | faster to establish. This network type is useful not only for physically | |
2832 | PtP ifaces (like PPP or tunnels), but also for broadcast networks used | |
2833 | as PtP links. This network type cannot be used on physically NBMA | |
2834 | networks. | |
919f5411 OZ |
2835 | |
2836 | <tag>type nonbroadcast|nbma</tag> | |
dad92c30 OZ |
2837 | On NBMA networks, the packets are sent to each neighbor separately |
2838 | because of lack of multicast capabilities. Like on broadcast networks, | |
2839 | a designated router is elected, which plays a central role in propagation | |
2840 | of LSAs. This network type cannot be used on unnumbered networks. | |
919f5411 OZ |
2841 | |
2842 | <tag>type pointomultipoint|ptmp</tag> | |
dad92c30 OZ |
2843 | This is another network type designed to handle NBMA networks. In this |
2844 | case the NBMA network is treated as a collection of PtP links. This is | |
2845 | useful if not every pair of routers on the NBMA network has direct | |
2846 | communication, or if the NBMA network is used as an (possibly | |
2847 | unnumbered) PtP link. | |
8fd12e6b | 2848 | |
70945cb6 OZ |
2849 | <tag>link lsa suppression <m/switch/</tag> |
2850 | In OSPFv3, link LSAs are generated for each link, announcing link-local | |
2851 | IPv6 address of the router to its local neighbors. These are useless on | |
2852 | PtP or PtMP networks and this option allows to suppress the link LSA | |
2853 | origination for such interfaces. The option is ignored on other than PtP | |
2854 | or PtMP interfaces. Default value is no. | |
2855 | ||
2856 | <tag>strict nonbroadcast <m/switch/</tag> | |
dad92c30 | 2857 | If set, don't send hello to any undefined neighbor. This switch is |
70945cb6 | 2858 | ignored on other than NBMA or PtMP interfaces. Default value is no. |
8fd12e6b | 2859 | |
95127cbb | 2860 | <tag>real broadcast <m/switch/</tag> |
dad92c30 OZ |
2861 | In <cf/type broadcast/ or <cf/type ptp/ network configuration, OSPF |
2862 | packets are sent as IP multicast packets. This option changes the | |
2863 | behavior to using old-fashioned IP broadcast packets. This may be useful | |
2864 | as a workaround if IP multicast for some reason does not work or does | |
2865 | not work reliably. This is a non-standard option and probably is not | |
2866 | interoperable with other OSPF implementations. Default value is no. | |
95127cbb | 2867 | |
8df02847 | 2868 | <tag>ptp netmask <m/switch/</tag> |
dad92c30 OZ |
2869 | In <cf/type ptp/ network configurations, OSPFv2 implementations should |
2870 | ignore received netmask field in hello packets and should send hello | |
2871 | packets with zero netmask field on unnumbered PtP links. But some OSPFv2 | |
2872 | implementations perform netmask checking even for PtP links. This option | |
2873 | specifies whether real netmask will be used in hello packets on <cf/type | |
2874 | ptp/ interfaces. You should ignore this option unless you meet some | |
2875 | compatibility problems related to this issue. Default value is no for | |
2876 | unnumbered PtP links, yes otherwise. | |
8df02847 | 2877 | |
391931d4 | 2878 | <tag>check link <M>switch</M></tag> |
dad92c30 OZ |
2879 | If set, a hardware link state (reported by OS) is taken into consideration. |
2880 | When a link disappears (e.g. an ethernet cable is unplugged), neighbors | |
2881 | are immediately considered unreachable and only the address of the iface | |
2882 | (instead of whole network prefix) is propagated. It is possible that | |
2883 | some hardware drivers or platforms do not implement this feature. | |
2884 | Default value is no. | |
e91f6960 | 2885 | |
1ec52253 OZ |
2886 | <tag>bfd <M>switch</M></tag> |
2887 | OSPF could use BFD protocol as an advisory mechanism for neighbor | |
2888 | liveness and failure detection. If enabled, BIRD setups a BFD session | |
2889 | for each OSPF neighbor and tracks its liveness by it. This has an | |
2890 | advantage of an order of magnitude lower detection times in case of | |
2891 | failure. Note that BFD protocol also has to be configured, see | |
2892 | <ref id="sect-bfd" name="BFD"> section for details. Default value is no. | |
2893 | ||
6ac4f87a | 2894 | <tag>ttl security [<m/switch/ | tx only]</tag> |
dad92c30 OZ |
2895 | TTL security is a feature that protects routing protocols from remote |
2896 | spoofed packets by using TTL 255 instead of TTL 1 for protocol packets | |
2897 | destined to neighbors. Because TTL is decremented when packets are | |
2898 | forwarded, it is non-trivial to spoof packets with TTL 255 from remote | |
2899 | locations. Note that this option would interfere with OSPF virtual | |
2900 | links. | |
2901 | ||
2902 | If this option is enabled, the router will send OSPF packets with TTL | |
2903 | 255 and drop received packets with TTL less than 255. If this option si | |
2904 | set to <cf/tx only/, TTL 255 is used for sent packets, but is not | |
2905 | checked for received packets. Default value is no. | |
6ac4f87a | 2906 | |
ef4a50be | 2907 | <tag>tx class|dscp|priority <m/num/</tag> |
dad92c30 OZ |
2908 | These options specify the ToS/DiffServ/Traffic class/Priority of the |
2909 | outgoing OSPF packets. See <ref id="dsc-prio" name="tx class"> common | |
2910 | option for detailed description. | |
ef4a50be | 2911 | |
e91f6960 | 2912 | <tag>ecmp weight <M>num</M></tag> |
dad92c30 OZ |
2913 | When ECMP (multipath) routes are allowed, this value specifies a |
2914 | relative weight used for nexthops going through the iface. Allowed | |
2915 | values are 1-256. Default value is 1. | |
391931d4 | 2916 | |
4e8ec666 | 2917 | <tag>authentication none</tag> |
dad92c30 | 2918 | No passwords are sent in OSPF packets. This is the default value. |
8fd12e6b | 2919 | |
4e8ec666 | 2920 | <tag>authentication simple</tag> |
dad92c30 OZ |
2921 | Every packet carries 8 bytes of password. Received packets lacking this |
2922 | password are ignored. This authentication mechanism is very weak. | |
8fd12e6b | 2923 | |
ea357b8b | 2924 | <tag>authentication cryptographic</tag> |
dad92c30 OZ |
2925 | 16-byte long MD5 digest is appended to every packet. For the digest |
2926 | generation 16-byte long passwords are used. Those passwords are not sent | |
2927 | via network, so this mechanism is quite secure. Packets can still be | |
2928 | read by an attacker. | |
ea357b8b | 2929 | |
5a203dac | 2930 | <tag>password "<M>text</M>"</tag> |
dad92c30 OZ |
2931 | An 8-byte or 16-byte password used for authentication. See |
2932 | <ref id="dsc-pass" name="password"> common option for detailed | |
2933 | description. | |
8fd12e6b | 2934 | |
5a203dac | 2935 | <tag>neighbors { <m/set/ } </tag> |
dad92c30 OZ |
2936 | A set of neighbors to which Hello messages on NBMA or PtMP networks are |
2937 | to be sent. For NBMA networks, some of them could be marked as eligible. | |
2938 | In OSPFv3, link-local addresses should be used, using global ones is | |
2939 | possible, but it is nonstandard and might be problematic. And definitely, | |
2940 | link-local and global addresses should not be mixed. | |
8fd12e6b OF |
2941 | </descrip> |
2942 | ||
2943 | <sect1>Attributes | |
2944 | ||
c27b2449 | 2945 | <p>OSPF defines four route attributes. Each internal route has a <cf/metric/. |
8fd12e6b | 2946 | |
dad92c30 OZ |
2947 | <p>Metric is ranging from 1 to infinity (65535). External routes use |
2948 | <cf/metric type 1/ or <cf/metric type 2/. A <cf/metric of type 1/ is comparable | |
2949 | with internal <cf/metric/, a <cf/metric of type 2/ is always longer than any | |
2950 | <cf/metric of type 1/ or any <cf/internal metric/. <cf/Internal metric/ or | |
2951 | <cf/metric of type 1/ is stored in attribute <cf/ospf_metric1/, <cf/metric type | |
2952 | 2/ is stored in attribute <cf/ospf_metric2/. If you specify both metrics only | |
2953 | metric1 is used. | |
2954 | ||
2955 | <p>Each external route can also carry attribute <cf/ospf_tag/ which is a 32-bit | |
2956 | integer which is used when exporting routes to other protocols; otherwise, it | |
2957 | doesn't affect routing inside the OSPF domain at all. The fourth attribute | |
2958 | <cf/ospf_router_id/ is a router ID of the router advertising that route / | |
2959 | network. This attribute is read-only. Default is <cf/ospf_metric2 = 10000/ and | |
2960 | <cf/ospf_tag = 0/. | |
8fd12e6b | 2961 | |
dad92c30 | 2962 | <sect1>Example |
8fd12e6b | 2963 | |
9637c7c0 | 2964 | <p><code> |
8fd12e6b | 2965 | protocol ospf MyOSPF { |
dad92c30 OZ |
2966 | rfc1583compat yes; |
2967 | tick 2; | |
76c7efec OF |
2968 | export filter { |
2969 | if source = RTS_BGP then { | |
2970 | ospf_metric1 = 100; | |
2971 | accept; | |
2972 | } | |
98ac6176 | 2973 | reject; |
f434d191 | 2974 | }; |
8fd12e6b | 2975 | area 0.0.0.0 { |
8fd12e6b OF |
2976 | interface "eth*" { |
2977 | cost 11; | |
2978 | hello 15; | |
2979 | priority 100; | |
2980 | retransmit 7; | |
2981 | authentication simple; | |
2982 | password "aaa"; | |
2983 | }; | |
2984 | interface "ppp*" { | |
2985 | cost 100; | |
3b16080c | 2986 | authentication cryptographic; |
f434d191 OZ |
2987 | password "abc" { |
2988 | id 1; | |
2989 | generate to "22-04-2003 11:00:06"; | |
2990 | accept from "17-01-2001 12:01:05"; | |
2991 | }; | |
2992 | password "def" { | |
2993 | id 2; | |
2994 | generate to "22-07-2005 17:03:21"; | |
2995 | accept from "22-02-2001 11:34:06"; | |
3b16080c | 2996 | }; |
8fd12e6b | 2997 | }; |
e3bc10fd OF |
2998 | interface "arc0" { |
2999 | cost 10; | |
3000 | stub yes; | |
3001 | }; | |
3b16080c | 3002 | interface "arc1"; |
8fd12e6b OF |
3003 | }; |
3004 | area 120 { | |
3005 | stub yes; | |
98ac6176 OF |
3006 | networks { |
3007 | 172.16.1.0/24; | |
3008 | 172.16.2.0/24 hidden; | |
3009 | } | |
8fd12e6b OF |
3010 | interface "-arc0" , "arc*" { |
3011 | type nonbroadcast; | |
3012 | authentication none; | |
e3bc10fd | 3013 | strict nonbroadcast yes; |
a190e720 OF |
3014 | wait 120; |
3015 | poll 40; | |
3016 | dead count 8; | |
8fd12e6b | 3017 | neighbors { |
a190e720 | 3018 | 192.168.120.1 eligible; |
8fd12e6b OF |
3019 | 192.168.120.2; |
3020 | 192.168.120.10; | |
3021 | }; | |
3022 | }; | |
3023 | }; | |
3024 | } | |
3025 | </code> | |
3026 | ||
dad92c30 | 3027 | |
371adba6 | 3028 | <sect>Pipe |
1b55b1a3 | 3029 | |
371adba6 | 3030 | <sect1>Introduction |
a2a3ced8 | 3031 | |
dad92c30 OZ |
3032 | <p>The Pipe protocol serves as a link between two routing tables, allowing |
3033 | routes to be passed from a table declared as primary (i.e., the one the pipe is | |
3034 | connected to using the <cf/table/ configuration keyword) to the secondary one | |
3035 | (declared using <cf/peer table/) and vice versa, depending on what's allowed by | |
3036 | the filters. Export filters control export of routes from the primary table to | |
3037 | the secondary one, import filters control the opposite direction. | |
3038 | ||
3039 | <p>The Pipe protocol may work in the transparent mode mode or in the opaque | |
3040 | mode. In the transparent mode, the Pipe protocol retransmits all routes from | |
3041 | one table to the other table, retaining their original source and attributes. | |
3042 | If import and export filters are set to accept, then both tables would have | |
3043 | the same content. The transparent mode is the default mode. | |
3044 | ||
3045 | <p>In the opaque mode, the Pipe protocol retransmits optimal route from one | |
3046 | table to the other table in a similar way like other protocols send and receive | |
3047 | routes. Retransmitted route will have the source set to the Pipe protocol, which | |
3048 | may limit access to protocol specific route attributes. This mode is mainly for | |
3049 | compatibility, it is not suggested for new configs. The mode can be changed by | |
f98e2915 OZ |
3050 | <tt/mode/ option. |
3051 | ||
dad92c30 OZ |
3052 | <p>The primary use of multiple routing tables and the Pipe protocol is for |
3053 | policy routing, where handling of a single packet doesn't depend only on its | |
3054 | destination address, but also on its source address, source interface, protocol | |
3055 | type and other similar parameters. In many systems (Linux being a good example), | |
3056 | the kernel allows to enforce routing policies by defining routing rules which | |
3057 | choose one of several routing tables to be used for a packet according to its | |
3058 | parameters. Setting of these rules is outside the scope of BIRD's work (on | |
3059 | Linux, you can use the <tt/ip/ command), but you can create several routing | |
3060 | tables in BIRD, connect them to the kernel ones, use filters to control which | |
3061 | routes appear in which tables and also you can employ the Pipe protocol for | |
3062 | exporting a selected subset of one table to another one. | |
a2a3ced8 | 3063 | |
371adba6 | 3064 | <sect1>Configuration |
a2a3ced8 MM |
3065 | |
3066 | <p><descrip> | |
dad92c30 OZ |
3067 | <tag>peer table <m/table/</tag> |
3068 | Defines secondary routing table to connect to. The primary one is | |
3069 | selected by the <cf/table/ keyword. | |
f98e2915 | 3070 | |
dad92c30 OZ |
3071 | <tag>mode opaque|transparent</tag> |
3072 | Specifies the mode for the pipe to work in. Default is transparent. | |
a2a3ced8 MM |
3073 | </descrip> |
3074 | ||
371adba6 | 3075 | <sect1>Attributes |
a2a3ced8 MM |
3076 | |
3077 | <p>The Pipe protocol doesn't define any route attributes. | |
3078 | ||
371adba6 | 3079 | <sect1>Example |
a2a3ced8 | 3080 | |
dad92c30 OZ |
3081 | <p>Let's consider a router which serves as a boundary router of two different |
3082 | autonomous systems, each of them connected to a subset of interfaces of the | |
3083 | router, having its own exterior connectivity and wishing to use the other AS as | |
3084 | a backup connectivity in case of outage of its own exterior line. | |
3085 | ||
3086 | <p>Probably the simplest solution to this situation is to use two routing tables | |
3087 | (we'll call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that | |
3088 | packets having arrived from interfaces belonging to the first AS will be routed | |
3089 | according to <cf/as1/ and similarly for the second AS. Thus we have split our | |
3090 | router to two logical routers, each one acting on its own routing table, having | |
3091 | its own routing protocols on its own interfaces. In order to use the other AS's | |
3092 | routes for backup purposes, we can pass the routes between the tables through a | |
3093 | Pipe protocol while decreasing their preferences and correcting their BGP paths | |
3094 | to reflect the AS boundary crossing. | |
a2a3ced8 MM |
3095 | |
3096 | <code> | |
3097 | table as1; # Define the tables | |
3098 | table as2; | |
3099 | ||
3100 | protocol kernel kern1 { # Synchronize them with the kernel | |
3101 | table as1; | |
3102 | kernel table 1; | |
3103 | } | |
3104 | ||
3105 | protocol kernel kern2 { | |
3106 | table as2; | |
3107 | kernel table 2; | |
3108 | } | |
3109 | ||
3110 | protocol bgp bgp1 { # The outside connections | |
3111 | table as1; | |
3112 | local as 1; | |
3113 | neighbor 192.168.0.1 as 1001; | |
3114 | export all; | |
3115 | import all; | |
3116 | } | |
3117 | ||
3118 | protocol bgp bgp2 { | |
3119 | table as2; | |
3120 | local as 2; | |
3121 | neighbor 10.0.0.1 as 1002; | |
3122 | export all; | |
3123 | import all; | |
3124 | } | |
3125 | ||
3126 | protocol pipe { # The Pipe | |
3127 | table as1; | |
3128 | peer table as2; | |
3129 | export filter { | |
3130 | if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks | |
3131 | if preference>10 then preference = preference-10; | |
3132 | if source=RTS_BGP then bgp_path.prepend(1); | |
3133 | accept; | |
3134 | } | |
3135 | reject; | |
3136 | }; | |
3137 | import filter { | |
3138 | if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks | |
3139 | if preference>10 then preference = preference-10; | |
3140 | if source=RTS_BGP then bgp_path.prepend(2); | |
3141 | accept; | |
3142 | } | |
3143 | reject; | |
3144 | }; | |
3145 | } | |
3146 | </code> | |
3147 | ||
dad92c30 | 3148 | |
6bcef225 OZ |
3149 | <sect>RAdv |
3150 | ||
3151 | <sect1>Introduction | |
3152 | ||
dad92c30 OZ |
3153 | <p>The RAdv protocol is an implementation of Router Advertisements, which are |
3154 | used in the IPv6 stateless autoconfiguration. IPv6 routers send (in irregular | |
3155 | time intervals or as an answer to a request) advertisement packets to connected | |
3156 | networks. These packets contain basic information about a local network (e.g. a | |
3157 | list of network prefixes), which allows network hosts to autoconfigure network | |
3158 | addresses and choose a default route. BIRD implements router behavior as defined | |
3159 | in RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt"> | |
0e224d59 OZ |
3160 | and also the DNS extensions from |
3161 | RFC 6106<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt">. | |
6bcef225 OZ |
3162 | |
3163 | <sect1>Configuration | |
3164 | ||
dad92c30 OZ |
3165 | <p>There are several classes of definitions in RAdv configuration -- interface |
3166 | definitions, prefix definitions and DNS definitions: | |
6bcef225 OZ |
3167 | |
3168 | <descrip> | |
dad92c30 | 3169 | <tag>interface <m/pattern [, ...]/ { <m/options/ }</tag> |
6bcef225 OZ |
3170 | Interface definitions specify a set of interfaces on which the |
3171 | protocol is activated and contain interface specific options. | |
3172 | See <ref id="dsc-iface" name="interface"> common options for | |
3173 | detailed description. | |
3174 | ||
0e224d59 | 3175 | <tag>prefix <m/prefix/ { <m/options/ }</tag> |
dad92c30 OZ |
3176 | Prefix definitions allow to modify a list of advertised prefixes. By |
3177 | default, the advertised prefixes are the same as the network prefixes | |
3178 | assigned to the interface. For each network prefix, the matching prefix | |
3179 | definition is found and its options are used. If no matching prefix | |
3180 | definition is found, the prefix is used with default options. | |
3181 | ||
3182 | Prefix definitions can be either global or interface-specific. The | |
3183 | second ones are part of interface options. The prefix definition | |
3184 | matching is done in the first-match style, when interface-specific | |
3185 | definitions are processed before global definitions. As expected, the | |
3186 | prefix definition is matching if the network prefix is a subnet of the | |
3187 | prefix in prefix definition. | |
0e224d59 OZ |
3188 | |
3189 | <tag>rdnss { <m/options/ }</tag> | |
dad92c30 OZ |
3190 | RDNSS definitions allow to specify a list of advertised recursive DNS |
3191 | servers together with their options. As options are seldom necessary, | |
3192 | there is also a short variant <cf>rdnss <m/address/</cf> that just | |
3193 | specifies one DNS server. Multiple definitions are cumulative. RDNSS | |
3194 | definitions may also be interface-specific when used inside interface | |
3195 | options. By default, interface uses both global and interface-specific | |
0e224d59 OZ |
3196 | options, but that can be changed by <cf/rdnss local/ option. |
3197 | ||
3198 | <tag>dnssl { <m/options/ }</tag> | |
dad92c30 OZ |
3199 | DNSSL definitions allow to specify a list of advertised DNS search |
3200 | domains together with their options. Like <cf/rdnss/ above, multiple | |
3201 | definitions are cumulative, they can be used also as interface-specific | |
3202 | options and there is a short variant <cf>dnssl <m/domain/</cf> that just | |
3203 | specifies one DNS search domain. | |
36da2857 OZ |
3204 | |
3205 | <label id="dsc-trigger"> <tag>trigger <m/prefix/</tag> | |
dad92c30 OZ |
3206 | RAdv protocol could be configured to change its behavior based on |
3207 | availability of routes. When this option is used, the protocol waits in | |
3208 | suppressed state until a <it/trigger route/ (for the specified network) | |
3209 | is exported to the protocol, the protocol also returnsd to suppressed | |
3210 | state if the <it/trigger route/ disappears. Note that route export | |
3211 | depends on specified export filter, as usual. This option could be used, | |
3212 | e.g., for handling failover in multihoming scenarios. | |
3213 | ||
3214 | During suppressed state, router advertisements are generated, but with | |
3215 | some fields zeroed. Exact behavior depends on which fields are zeroed, | |
3216 | this can be configured by <cf/sensitive/ option for appropriate | |
3217 | fields. By default, just <cf/default lifetime/ (also called <cf/router | |
3218 | lifetime/) is zeroed, which means hosts cannot use the router as a | |
3219 | default router. <cf/preferred lifetime/ and <cf/valid lifetime/ could | |
3220 | also be configured as <cf/sensitive/ for a prefix, which would cause | |
3221 | autoconfigured IPs to be deprecated or even removed. | |
6bcef225 OZ |
3222 | </descrip> |
3223 | ||
3224 | <p>Interface specific options: | |
3225 | ||
3226 | <descrip> | |
3227 | <tag>max ra interval <m/expr/</tag> | |
dad92c30 OZ |
3228 | Unsolicited router advertisements are sent in irregular time intervals. |
3229 | This option specifies the maximum length of these intervals, in seconds. | |
3230 | Valid values are 4-1800. Default: 600 | |
6bcef225 OZ |
3231 | |
3232 | <tag>min ra interval <m/expr/</tag> | |
dad92c30 OZ |
3233 | This option specifies the minimum length of that intervals, in seconds. |
3234 | Must be at least 3 and at most 3/4 * <cf/max ra interval/. Default: | |
3235 | about 1/3 * <cf/max ra interval/. | |
6bcef225 OZ |
3236 | |
3237 | <tag>min delay <m/expr/</tag> | |
dad92c30 OZ |
3238 | The minimum delay between two consecutive router advertisements, in |
3239 | seconds. Default: 3 | |
6bcef225 OZ |
3240 | |
3241 | <tag>managed <m/switch/</tag> | |
dad92c30 OZ |
3242 | This option specifies whether hosts should use DHCPv6 for IP address |
3243 | configuration. Default: no | |
6bcef225 OZ |
3244 | |
3245 | <tag>other config <m/switch/</tag> | |
dad92c30 OZ |
3246 | This option specifies whether hosts should use DHCPv6 to receive other |
3247 | configuration information. Default: no | |
6bcef225 OZ |
3248 | |
3249 | <tag>link mtu <m/expr/</tag> | |
dad92c30 OZ |
3250 | This option specifies which value of MTU should be used by hosts. 0 |
3251 | means unspecified. Default: 0 | |
6bcef225 OZ |
3252 | |
3253 | <tag>reachable time <m/expr/</tag> | |
dad92c30 OZ |
3254 | This option specifies the time (in milliseconds) how long hosts should |
3255 | assume a neighbor is reachable (from the last confirmation). Maximum is | |
3256 | 3600000, 0 means unspecified. Default 0. | |
6bcef225 OZ |
3257 | |
3258 | <tag>retrans timer <m/expr/</tag> | |
dad92c30 OZ |
3259 | This option specifies the time (in milliseconds) how long hosts should |
3260 | wait before retransmitting Neighbor Solicitation messages. 0 means | |
3261 | unspecified. Default 0. | |
6bcef225 OZ |
3262 | |
3263 | <tag>current hop limit <m/expr/</tag> | |
dad92c30 OZ |
3264 | This option specifies which value of Hop Limit should be used by |
3265 | hosts. Valid values are 0-255, 0 means unspecified. Default: 64 | |
6bcef225 | 3266 | |
36da2857 | 3267 | <tag>default lifetime <m/expr/ [sensitive <m/switch/]</tag> |
dad92c30 OZ |
3268 | This option specifies the time (in seconds) how long (after the receipt |
3269 | of RA) hosts may use the router as a default router. 0 means do not use | |
3270 | as a default router. For <cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">. | |
3271 | Default: 3 * <cf/max ra interval/, <cf/sensitive/ yes. | |
0e224d59 | 3272 | |
75148289 OZ |
3273 | <tag>default preference low|medium|high</tag> |
3274 | This option specifies the Default Router Preference value to advertise | |
3275 | to hosts. Default: medium. | |
3276 | ||
cf98be7b | 3277 | <tag>rdnss local <m/switch/</tag> |
0e224d59 | 3278 | Use only local (interface-specific) RDNSS definitions for this |
dad92c30 OZ |
3279 | interface. Otherwise, both global and local definitions are used. Could |
3280 | also be used to disable RDNSS for given interface if no local definitons | |
3281 | are specified. Default: no. | |
0e224d59 | 3282 | |
cf98be7b | 3283 | <tag>dnssl local <m/switch/</tag> |
dad92c30 OZ |
3284 | Use only local DNSSL definitions for this interface. See <cf/rdnss local/ |
3285 | option above. Default: no. | |
6bcef225 OZ |
3286 | </descrip> |
3287 | ||
3288 | ||
3289 | <p>Prefix specific options: | |
3290 | ||
3291 | <descrip> | |
d214ae4f OZ |
3292 | <tag>skip <m/switch/</tag> |
3293 | This option allows to specify that given prefix should not be | |
dad92c30 OZ |
3294 | advertised. This is useful for making exceptions from a default policy |
3295 | of advertising all prefixes. Note that for withdrawing an already | |
3296 | advertised prefix it is more useful to advertise it with zero valid | |
3297 | lifetime. Default: no | |
d214ae4f | 3298 | |
6bcef225 | 3299 | <tag>onlink <m/switch/</tag> |
dad92c30 OZ |
3300 | This option specifies whether hosts may use the advertised prefix for |
3301 | onlink determination. Default: yes | |
6bcef225 OZ |
3302 | |
3303 | <tag>autonomous <m/switch/</tag> | |
dad92c30 OZ |
3304 | This option specifies whether hosts may use the advertised prefix for |
3305 | stateless autoconfiguration. Default: yes | |
6bcef225 | 3306 | |
36da2857 | 3307 | <tag>valid lifetime <m/expr/ [sensitive <m/switch/]</tag> |
dad92c30 OZ |
3308 | This option specifies the time (in seconds) how long (after the |
3309 | receipt of RA) the prefix information is valid, i.e., autoconfigured | |
3310 | IP addresses can be assigned and hosts with that IP addresses are | |
3311 | considered directly reachable. 0 means the prefix is no longer | |
3312 | valid. For <cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">. | |
3313 | Default: 86400 (1 day), <cf/sensitive/ no. | |
6bcef225 | 3314 | |
36da2857 | 3315 | <tag>preferred lifetime <m/expr/ [sensitive <m/switch/]</tag> |
dad92c30 OZ |
3316 | This option specifies the time (in seconds) how long (after the |
3317 | receipt of RA) IP addresses generated from the prefix using stateless | |
3318 | autoconfiguration remain preferred. For <cf/sensitive/ option, | |
3319 | see <ref id="dsc-trigger" name="trigger">. Default: 14400 (4 hours), | |
3320 | <cf/sensitive/ no. | |
6bcef225 OZ |
3321 | </descrip> |
3322 | ||
0e224d59 OZ |
3323 | |
3324 | <p>RDNSS specific options: | |
3325 | ||
3326 | <descrip> | |
3327 | <tag>ns <m/address/</tag> | |
dad92c30 OZ |
3328 | This option specifies one recursive DNS server. Can be used multiple |
3329 | times for multiple servers. It is mandatory to have at least one | |
3330 | <cf/ns/ option in <cf/rdnss/ definition. | |
0e224d59 OZ |
3331 | |
3332 | <tag>lifetime [mult] <m/expr/</tag> | |
dad92c30 OZ |
3333 | This option specifies the time how long the RDNSS information may be |
3334 | used by clients after the receipt of RA. It is expressed either in | |
3335 | seconds or (when <cf/mult/ is used) in multiples of <cf/max ra | |
3336 | interval/. Note that RDNSS information is also invalidated when | |
3337 | <cf/default lifetime/ expires. 0 means these addresses are no longer | |
3338 | valid DNS servers. Default: 3 * <cf/max ra interval/. | |
0e224d59 OZ |
3339 | </descrip> |
3340 | ||
3341 | ||
3342 | <p>DNSSL specific options: | |
3343 | ||
3344 | <descrip> | |
3345 | <tag>domain <m/address/</tag> | |
dad92c30 OZ |
3346 | This option specifies one DNS search domain. Can be used multiple times |
3347 | for multiple domains. It is mandatory to have at least one <cf/domain/ | |
3348 | option in <cf/dnssl/ definition. | |
0e224d59 OZ |
3349 | |
3350 | <tag>lifetime [mult] <m/expr/</tag> | |
dad92c30 OZ |
3351 | This option specifies the time how long the DNSSL information may be |
3352 | used by clients after the receipt of RA. Details are the same as for | |
3353 | RDNSS <cf/lifetime/ option above. Default: 3 * <cf/max ra interval/. | |
0e224d59 OZ |
3354 | </descrip> |
3355 | ||
3356 | ||
6bcef225 OZ |
3357 | <sect1>Example |
3358 | ||
3359 | <p><code> | |
3360 | protocol radv { | |
3361 | interface "eth2" { | |
3362 | max ra interval 5; # Fast failover with more routers | |
3363 | managed yes; # Using DHCPv6 on eth2 | |
3364 | prefix ::/0 { | |
3365 | autonomous off; # So do not autoconfigure any IP | |
3366 | }; | |
3367 | }; | |
3368 | ||
3369 | interface "eth*"; # No need for any other options | |
3370 | ||
3371 | prefix 2001:0DB8:1234::/48 { | |
3372 | preferred lifetime 0; # Deprecated address range | |
3373 | }; | |
3374 | ||
3375 | prefix 2001:0DB8:2000::/48 { | |
3376 | autonomous off; # Do not autoconfigure | |
3377 | }; | |
fc06fb62 OZ |
3378 | |
3379 | rdnss 2001:0DB8:1234::10; # Short form of RDNSS | |
3380 | ||
3381 | rdnss { | |
3382 | lifetime mult 10; | |
3383 | ns 2001:0DB8:1234::11; | |
3384 | ns 2001:0DB8:1234::12; | |
3385 | }; | |
3386 | ||
3387 | dnssl { | |
3388 | lifetime 3600; | |
3389 | domain "abc.com"; | |
3390 | domain "xyz.com"; | |
3391 | }; | |
6bcef225 OZ |
3392 | } |
3393 | </code> | |
3394 | ||
dad92c30 | 3395 | |
1532a244 | 3396 | <sect>RIP |
d37f899b | 3397 | |
371adba6 | 3398 | <sect1>Introduction |
d37f899b | 3399 | |
dad92c30 OZ |
3400 | <p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, |
3401 | where each router broadcasts (to all its neighbors) distances to all networks it | |
3402 | can reach. When a router hears distance to another network, it increments it and | |
3403 | broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some | |
3404 | network goes unreachable, routers keep telling each other that its distance is | |
3405 | the original distance plus 1 (actually, plus interface metric, which is usually | |
3406 | one). After some time, the distance reaches infinity (that's 15 in RIP) and all | |
3407 | routers know that network is unreachable. RIP tries to minimize situations where | |
3408 | counting to infinity is necessary, because it is slow. Due to infinity being 16, | |
3409 | you can't use RIP on networks where maximal distance is higher than 15 | |
8465dccb OZ |
3410 | hosts. |
3411 | ||
3412 | <p>BIRD supports RIPv1 | |
3413 | (RFC 1058<htmlurl url="http://www.rfc-editor.org/rfc/rfc1058.txt">), | |
3414 | RIPv2 (RFC 2453<htmlurl url="http://www.rfc-editor.org/rfc/rfc2453.txt">), | |
3415 | RIPng (RFC 2080<htmlurl url="http://www.rfc-editor.org/rfc/rfc2080.txt">), | |
3416 | and RIP cryptographic authentication (SHA-1 not implemented) | |
3417 | (RFC 4822<htmlurl url="http://www.rfc-editor.org/rfc/rfc4822.txt">). | |
440439e3 | 3418 | |
1532a244 | 3419 | <p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow |
dad92c30 OZ |
3420 | convergence, big network load and inability to handle larger networks makes it |
3421 | pretty much obsolete. It is still usable on very small networks. | |
d37f899b | 3422 | |
371adba6 | 3423 | <sect1>Configuration |
d37f899b | 3424 | |
8465dccb OZ |
3425 | <p>RIP configuration consists mainly of common protocol options and interface |
3426 | definitions, most RIP options are interface specific. | |
3427 | ||
3428 | <code> | |
3429 | protocol rip [<name>] { | |
3430 | infinity <number>; | |
3431 | ecmp <switch> [limit <number>]; | |
3432 | interface <interface pattern> { | |
3433 | metric <number>; | |
3434 | mode multicast|broadcast; | |
3435 | passive <switch>; | |
3436 | address <ip>; | |
3437 | port <number>; | |
3438 | version 1|2; | |
3439 | split horizon <switch>; | |
3440 | poison reverse <switch>; | |
3441 | check zero <switch>; | |
3442 | update time <number>; | |
3443 | timeout time <number>; | |
3444 | garbage time <number>; | |
3445 | ecmp weight <number>; | |
3446 | ttl security <switch>; | tx only; | |
3447 | tx class|dscp <number>; | |
3448 | tx priority <number>; | |
3449 | rx buffer <number>; | |
3450 | tx length <number>; | |
3451 | check link <switch>; | |
3452 | authentication none|plaintext|cryptographic; | |
3453 | password "<text>"; | |
3454 | password "<text>" { | |
3455 | id <num>; | |
3456 | generate from "<date>"; | |
3457 | generate to "<date>"; | |
3458 | accept from "<date>"; | |
3459 | accept to "<date>"; | |
3460 | }; | |
3461 | }; | |
3462 | } | |
3463 | </code> | |
d37f899b PM |
3464 | |
3465 | <descrip> | |
8465dccb OZ |
3466 | <tag>infinity <M>number</M></tag> |
3467 | Selects the distance of infinity. Bigger values will make | |
3468 | protocol convergence even slower. The default value is 16. | |
dad92c30 | 3469 | |
8465dccb OZ |
3470 | <tag>ecmp <M>switch</M> [limit <M>number</M>]</tag> |
3471 | This option specifies whether RIP is allowed to generate ECMP | |
3472 | (equal-cost multipath) routes. Such routes are used when there are | |
3473 | several directions to the destination, each with the same (computed) | |
3474 | cost. This option also allows to specify a limit on maximum number of | |
3475 | nexthops in one route. By default, ECMP is disabled. If enabled, | |
3476 | default value of the limit is 16. | |
3477 | ||
3478 | <tag>interface <m/pattern [, ...]/ { <m/options/ }</tag> | |
3479 | Interface definitions specify a set of interfaces on which the | |
3480 | protocol is activated and contain interface specific options. | |
3481 | See <ref id="dsc-iface" name="interface"> common options for | |
3482 | detailed description. | |
d37f899b PM |
3483 | </descrip> |
3484 | ||
8465dccb | 3485 | <p>Interface specific options: |
ef4a50be OZ |
3486 | |
3487 | <descrip> | |
3488 | <tag>metric <m/num/</tag> | |
8465dccb OZ |
3489 | This option specifies the metric of the interface. When a route is |
3490 | received from the interface, its metric is increased by this value | |
3491 | before further processing. Valid values are 1-255, but values higher | |
3492 | than infinity has no further meaning. Default: 1. | |
3493 | ||
3494 | <tag>mode multicast|broadcast</tag> | |
3495 | This option selects the mode for RIP to use on the interface. The | |
3496 | default is multicast mode for RIPv2 and broadcast mode for RIPv1. | |
3497 | RIPng always uses the multicast mode. | |
3498 | ||
3499 | <tag>passive <m/switch/</tag> | |
3500 | Passive interfaces receive routing updates but do not transmit any | |
3501 | messages. Default: no. | |
3502 | ||
3503 | <tag>address <m/ip/</tag> | |
3504 | This option specifies a destination address used for multicast or | |
3505 | broadcast messages, the default is the official RIP (224.0.0.9) or RIPng | |
3506 | (ff02::9) multicast address, or an appropriate broadcast address in the | |
3507 | broadcast mode. | |
3508 | ||
3509 | <tag>port <m/number/</tag> | |
3510 | This option selects an UDP port to operate on, the default is the | |
3511 | official RIP (520) or RIPng (521) port. | |
3512 | ||
3513 | <tag>version 1|2</tag> | |
3514 | This option selects the version of RIP used on the interface. For RIPv1, | |
3515 | automatic subnet aggregation is not implemented, only classful network | |
3516 | routes and host routes are propagated. Note that BIRD allows RIPv1 to be | |
3517 | configured with features that are defined for RIPv2 only, like | |
3518 | authentication or using multicast sockets. The default is RIPv2 for IPv4 | |
3519 | RIP, the option is not supported for RIPng, as no further versions are | |
3520 | defined. | |
3521 | ||
43fc6bb0 OZ |
3522 | <tag>version only <m/switch/</tag> |
3523 | Regardless of RIP version configured for the interface, BIRD accepts | |
3524 | incoming packets of any RIP version. This option restrict accepted | |
3525 | packets to the configured version. Default: no. | |
3526 | ||
8465dccb OZ |
3527 | <tag>split horizon <m/switch/</tag> |
3528 | Split horizon is a scheme for preventing routing loops. When split | |
3529 | horizon is active, routes are not regularly propagated back to the | |
3530 | interface from which they were received. They are either not propagated | |
3531 | back at all (plain split horizon) or propagated back with an infinity | |
3532 | metric (split horizon with poisoned reverse). Therefore, other routers | |
3533 | on the interface will not consider the router as a part of an | |
3534 | independent path to the destination of the route. Default: yes. | |
3535 | ||
3536 | <tag>poison reverse <m/switch/</tag> | |
3537 | When split horizon is active, this option specifies whether the poisoned | |
3538 | reverse variant (propagating routes back with an infinity metric) is | |
3539 | used. The poisoned reverse has some advantages in faster convergence, | |
3540 | but uses more network traffic. Default: yes. | |
3541 | ||
3542 | <tag>check zero <m/switch/</tag> | |
3543 | Received RIPv1 packets with non-zero values in reserved fields should | |
3544 | be discarded. This option specifies whether the check is performed or | |
3545 | such packets are just processed as usual. Default: yes. | |
3546 | ||
3547 | <tag>update time <m/number/</tag> | |
3548 | Specifies the number of seconds between periodic updates. A lower number | |
3549 | will mean faster convergence but bigger network load. Default: 30. | |
3550 | ||
3551 | <tag>timeout time <m/number/</tag> | |
3552 | Specifies the time interval (in seconds) between the last received route | |
3553 | announcement and the route expiration. After that, the network is | |
3554 | considered unreachable, but still is propagated with infinity distance. | |
3555 | Default: 180. | |
3556 | ||
3557 | <tag>garbage time <m/number/</tag> | |
3558 | Specifies the time interval (in seconds) between the route expiration | |
3559 | and the removal of the unreachable network entry. The garbage interval, | |
3560 | when a route with infinity metric is propagated, is used for both | |
3561 | internal (after expiration) and external (after withdrawal) routes. | |
3562 | Default: 120. | |
3563 | ||
3564 | <tag>ecmp weight <m/number/</tag> | |
3565 | When ECMP (multipath) routes are allowed, this value specifies a | |
3566 | relative weight used for nexthops going through the iface. Valid | |
3567 | values are 1-256. Default value is 1. | |
ef4a50be | 3568 | |
8465dccb OZ |
3569 | <tag>authentication none|plaintext|cryptographic</tag> |
3570 | Selects authentication method to be used. <cf/none/ means that packets | |
3571 | are not authenticated at all, <cf/plaintext/ means that a plaintext | |
3572 | password is embedded into each packet, and <cf/cryptographic/ means that | |
3573 | packets are authenticated using a MD5 cryptographic hash. If you set | |
3574 | authentication to not-none, it is a good idea to add <cf>password</cf> | |
3575 | section. Default: none. | |
3576 | ||
3577 | <tag>password "<m/text/"</tag> | |
3578 | Specifies a password used for authentication. See <ref id="dsc-pass" | |
3579 | name="password"> common option for detailed description. | |
ef4a50be | 3580 | |
6ac4f87a | 3581 | <tag>ttl security [<m/switch/ | tx only]</tag> |
dad92c30 OZ |
3582 | TTL security is a feature that protects routing protocols from remote |
3583 | spoofed packets by using TTL 255 instead of TTL 1 for protocol packets | |
3584 | destined to neighbors. Because TTL is decremented when packets are | |
3585 | forwarded, it is non-trivial to spoof packets with TTL 255 from remote | |
3586 | locations. | |
3587 | ||
3588 | If this option is enabled, the router will send RIP packets with TTL 255 | |
3589 | and drop received packets with TTL less than 255. If this option si set | |
3590 | to <cf/tx only/, TTL 255 is used for sent packets, but is not checked | |
3591 | for received packets. Such setting does not offer protection, but offers | |
3592 | compatibility with neighbors regardless of whether they use ttl | |
3593 | security. | |
3594 | ||
8465dccb OZ |
3595 | For RIPng, TTL security is a standard behavior (required by RFC 2080) |
3596 | and therefore default value is yes. For IPv4 RIP, default value is no. | |
6ac4f87a | 3597 | |
8465dccb | 3598 | <tag>tx class|dscp|priority <m/number/</tag> |
dad92c30 OZ |
3599 | These options specify the ToS/DiffServ/Traffic class/Priority of the |
3600 | outgoing RIP packets. See <ref id="dsc-prio" name="tx class"> common | |
3601 | option for detailed description. | |
d37f899b | 3602 | |
8465dccb OZ |
3603 | <tag>rx buffer <m/number/</tag> |
3604 | This option specifies the size of buffers used for packet processing. | |
3605 | The buffer size should be bigger than maximal size of received packets. | |
3606 | The default value is 532 for IPv4 RIP and interface MTU value for RIPng. | |
3607 | ||
3608 | <tag>tx length <m/number/</tag> | |
3609 | This option specifies the maximum length of generated RIP packets. To | |
3610 | avoid IP fragmentation, it should not exceed the interface MTU value. | |
3611 | The default value is 532 for IPv4 RIP and interface MTU value for RIPng. | |
3612 | ||
3613 | <tag>check link <m/switch/</tag> | |
3614 | If set, the hardware link state (as reported by OS) is taken into | |
3615 | consideration. When the link disappears (e.g. an ethernet cable is | |
3616 | unplugged), neighbors are immediately considered unreachable and all | |
3617 | routes received from them are withdrawn. It is possible that some | |
3618 | hardware drivers or platforms do not implement this feature. Default: | |
3619 | no. | |
d37f899b PM |
3620 | </descrip> |
3621 | ||
371adba6 | 3622 | <sect1>Attributes |
d37f899b | 3623 | |
1b55b1a3 MM |
3624 | <p>RIP defines two route attributes: |
3625 | ||
3626 | <descrip> | |
dad92c30 OZ |
3627 | <tag>int <cf/rip_metric/</tag> |
3628 | RIP metric of the route (ranging from 0 to <cf/infinity/). When routes | |
3629 | from different RIP instances are available and all of them have the same | |
8465dccb OZ |
3630 | preference, BIRD prefers the route with lowest <cf/rip_metric/. When a |
3631 | non-RIP route is exported to RIP, the default metric is 1. | |
dad92c30 OZ |
3632 | |
3633 | <tag>int <cf/rip_tag/</tag> | |
3634 | RIP route tag: a 16-bit number which can be used to carry additional | |
3635 | information with the route (for example, an originating AS number in | |
8465dccb OZ |
3636 | case of external routes). When a non-RIP route is exported to RIP, the |
3637 | default tag is 0. | |
1b55b1a3 MM |
3638 | </descrip> |
3639 | ||
371adba6 | 3640 | <sect1>Example |
1b55b1a3 MM |
3641 | |
3642 | <p><code> | |
8465dccb | 3643 | protocol rip { |
d37f899b PM |
3644 | debug all; |
3645 | port 1520; | |
2bf59bf4 | 3646 | period 12; |
326e33f5 | 3647 | garbage time 60; |
f434d191 OZ |
3648 | interface "eth0" { metric 3; mode multicast; }; |
3649 | interface "eth*" { metric 2; mode broadcast; }; | |
d37f899b PM |
3650 | authentication none; |
3651 | import filter { print "importing"; accept; }; | |
3652 | export filter { print "exporting"; accept; }; | |
3653 | } | |
a0dd1c74 | 3654 | </code> |
d37f899b | 3655 | |
dad92c30 | 3656 | |
371adba6 | 3657 | <sect>Static |
1b55b1a3 | 3658 | |
0e4789c2 | 3659 | <p>The Static protocol doesn't communicate with other routers in the network, |
f8e2d916 | 3660 | but instead it allows you to define routes manually. This is often used for |
79a2b697 | 3661 | specifying how to forward packets to parts of the network which don't use |
dad92c30 OZ |
3662 | dynamic routing at all and also for defining sink routes (i.e., those telling to |
3663 | return packets as undeliverable if they are in your IP block, you don't have any | |
3664 | specific destination for them and you don't want to send them out through the | |
3665 | default route to prevent routing loops). | |
3666 | ||
3667 | <p>There are five types of static routes: `classical' routes telling to forward | |
3668 | packets to a neighboring router, multipath routes specifying several (possibly | |
3669 | weighted) neighboring routers, device routes specifying forwarding to hosts on a | |
3670 | directly connected network, recursive routes computing their nexthops by doing | |
43fc6bb0 | 3671 | route table lookups for a given IP, and special routes (sink, blackhole etc.) |
dad92c30 | 3672 | which specify a special action to be done instead of forwarding the packet. |
79a2b697 MM |
3673 | |
3674 | <p>When the particular destination is not available (the interface is down or | |
3675 | the next hop of the route is not a neighbor at the moment), Static just | |
326e33f5 | 3676 | uninstalls the route from the table it is connected to and adds it again as soon |
a00c7a18 | 3677 | as the destination becomes adjacent again. |
79a2b697 | 3678 | |
43fc6bb0 OZ |
3679 | <p>There are three classes of definitions in Static protocol configuration -- |
3680 | global options, static route definitions, and per-route options. Usually, the | |
3681 | definition of the protocol contains mainly a list of static routes. | |
3682 | ||
3683 | <p>Global options: | |
3684 | ||
3685 | <descrip> | |
3686 | <tag>check link <m/switch/</tag> | |
3687 | If set, hardware link states of network interfaces are taken into | |
3688 | consideration. When link disappears (e.g. ethernet cable is unplugged), | |
3689 | static routes directing to that interface are removed. It is possible | |
3690 | that some hardware drivers or platforms do not implement this feature. | |
3691 | Default: off. | |
3692 | ||
3693 | <tag>igp table <m/name/</tag> | |
3694 | Specifies a table that is used for route table lookups of recursive | |
3695 | routes. Default: the same table as the protocol is connected to. | |
3696 | </descrip> | |
3697 | ||
3698 | <p>Route definitions (each may also contain a block of per-route options): | |
79a2b697 MM |
3699 | |
3700 | <descrip> | |
dad92c30 | 3701 | <tag>route <m/prefix/ via <m/ip/</tag> |
6683d42d OZ |
3702 | Static route through a neighboring router. For link-local next hops, |
3703 | interface can be specified as a part of the address (e.g., | |
3704 | <cf/via fe80::1234%eth0/). | |
dad92c30 | 3705 | |
1e3810f9 | 3706 | <tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [bfd <m/switch/] [via ...]</tag> |
e91f6960 | 3707 | Static multipath route. Contains several nexthops (gateways), possibly |
1e3810f9 | 3708 | with their weights. |
dad92c30 OZ |
3709 | |
3710 | <tag>route <m/prefix/ via <m/"interface"/</tag> | |
3711 | Static device route through an interface to hosts on a directly | |
3712 | connected network. | |
3713 | ||
3714 | <tag>route <m/prefix/ recursive <m/ip/</tag> | |
3715 | Static recursive route, its nexthop depends on a route table lookup for | |
3716 | given IP address. | |
3717 | ||
3718 | <tag>route <m/prefix/ blackhole|unreachable|prohibit</tag> | |
3719 | Special routes specifying to silently drop the packet, return it as | |
3720 | unreachable or return it as administratively prohibited. First two | |
3721 | targets are also known as <cf/drop/ and <cf/reject/. | |
43fc6bb0 | 3722 | </descrip> |
391931d4 | 3723 | |
43fc6bb0 | 3724 | <p>Per-route options: |
dad92c30 | 3725 | |
43fc6bb0 OZ |
3726 | <descrip> |
3727 | <tag>bfd <m/switch/</tag> | |
3728 | The Static protocol could use BFD protocol for next hop liveness | |
3729 | detection. If enabled, a BFD session to the route next hop is created | |
3730 | and the static route is BFD-controlled -- the static route is announced | |
3731 | only if the next hop liveness is confirmed by BFD. If the BFD session | |
3732 | fails, the static route is removed. Note that this is a bit different | |
3733 | compared to other protocols, which may use BFD as an advisory mechanism | |
3734 | for fast failure detection but ignores it if a BFD session is not even | |
3735 | established. | |
3736 | ||
3737 | This option can be used for static routes with a direct next hop, or | |
3738 | also for for individual next hops in a static multipath route (see | |
3739 | above). Note that BFD protocol also has to be configured, see | |
3740 | <ref id="sect-bfd" name="BFD"> section for details. Default value is no. | |
3741 | ||
3742 | <tag><m/filter expression/</tag> | |
3743 | This is a special option that allows filter expressions to be configured | |
3744 | on per-route basis. Can be used multiple times. These expressions are | |
3745 | evaluated when the route is originated, similarly to the import filter | |
3746 | of the static protocol. This is especially useful for configuring route | |
3747 | attributes, e.g., <cf/ospf_metric1 = 100;/ for a route that will be | |
3748 | exported to the OSPF protocol. | |
79a2b697 MM |
3749 | </descrip> |
3750 | ||
79a2b697 MM |
3751 | <p>Static routes have no specific attributes. |
3752 | ||
4f88ac47 | 3753 | <p>Example static config might look like this: |
79a2b697 MM |
3754 | |
3755 | <p><code> | |
3756 | protocol static { | |
43fc6bb0 OZ |
3757 | table testable; # Connect to a non-default routing table |
3758 | check link; # Advertise routes only if link is up | |
9491f9f5 | 3759 | route 0.0.0.0/0 via 198.51.100.130; # Default route |
43fc6bb0 | 3760 | route 10.0.0.0/8 multipath # Multipath route |
9491f9f5 | 3761 | via 198.51.100.10 weight 2 |
43fc6bb0 | 3762 | via 198.51.100.20 bfd # BFD-controlled next hop |
9491f9f5 | 3763 | via 192.0.2.1; |
80a9cadc | 3764 | route 203.0.113.0/24 unreachable; # Sink route |
43fc6bb0 OZ |
3765 | route 10.2.0.0/24 via "arc0"; # Secondary network |
3766 | route 192.168.10.0/24 via 198.51.100.100 { | |
3767 | ospf_metric1 = 20; # Set extended attribute | |
3768 | } | |
3769 | route 192.168.10.0/24 via 198.51.100.100 { | |
3770 | ospf_metric2 = 100; # Set extended attribute | |
3771 | ospf_tag = 2; # Set extended attribute | |
3772 | bfd; # BFD-controlled route | |
3773 | } | |
79a2b697 MM |
3774 | } |
3775 | </code> | |
3776 | ||
dad92c30 | 3777 | |
96264d4d PM |
3778 | <chapt>Conclusions |
3779 | ||
3780 | <sect>Future work | |
3781 | ||
dad92c30 OZ |
3782 | <p>Although BIRD supports all the commonly used routing protocols, there are |
3783 | still some features which would surely deserve to be implemented in future | |
3784 | versions of BIRD: | |
96264d4d PM |
3785 | |
3786 | <itemize> | |
55b58d8c | 3787 | <item>Opaque LSA's |
96264d4d | 3788 | <item>Route aggregation and flap dampening |
96264d4d PM |
3789 | <item>Multipath routes |
3790 | <item>Multicast routing protocols | |
3791 | <item>Ports to other systems | |
3792 | </itemize> | |
3793 | ||
dad92c30 | 3794 | |
96264d4d PM |
3795 | <sect>Getting more help |
3796 | ||
3797 | <p>If you use BIRD, you're welcome to join the bird-users mailing list | |
d148d0af | 3798 | (<HTMLURL URL="mailto:bird-users@network.cz" name="bird-users@network.cz">) |
96264d4d | 3799 | where you can share your experiences with the other users and consult |
d148d0af OF |
3800 | your problems with the authors. To subscribe to the list, visit |
3801 | <HTMLURL URL="http://bird.network.cz/?m_list" name="http://bird.network.cz/?m_list">. | |
96264d4d PM |
3802 | The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">. |
3803 | ||
dad92c30 OZ |
3804 | <p>BIRD is a relatively young system and it probably contains some bugs. You can |
3805 | report any problems to the bird-users list and the authors will be glad to solve | |
3806 | them, but before you do so, please make sure you have read the available | |
3807 | documentation and that you are running the latest version (available at | |
3808 | <HTMLURL URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). | |
3809 | (Of course, a patch which fixes the bug is always welcome as an attachment.) | |
3810 | ||
3811 | <p>If you want to understand what is going inside, Internet standards are a good | |
3812 | and interesting reading. You can get them from | |
3813 | <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a | |
3814 | nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" | |
3815 | name="atrey.karlin.mff.cuni.cz:/pub/rfc">). | |
69477cad | 3816 | |
c184d9d0 | 3817 | <p><it/Good luck!/ |
69477cad | 3818 | |
371adba6 | 3819 | </book> |
7581b81b | 3820 | |
a0dd1c74 | 3821 | <!-- |
75317ab8 MM |
3822 | LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel |
3823 | LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps | |
5a203dac | 3824 | LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC |
75317ab8 MM |
3825 | LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth |
3826 | LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek | |
4e8ec666 | 3827 | LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC |
5a203dac | 3828 | LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU |
4e8ec666 | 3829 | LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc |
5a203dac | 3830 | LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats |
64722c98 | 3831 | LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt |
5adc02a6 | 3832 | LocalWords: proto wildcard Ondrej Filip |
5a64ac70 | 3833 | --> |