]>
Commit | Line | Data |
---|---|---|
04a22949 | 1 | <!doctype birddoc system> |
d37f899b PM |
2 | |
3 | <!-- | |
d150c637 | 4 | BIRD documentation |
d37f899b | 5 | |
02357f96 PM |
6 | This documentation can have 4 forms: sgml (this is master copy), html, |
7 | ASCII text and dvi/postscript (generated from sgml using | |
8 | sgmltools). You should always edit master copy. | |
9 | ||
4e8ec666 | 10 | This is a slightly modified linuxdoc dtd. Anything in <descrip> tags is considered definition of |
326e33f5 | 11 | configuration primitives, <cf> is fragment of configuration within normal text, <m> is |
cd4fecb6 | 12 | "meta" information within fragment of configuration - something in config which is not keyword. |
d37f899b PM |
13 | |
14 | (set-fill-column 100) | |
15 | ||
16 | Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later. | |
17 | ||
18 | --> | |
19 | ||
371adba6 | 20 | <book> |
d37f899b | 21 | |
aa185265 | 22 | <title>BIRD User's Guide |
d37f899b | 23 | <author> |
aa185265 MM |
24 | Ondrej Filip <it/<feela@network.cz>/, |
25 | Pavel Machek <it/<pavel@ucw.cz>/, | |
5516a66d OF |
26 | Martin Mares <it/<mj@ucw.cz>/, |
27 | Ondrej Zajicek <it/<santiago@crfreenet.org>/ | |
aa185265 | 28 | </author> |
d37f899b | 29 | |
d37f899b | 30 | <abstract> |
aa185265 | 31 | This document contains user documentation for the BIRD Internet Routing Daemon project. |
d37f899b PM |
32 | </abstract> |
33 | ||
34 | <!-- Table of contents --> | |
35 | <toc> | |
36 | ||
37 | <!-- Begin the document --> | |
38 | ||
371adba6 | 39 | <chapt>Introduction |
d37f899b | 40 | |
371adba6 | 41 | <sect>What is BIRD |
d37f899b | 42 | |
897cd7aa MM |
43 | <p><label id="intro"> |
44 | The name `BIRD' is actually an acronym standing for `BIRD Internet Routing Daemon'. | |
45 | Let's take a closer look at the meaning of the name: | |
46 | ||
47 | <p><em/BIRD/: Well, we think we have already explained that. It's an acronym standing | |
48 | for `BIRD Internet Routing Daemon', you remember, don't you? :-) | |
49 | ||
50 | <p><em/Internet Routing/: It's a program (well, a daemon, as you are going to discover in a moment) | |
51 | which works as a dynamic router in an Internet type network (that is, in a network running either | |
52 | the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected | |
53 | networks in order to allow hosts not connected directly to the same local area network to | |
02357f96 | 54 | communicate with each other. They also communicate with the other routers in the Internet to discover |
897cd7aa | 55 | the topology of the network which allows them to find optimal (in terms of some metric) rules for |
96264d4d | 56 | forwarding of packets (which are called routing tables) and to adapt themselves to the |
897cd7aa MM |
57 | changing conditions such as outages of network links, building of new connections and so on. Most of |
58 | these routers are costly dedicated devices running obscure firmware which is hard to configure and | |
02357f96 | 59 | not open to any changes (on the other hand, their special hardware design allows them to keep up with lots of high-speed network interfaces, better than general-purpose computer does). Fortunately, most operating systems of the UNIX family allow an ordinary |
897cd7aa MM |
60 | computer to act as a router and forward packets belonging to the other hosts, but only according to |
61 | a statically configured table. | |
62 | ||
63 | <p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program running on | |
64 | background which does the dynamic part of Internet routing, that is it communicates | |
65 | with the other routers, calculates routing tables and sends them to the OS kernel | |
a92fe607 OZ |
66 | which does the actual packet forwarding. There already exist other such routing |
67 | daemons: routed (RIP only), GateD (non-free), Zebra<HTMLURL URL="http://www.zebra.org"> | |
68 | and MRTD<HTMLURL URL="http://sourceforge.net/projects/mrt">, but their capabilities are | |
69 | limited and they are relatively hard to configure and maintain. | |
897cd7aa MM |
70 | |
71 | <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings, | |
5459fac6 | 72 | to support all the routing technology used in the today's Internet or planned to be |
897cd7aa MM |
73 | used in near future and to have a clean extensible architecture allowing new routing |
74 | protocols to be incorporated easily. Among other features, BIRD supports: | |
75 | ||
76 | <itemize> | |
77 | <item>both IPv4 and IPv6 protocols | |
78 | <item>multiple routing tables | |
79 | <item>the Border Gateway Protocol (BGPv4) | |
96264d4d | 80 | <item>the Routing Information Protocol (RIPv2) |
0c75411b | 81 | <item>the Open Shortest Path First protocol (OSPFv2, OSPFv3) |
02357f96 | 82 | <item>a virtual protocol for exchange of routes between different routing tables on a single host |
897cd7aa MM |
83 | <item>a command-line interface allowing on-line control and inspection |
84 | of status of the daemon | |
85 | <item>soft reconfiguration (no need to use complex online commands | |
86 | to change the configuration, just edit the configuration file | |
02357f96 | 87 | and notify BIRD to re-read it and it will smoothly switch itself |
897cd7aa MM |
88 | to the new configuration, not disturbing routing protocols |
89 | unless they are affected by the configuration changes) | |
02357f96 | 90 | <item>a powerful language for route filtering |
897cd7aa MM |
91 | </itemize> |
92 | ||
93 | <p>BIRD has been developed at the Faculty of Math and Physics, Charles University, Prague, | |
e9df1bb6 | 94 | Czech Republic as a student project. It can be freely distributed under the terms of the GNU General |
897cd7aa MM |
95 | Public License. |
96 | ||
5adc02a6 OZ |
97 | <p>BIRD has been designed to work on all UNIX-like systems. It has |
98 | been developed and tested under Linux 2.0 to 2.6, and then ported to | |
99 | FreeBSD, NetBSD and OpenBSD, porting to other systems (even non-UNIX | |
100 | ones) should be relatively easy due to its highly modular | |
101 | architecture. | |
102 | ||
103 | <p>BIRD supports either IPv4 or IPv6 protocol, but have to be compiled | |
104 | separately for each one. Therefore, a dualstack router would run two | |
105 | instances of BIRD (one for IPv4 and one for IPv6), with completely | |
106 | separate setups (configuration files, tools ...). | |
d37f899b | 107 | |
371adba6 | 108 | <sect>Installing BIRD |
440439e3 | 109 | |
02357f96 | 110 | <p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) and Perl, installing BIRD should be as easy as: |
440439e3 PM |
111 | |
112 | <code> | |
113 | ./configure | |
114 | make | |
115 | make install | |
116 | vi /usr/local/etc/bird.conf | |
c184d9d0 | 117 | bird |
440439e3 PM |
118 | </code> |
119 | ||
02357f96 PM |
120 | <p>You can use <tt>./configure --help</tt> to get a list of configure |
121 | options. The most important ones are: | |
122 | <tt/--enable-ipv6/ which enables building of an IPv6 version of BIRD, | |
123 | <tt/--with-protocols=/ to produce a slightly smaller BIRD executable by configuring out routing protocols you don't use, and | |
124 | <tt/--prefix=/ to install BIRD to a place different from. | |
b093c328 PM |
125 | <file>/usr/local</file>. |
126 | ||
02357f96 | 127 | <sect>Running BIRD |
36032ded | 128 | |
c184d9d0 | 129 | <p>You can pass several command-line options to bird: |
d26524fa | 130 | |
c184d9d0 PM |
131 | <descrip> |
132 | <tag>-c <m/config name/</tag> | |
66701947 | 133 | use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>. |
c184d9d0 PM |
134 | |
135 | <tag>-d</tag> | |
02357f96 | 136 | enable debug messages and run bird in foreground. |
c184d9d0 | 137 | |
02357f96 | 138 | <tag>-D <m/filename of debug log/</tag> |
a4644ed6 OZ |
139 | log debugging information to given file instead of stderr. |
140 | ||
141 | <tag>-p</tag> | |
a6250a7d OZ |
142 | just parse the config file and exit. Return value is zero if the config file is valid, |
143 | nonzero if there are some errors. | |
c184d9d0 PM |
144 | |
145 | <tag>-s <m/name of communication socket/</tag> | |
66701947 | 146 | use given filename for a socket for communications with the client, default is <it/prefix/<file>/var/run/bird.ctl</file>. |
c184d9d0 | 147 | </descrip> |
d26524fa | 148 | |
02357f96 PM |
149 | <p>BIRD writes messages about its work to log files or syslog (according to config). |
150 | ||
a852c139 PM |
151 | <chapt>About routing tables |
152 | ||
96264d4d PM |
153 | <p>BIRD has one or more routing tables which may or may not be |
154 | synchronized with OS kernel and which may or may not be synchronized with | |
155 | each other (see the Pipe protocol). Each routing table contains a list of | |
a852c139 PM |
156 | known routes. Each route consists of: |
157 | ||
158 | <itemize> | |
96264d4d PM |
159 | <item>network prefix this route is for (network address and prefix length -- the number of bits forming the network part of the address; also known as a netmask) |
160 | <item>preference of this route | |
161 | <item>IP address of router which told us about this route | |
02357f96 | 162 | <item>IP address of router we should forward the packets to |
a852c139 PM |
163 | using this route |
164 | <item>other attributes common to all routes | |
02357f96 PM |
165 | <item>dynamic attributes defined by protocols which may or |
166 | may not be present (typically protocol metrics) | |
a852c139 PM |
167 | </itemize> |
168 | ||
96264d4d PM |
169 | Routing table maintains multiple entries |
170 | for a network, but at most one entry for one network and one | |
171 | protocol. The entry with the highest preference is used for routing (we | |
172 | will call such an entry the <it/selected route/). If | |
02357f96 | 173 | there are more entries with the same preference and they are from the same |
96264d4d PM |
174 | protocol, the protocol decides (typically according to metrics). If they aren't, |
175 | an internal ordering is used to break the tie. You can | |
176 | get the list of route attributes in the Route attributes section. | |
177 | ||
178 | <p>Each protocol is connected to a routing table through two filters | |
179 | which can accept, reject and modify the routes. An <it/export/ | |
180 | filter checks routes passed from the routing table to the protocol, | |
181 | an <it/import/ filter checks routes in the opposite direction. | |
182 | When the routing table gets a route from a protocol, it recalculates | |
183 | the selected route and broadcasts it to all protocols connected to | |
184 | the table. The protocols typically send the update to other routers | |
185 | in the network. | |
a852c139 | 186 | |
371adba6 | 187 | <chapt>Configuration |
af0b25d2 | 188 | |
371adba6 | 189 | <sect>Introduction |
d37f899b | 190 | |
66701947 | 191 | <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <it/prefix/<file>/etc/bird.conf</file> (unless the |
1632f1fe PM |
192 | <tt/-c/ command line option is given). Configuration may be changed at user's request: if you modify |
193 | the config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new | |
194 | config. Then there's the client | |
195 | which allows you to talk with BIRD in an extensive way. | |
02357f96 PM |
196 | |
197 | <p>In the config, everything on a line after <cf/#/ or inside <cf>/* | |
198 | */</cf> is a comment, whitespace characters are treated as a single space. If there's a variable number of options, they are grouped using | |
199 | the <cf/{ }/ brackets. Each option is terminated by a <cf/;/. Configuration | |
326e33f5 PM |
200 | is case sensitive. |
201 | ||
02357f96 PM |
202 | <p>Here is an example of a simple config file. It enables |
203 | synchronization of routing tables with OS kernel, scans for | |
204 | new network interfaces every 10 seconds and runs RIP on all network interfaces found. | |
4a5bb2bf | 205 | |
d37f899b | 206 | |
a0dd1c74 | 207 | <code> |
d37f899b | 208 | protocol kernel { |
d150c637 | 209 | persist; # Don't remove routes on BIRD shutdown |
d37f899b PM |
210 | scan time 20; # Scan kernel routing table every 20 seconds |
211 | export all; # Default is export none | |
212 | } | |
213 | ||
214 | protocol device { | |
215 | scan time 10; # Scan interfaces every 10 seconds | |
216 | } | |
217 | ||
218 | protocol rip { | |
219 | export all; | |
220 | import all; | |
f434d191 | 221 | interface "*"; |
d37f899b | 222 | } |
a0dd1c74 | 223 | </code> |
d37f899b | 224 | |
326e33f5 | 225 | |
371adba6 | 226 | <sect>Global options |
af0b25d2 | 227 | |
a0dd1c74 | 228 | <p><descrip> |
44d4ab7a | 229 | <tag>log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag> |
1632f1fe | 230 | Set logging of messages having the given class (either <cf/all/ or <cf/{ |
44d4ab7a OZ |
231 | error, trace }/ etc.) into selected destination (a file specified as a filename string, |
232 | syslog with optional name argument, or the stderr output). Classes are: | |
1632f1fe | 233 | <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems, |
98627595 | 234 | <cf/debug/ for debugging messages, |
02357f96 PM |
235 | <cf/trace/ when you want to know what happens in the network, |
236 | <cf/remote/ for messages about misbehavior of remote machines, | |
237 | <cf/auth/ about authentication failures, | |
4e8ec666 | 238 | <cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple |
5a203dac | 239 | destinations. Default: log everything to the system log. |
02357f96 | 240 | |
7581b81b | 241 | <tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag> |
5a203dac PM |
242 | Set global defaults of protocol debugging options. See <cf/debug/ in the following section. Default: off. |
243 | ||
244 | <tag>debug commands <m/number/</tag> | |
245 | Control logging of client connections (0 for no logging, 1 for | |
246 | logging of connects and disconnects, 2 and higher for logging of | |
247 | all client commands). Default: 0. | |
249d238c | 248 | |
cf31112f OZ |
249 | <tag>mrtdump "<m/filename/"</tag> |
250 | Set MRTdump file name. This option must be specified to allow MRTdump feature. | |
251 | Default: no dump file. | |
252 | ||
253 | <tag>mrtdump protocols all|off|{ states, messages }</tag> | |
254 | Set global defaults of MRTdump options. See <cf/mrtdump/ in the following section. | |
255 | Default: off. | |
256 | ||
02357f96 | 257 | <tag>filter <m/name local variables/{ <m/commands/ }</tag> Define a filter. You can learn more about filters |
5a203dac | 258 | in the following chapter. |
326e33f5 | 259 | |
96264d4d | 260 | <tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more |
02357f96 | 261 | about functions in the following chapter. |
bfd71178 | 262 | |
02357f96 | 263 | <tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol |
1632f1fe | 264 | instance called <cf><m/name/</cf> (or with a name like "rip5" generated automatically if you don't specify any <cf><m/name/</cf>). You can learn more |
d150c637 | 265 | about configuring protocols in their own chapters. You can run more than one instance of |
5a203dac | 266 | most protocols (like RIP or BGP). By default, no instances are configured. |
249d238c | 267 | |
02357f96 | 268 | <tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/IP address/</tag> Define a constant. You can use it later in every place |
1632f1fe | 269 | you could use a simple integer or an IP address. |
249d238c | 270 | |
5a203dac | 271 | <tag>router id <m/IPv4 address/</tag> Set BIRD's router ID. It's a world-wide unique identification of your router, usually one of router's IPv4 addresses. Default: in IPv4 version, the lowest IP address of a non-loopback interface. In IPv6 version, this option is mandatory. |
249d238c | 272 | |
fcf5a4f4 | 273 | <tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag> |
27579857 OZ |
274 | This option allows to specify address and port where BGP |
275 | protocol should listen. It is global option as listening | |
276 | socket is common to all BGP instances. Default is to listen on | |
277 | all addresses (0.0.0.0) and port 179. In IPv6 mode, option | |
fcf5a4f4 OZ |
278 | <cf/dual/ can be used to specify that BGP socket should accept |
279 | both IPv4 and IPv6 connections (but even in that case, BIRD | |
280 | would accept IPv6 routes only). Such behavior was default in | |
281 | older versions of BIRD. | |
27579857 | 282 | |
9be9a264 | 283 | <tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag> |
c37e7851 OZ |
284 | This option allows to specify a format of date/time used by |
285 | BIRD. The first argument specifies for which purpose such | |
286 | format is used. <cf/route/ is a format used in 'show route' | |
287 | command output, <cf/protocol/ is used in 'show protocols' | |
288 | command output, <cf/base/ is used for other commands and | |
289 | <cf/log/ is used in a log file. | |
290 | ||
9be9a264 OZ |
291 | "<m/format1/" is a format string using <it/strftime(3)/ |
292 | notation (see <it/man strftime/ for details). <m/limit> and | |
c37e7851 OZ |
293 | "<m/format2/" allow to specify the second format string for |
294 | times in past deeper than <m/limit/ seconds. There are two | |
295 | shorthands: <cf/iso long/ is a ISO 8601 date/time format | |
296 | (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F | |
297 | %T"/. <cf/iso short/ is a variant of ISO 8601 that uses just | |
298 | the time format (hh:mm:ss) for near times (up to 20 hours in | |
299 | the past) and the date format (YYYY-MM-DD) for far times. This | |
300 | is a shorthand for <cf/"%T" 72000 "%F"/. | |
301 | ||
302 | By default, BIRD uses an short, ad-hoc format for <cf/route/ | |
303 | and <cf/protocol/ times, and a <cf/iso long/ similar format | |
304 | (DD-MM-YYYY hh:mm:ss) for <cf/base/ and <cf/log/. These | |
305 | defaults are here for a compatibility with older versions | |
306 | and might change in the future. | |
307 | ||
02357f96 | 308 | <tag>table <m/name/</tag> Create a new routing table. The default |
326e33f5 PM |
309 | routing table is created implicitly, other routing tables have |
310 | to be added by this command. | |
af0b25d2 | 311 | |
02357f96 | 312 | <tag>eval <m/expr/</tag> Evaluates given filter expression. It |
1632f1fe | 313 | is used by us for testing of filters. |
249d238c PM |
314 | </descrip> |
315 | ||
371adba6 | 316 | <sect>Protocol options |
bfd71178 | 317 | |
5a203dac PM |
318 | <p>For each protocol instance, you can configure a bunch of options. |
319 | Some of them (those described in this section) are generic, some are | |
320 | specific to the protocol (see sections talking about the protocols). | |
7581b81b | 321 | |
5a203dac PM |
322 | <p>Several options use a <cf><m/switch/</cf> argument. It can be either |
323 | <cf/on/, <cf/yes/ or a numeric expression with a non-zero value for the | |
324 | option to be enabled or <cf/off/, <cf/no/ or a numeric expression evaluating | |
325 | to zero to disable it. An empty <cf><m/switch/</cf> is equivalent to <cf/on/ | |
326 | ("silence means agreement"). | |
7581b81b | 327 | |
5a203dac PM |
328 | <descrip> |
329 | <tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent. | |
330 | ||
331 | <tag>disabled <m/switch/</tag> Disables the protocol. You can change the disable/enable status from the command | |
332 | line interface without needing to touch the configuration. Disabled protocols are not activated. Default: protocol is enabled. | |
333 | ||
334 | <tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag> | |
335 | Set protocol debugging options. If asked, each protocol is capable of | |
336 | writing trace messages about its work to the log (with category | |
337 | <cf/trace/). You can either request printing of <cf/all/ trace messages | |
338 | or only of the types selected: <cf/states/ for protocol state changes | |
339 | (protocol going up, down, starting, stopping etc.), | |
340 | <cf/routes/ for routes exchanged with the routing table, | |
341 | <cf/filters/ for details on route filtering, | |
342 | <cf/interfaces/ for interface change events sent to the protocol, | |
343 | <cf/events/ for events internal to the protocol and | |
344 | <cf/packets/ for packets sent and received by the protocol. Default: off. | |
345 | ||
cf31112f OZ |
346 | <tag>mrtdump all|off|{ states, messages }</tag> |
347 | ||
348 | Set protocol MRTdump flags. MRTdump is a standard binary | |
349 | format for logging information from routing protocols and | |
350 | daemons. These flags control what kind of information is | |
351 | logged from the protocol to the MRTdump file (which must be | |
352 | specified by global <cf/mrtdump/ option, see the previous | |
353 | section). Although these flags are similar to flags of | |
354 | <cf/debug/ option, their meaning is different and | |
355 | protocol-specific. For BGP protocol, <cf/states/ logs BGP | |
356 | state changes and <cf/messages/ logs received BGP messages. | |
357 | Other protocols does not support MRTdump yet. | |
358 | ||
359 | <tag>router id <m/IPv4 address/</tag> This option can be used | |
360 | to override global router id for a given protocol. Default: | |
361 | uses global router id. | |
4cdd0784 | 362 | |
5a203dac | 363 | <tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag> |
1632f1fe | 364 | Specify a filter to be used for filtering routes coming from the protocol to the routing table. <cf/all/ is shorthand for <cf/where true/ and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/. |
bfd71178 | 365 | |
1632f1fe PM |
366 | <tag>export <m/filter/</tag> This is similar to the <cf>import</cf> keyword, except that it |
367 | works in the direction from the routing table to the protocol. Default: <cf/none/. | |
af0b25d2 | 368 | |
62aa96ca OZ |
369 | <tag>description "<m/text/"</tag> This is an optional |
370 | description of the protocol. It is displayed as a part of the | |
371 | output of 'show route all' command. | |
372 | ||
a7c9f7c0 | 373 | <tag>table <m/name/</tag> Connect this protocol to a non-default routing table. |
7581b81b PM |
374 | </descrip> |
375 | ||
a7c9f7c0 | 376 | <p>There are several options that give sense only with certain protocols: |
7581b81b PM |
377 | |
378 | <descrip> | |
f434d191 OZ |
379 | <tag><label id="dsc-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...] [ { <m/option/ ; [...] } ]</tag> |
380 | ||
381 | Specifies a set of interfaces on which the protocol is activated with | |
382 | given interface-specific options. A set of interfaces specified by one | |
383 | interface option is described using an interface pattern. The | |
0c75411b | 384 | interface pattern consists of a sequence of clauses (separated by |
f434d191 OZ |
385 | commas), each clause may contain a mask, a prefix, or both of them. An |
386 | interface matches the clause if its name matches the mask (if | |
387 | specified) and its address matches the prefix (if specified). Mask is | |
388 | specified as shell-like pattern. | |
389 | ||
390 | An interface matches the pattern if it matches any of its | |
391 | clauses. If the clause begins with <cf/-/, matching interfaces are | |
392 | excluded. Patterns are parsed left-to-right, thus | |
393 | <cf/interface "eth0", -"eth*", "*";/ means eth0 and all | |
394 | non-ethernets. | |
395 | ||
396 | An interface option can be used more times with different | |
397 | interfaces-specific options, in that case for given interface | |
398 | the first matching interface option is used. | |
399 | ||
400 | This option is allowed in Direct, OSPF and RIP protocols, | |
401 | but in OSPF protocol it is used in <cf/area/ subsection. | |
402 | ||
403 | Default: none. | |
404 | ||
405 | Examples: | |
406 | ||
407 | <cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with | |
408 | <cf>type broadcast</cf> option. | |
409 | ||
410 | <cf>interface "eth1", "eth4", "eth5" { type pointopoint; };</cf> - start the protocol | |
411 | on enumerated interfaces with <cf>type pointopoint</cf> option. | |
412 | ||
413 | <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all | |
414 | interfaces that have address from 192.168.0.0/16, but not | |
415 | from 192.168.1.0/24. | |
416 | ||
417 | <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all | |
418 | interfaces that have address from 192.168.0.0/16, but not | |
419 | from 192.168.1.0/24. | |
420 | ||
421 | <cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all | |
422 | ethernet interfaces that have address from 192.168.1.0/24. | |
423 | ||
424 | <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> | |
425 | Specifies a password that can be used by the protocol. Password option can | |
426 | be used more times to specify more passwords. If more passwords are | |
427 | specified, it is a protocol-dependent decision which one is really | |
428 | used. Specifying passwords does not mean that authentication is | |
429 | enabled, authentication can be enabled by separate, protocol-dependent | |
430 | <cf/authentication/ option. | |
431 | ||
432 | This option is allowed in OSPF and RIP protocols. BGP has also | |
433 | <cf/password/ option, but it is slightly different and described | |
434 | separately. | |
435 | ||
436 | Default: none. | |
437 | </descrip> | |
438 | ||
439 | <p>Password option can contain section with some (not necessary all) password sub-options: | |
440 | ||
441 | <descrip> | |
442 | <tag>id <M>num</M></tag> | |
443 | ID of the password, (0-255). If it's not used, BIRD will choose | |
444 | ID based on an order of the password item in the interface. For | |
445 | example, second password item in one interface will have default | |
446 | ID 2. ID is used by some routing protocols to identify which | |
447 | password was used to authenticate protocol packets. | |
448 | ||
449 | <tag>generate from "<m/time/"</tag> | |
450 | The start time of the usage of the password for packet signing. | |
451 | The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>. | |
452 | ||
453 | <tag>generate to "<m/time/"</tag> | |
454 | The last time of the usage of the password for packet signing. | |
455 | ||
456 | <tag>accept from "<m/time/"</tag> | |
457 | The start time of the usage of the password for packet verification. | |
5a203dac | 458 | |
f434d191 OZ |
459 | <tag>accept to "<m/time/"</tag> |
460 | The last time of the usage of the password for packet verification. | |
7581b81b | 461 | </descrip> |
d37f899b | 462 | |
5a203dac | 463 | <chapt>Remote control |
36032ded | 464 | |
a7c9f7c0 | 465 | <p>You can use the command-line client <file>birdc</file> to talk with |
c429d4a4 OZ |
466 | a running BIRD. Communication is done using a <file/bird.ctl/ UNIX |
467 | domain socket (unless changed with the <tt/-s/ option given to both | |
468 | the server and the client). The commands can perform simple actions | |
469 | such as enabling/disabling of protocols, telling BIRD to show various | |
470 | information, telling it to show routing table filtered by filter, or | |
471 | asking BIRD to reconfigure. Press <tt/?/ at any time to get online | |
472 | help. Option <tt/-r/ can be used to enable a restricted mode of BIRD | |
473 | client, which allows just read-only commands (<cf/show .../). Option | |
1632f1fe | 474 | <tt/-v/ can be passed to the client, to make it dump numeric return |
c429d4a4 OZ |
475 | codes along with the messages. You do not necessarily need to use |
476 | <file/birdc/ to talk to BIRD, your own applications could do that, too | |
477 | -- the format of communication between BIRD and <file/birdc/ is stable | |
478 | (see the programmer's documentation). | |
c184d9d0 | 479 | |
f434d191 OZ |
480 | Many commands have the <m/name/ of the protocol instance as an argument. |
481 | This argument can be omitted if there exists only a single instance. | |
482 | ||
5a203dac | 483 | <p>Here is a brief list of supported functions: |
64722c98 PM |
484 | |
485 | <descrip> | |
5a203dac PM |
486 | <tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag> |
487 | Dump contents of internal data structures to the debugging output. | |
488 | ||
489 | <tag>show status</tag> | |
1632f1fe | 490 | Show router status, that is BIRD version, uptime and time from last reconfiguration. |
5a203dac PM |
491 | |
492 | <tag>show protocols [all]</tag> | |
1632f1fe | 493 | Show list of protocol instances along with tables they are connected to and protocol status, possibly giving verbose information, if <cf/all/ is specified. |
64722c98 | 494 | |
f434d191 OZ |
495 | <tag>show ospf interface [<m/name/] ["<m/interface/"]</tag> |
496 | Show detailed information about OSPF interfaces. | |
497 | ||
498 | <tag>show ospf neighbors [<m/name/] ["<m/interface/"]</tag> | |
499 | Show a list of OSPF neighbors and a state of adjacency to them. | |
500 | ||
0ea8fb4a OZ |
501 | <tag>show ospf state [all] [<m/name/]</tag> |
502 | Show detailed information about OSPF areas based on a content | |
503 | of the link-state database. It shows network topology, stub | |
504 | networks, aggregated networks and routers from other areas and | |
505 | external routes. The command shows information about reachable | |
506 | network nodes, use option <cf/all/ to show information about | |
507 | all network nodes in the link-state database. | |
508 | ||
509 | <tag>show ospf topology [all] [<m/name/]</tag> | |
510 | Show a topology of OSPF areas based on a content of the | |
511 | link-state database. It is just a stripped-down version of | |
512 | 'show ospf state'. | |
64722c98 | 513 | |
5a203dac | 514 | <tag>show static [<m/name/]</tag> |
f434d191 OZ |
515 | Show detailed information about static routes. |
516 | ||
5a203dac | 517 | <tag>show interfaces [summary]</tag> |
1632f1fe | 518 | Show the list of interfaces. For each interface, print its type, state, MTU and addresses assigned. |
5a203dac PM |
519 | |
520 | <tag>show symbols</tag> | |
1632f1fe | 521 | Show the list of symbols defined in the configuration (names of protocols, routing tables etc.). |
5a203dac | 522 | |
ea2ae6dd | 523 | <tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(export|preexport) <m/p/] [protocol <m/p/] [<m/options/]</tag> |
5a203dac | 524 | Show contents of a routing table (by default of the main one), |
1632f1fe | 525 | that is routes, their metrics and (in case the <cf/all/ switch is given) |
5a203dac PM |
526 | all their attributes. |
527 | ||
528 | <p>You can specify a <m/prefix/ if you want to print routes for a | |
529 | specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get | |
530 | the entry which will be used for forwarding of packets to the given | |
531 | destination. By default, all routes for each network are printed with | |
532 | the selected one at the top, unless <cf/primary/ is given in which case | |
533 | only the selected route is shown. | |
534 | ||
535 | <p>You can also ask for printing only routes processed and accepted by | |
536 | a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ } | |
537 | </cf> or matching a given condition (<cf>where <m/condition/</cf>). | |
ea2ae6dd OZ |
538 | The <cf/export/ and <cf/preexport/ switches ask for printing of entries |
539 | that are exported to the specified protocol. With <cf/preexport/, the | |
540 | export filter of the protocol is skipped. | |
5a203dac | 541 | |
4d176e14 OF |
542 | <p>You can also select just routes added by a specific protocol. |
543 | <cf>protocol <m/p/</cf>. | |
544 | ||
5a203dac PM |
545 | <p>The <cf/stats/ switch requests showing of route statistics (the |
546 | number of networks, number of routes before and after filtering). If | |
547 | you use <cf/count/ instead, only the statistics will be printed. | |
548 | ||
27579857 OZ |
549 | <tag>configure [soft] ["<m/config file/"]</tag> |
550 | Reload configuration from a given file. BIRD will smoothly | |
551 | switch itself to the new configuration, protocols are | |
552 | reconfigured if possible, restarted otherwise. Changes in | |
0c75411b | 553 | filters usually lead to restart of affected protocols. If |
4cdd0784 | 554 | <cf/soft/ option is used, changes in filters does not cause |
27579857 OZ |
555 | BIRD to restart affected protocols, therefore already accepted |
556 | routes (according to old filters) would be still propagated, | |
557 | but new routes would be processed according to the new | |
558 | filters. | |
5a203dac | 559 | |
bf47fe4b OZ |
560 | <tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag> |
561 | Enable, disable or restart a given protocol instance, instances matching the <cf><m/pattern/</cf> or <cf/all/ instances. | |
562 | ||
8a7fb885 OZ |
563 | <tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag> |
564 | ||
565 | Reload a given protocol instance, that means re-import routes | |
566 | from the protocol instance and re-export preferred routes to | |
567 | the instance. If <cf/in/ or <cf/out/ options are used, the | |
568 | command is restricted to one direction (re-import or | |
569 | re-export). | |
570 | ||
571 | This command is useful if appropriate filters have changed but | |
572 | the protocol instance was not restarted (or reloaded), | |
573 | therefore it still propagates the old set of routes. For example | |
574 | when <cf/configure soft/ command was used to change filters. | |
575 | ||
576 | Re-export always succeeds, but re-import is protocol-dependent | |
577 | and might fail (for example, if BGP neighbor does not support | |
578 | route-refresh extension). In that case, re-export is also | |
ea7ada38 OZ |
579 | skipped. Note that for the pipe protocol, both directions are |
580 | always reloaded together (<cf/in/ or <cf/out/ options are | |
581 | ignored in that case). | |
8a7fb885 | 582 | |
5a203dac PM |
583 | <tag/down/ |
584 | Shut BIRD down. | |
64722c98 | 585 | |
a4601845 | 586 | <tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag> |
64722c98 PM |
587 | Control protocol debugging. |
588 | </descrip> | |
36032ded | 589 | |
371adba6 | 590 | <chapt>Filters |
d37f899b | 591 | |
371adba6 | 592 | <sect>Introduction |
d37f899b | 593 | |
1632f1fe PM |
594 | <p>BIRD contains a simple programming language. (No, it can't yet read mail :-). There are |
595 | two objects in this language: filters and functions. Filters are interpreted by BIRD core when a route is | |
596 | being passed between protocols and routing tables. The filter language contains control structures such | |
597 | as if's and switches, but it allows no loops. An example of a filter using many features can be found in <file>filter/test.conf</file>. | |
d37f899b | 598 | |
a7c9f7c0 PM |
599 | <p>Filter gets the route, looks at its attributes and |
600 | modifies some of them if it wishes. At the end, it decides whether to | |
1632f1fe | 601 | pass the changed route through (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks |
0e5373fd | 602 | like this: |
d37f899b | 603 | |
a0dd1c74 | 604 | <code> |
d37f899b PM |
605 | filter not_too_far |
606 | int var; | |
607 | { | |
608 | if defined( rip_metric ) then | |
609 | var = rip_metric; | |
610 | else { | |
611 | var = 1; | |
612 | rip_metric = 1; | |
613 | } | |
614 | if rip_metric > 10 then | |
615 | reject "RIP metric is too big"; | |
616 | else | |
617 | accept "ok"; | |
618 | } | |
a0dd1c74 | 619 | </code> |
d37f899b | 620 | |
a7c9f7c0 | 621 | <p>As you can see, a filter has a header, a list of local variables, and a body. The header consists of |
1632f1fe PM |
622 | the <cf/filter/ keyword followed by a (unique) name of filter. The list of local variables consists of |
623 | <cf><M>type name</M>;</cf> pairs where each pair defines one local variable. The body consists of | |
624 | <cf> { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You can group | |
625 | several statements to a single compound statement by using braces (<cf>{ <M>statements</M> }</cf>) which is useful if | |
626 | you want to make a bigger block of code conditional. | |
627 | ||
628 | <p>BIRD supports functions, so that you don't have to repeat the same blocks of code over and | |
629 | over. Functions can have zero or more parameters and they can have local variables. Recursion is not allowed. Function definitions | |
326e33f5 | 630 | look like this: |
0e5373fd PM |
631 | |
632 | <code> | |
633 | function name () | |
634 | int local_variable; | |
635 | { | |
636 | local_variable = 5; | |
637 | } | |
638 | ||
639 | function with_parameters (int parameter) | |
640 | { | |
641 | print parameter; | |
642 | } | |
643 | </code> | |
644 | ||
1632f1fe | 645 | <p>Unlike in C, variables are declared after the <cf/function/ line, but before the first <cf/{/. You can't declare |
0e5373fd | 646 | variables in nested blocks. Functions are called like in C: <cf>name(); |
1632f1fe | 647 | with_parameters(5);</cf>. Function may return values using the <cf>return <m/[expr]/</cf> |
a7c9f7c0 | 648 | command. Returning a value exits from current function (this is similar to C). |
0e5373fd | 649 | |
a7c9f7c0 | 650 | <p>Filters are declared in a way similar to functions except they can't have explicit |
1632f1fe | 651 | parameters. They get a route table entry as an implicit parameter, it is also passed automatically |
a7c9f7c0 | 652 | to any functions called. The filter must terminate with either |
1632f1fe | 653 | <cf/accept/ or <cf/reject/ statement. If there's a runtime error in filter, the route |
2f647f3f | 654 | is rejected. |
0e5373fd | 655 | |
a7c9f7c0 PM |
656 | <p>A nice trick to debug filters is to use <cf>show route filter |
657 | <m/name/</cf> from the command line client. An example session might look | |
c184d9d0 PM |
658 | like: |
659 | ||
660 | <code> | |
661 | pavel@bug:~/bird$ ./birdc -s bird.ctl | |
662 | BIRD 0.0.0 ready. | |
c184d9d0 PM |
663 | bird> show route |
664 | 10.0.0.0/8 dev eth0 [direct1 23:21] (240) | |
665 | 195.113.30.2/32 dev tunl1 [direct1 23:21] (240) | |
666 | 127.0.0.0/8 dev lo [direct1 23:21] (240) | |
667 | bird> show route ? | |
1632f1fe | 668 | show route [<prefix>] [table <t>] [filter <f>] [all] [primary]... |
66701947 | 669 | bird> show route filter { if 127.0.0.5 ˜ net then accept; } |
c184d9d0 PM |
670 | 127.0.0.0/8 dev lo [direct1 23:21] (240) |
671 | bird> | |
672 | </code> | |
673 | ||
371adba6 | 674 | <sect>Data types |
d37f899b | 675 | |
a7c9f7c0 | 676 | <p>Each variable and each value has certain type. Booleans, integers and enums are |
326e33f5 | 677 | incompatible with each other (that is to prevent you from shooting in the foot). |
d37f899b PM |
678 | |
679 | <descrip> | |
a7c9f7c0 | 680 | <tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and |
1632f1fe | 681 | <cf/false/. Boolean is the only type you can use in <cf/if/ |
7581b81b | 682 | statements. |
d37f899b | 683 | |
a7c9f7c0 PM |
684 | <tag/int/ This is a general integer type, you can expect it to store signed values from -2000000000 |
685 | to +2000000000. Overflows are not checked. You can use <cf/0x1234/ syntax to write hexadecimal values. | |
d37f899b | 686 | |
a7c9f7c0 | 687 | <tag/pair/ This is a pair of two short integers. Each component can have values from 0 to |
92a72a4c OZ |
688 | 65535. Literals of this type are written as <cf/(1234,5678)/. The same syntax can also be |
689 | used to construct a pair from two arbitrary integer expressions (for example <cf/(1+2,a)/). | |
d37f899b | 690 | |
126683fe OZ |
691 | <tag/quad/ This is a dotted quad of numbers used to represent |
692 | router IDs (and others). Each component can have a value | |
693 | from 0 to 255. Literals of this type are written like IPv4 | |
694 | addresses. | |
695 | ||
a7c9f7c0 PM |
696 | <tag/string/ This is a string of characters. There are no ways to modify strings in |
697 | filters. You can pass them between functions, assign them to variables of type <cf/string/, print | |
698 | such variables, but you can't concatenate two strings. String literals | |
0e5373fd | 699 | are written as <cf/"This is a string constant"/. |
d37f899b | 700 | |
a7c9f7c0 | 701 | <tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it |
5a203dac | 702 | is either an IPv4 or IPv6 address. IP addresses are written in the standard notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator <cf>.mask(<M>num</M>)</cf> |
1632f1fe | 703 | on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP |
5a203dac | 704 | address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. |
d37f899b | 705 | |
a7c9f7c0 | 706 | <tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as |
0e5373fd | 707 | <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or |
1632f1fe PM |
708 | <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special |
709 | operators on prefixes: | |
710 | <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix | |
711 | length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true. | |
d37f899b | 712 | |
126683fe | 713 | <tag/int|pair|quad|ip|prefix|enum set/ |
a7c9f7c0 | 714 | Filters recognize four types of sets. Sets are similar to strings: you can pass them around |
126683fe | 715 | but you can't modify them. Literals of type <cf>int set</cf> look like <cf> |
d37f899b | 716 | [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in |
946dc15c OF |
717 | sets. |
718 | For pair sets, expressions like <cf/(123,*)/ can be used to denote ranges (in | |
0ef69b1c | 719 | that case <cf/(123,0)..(123,65535)/). You can also use <cf/(123,5..100)/ for range |
4733b49e | 720 | <cf/(123,5)..(123,100)/. |
946dc15c OF |
721 | You can also use expressions for both, pair sets and int sets. However it must |
722 | be possible to evaluate these expressions before daemon boots. So you can use | |
723 | only constants inside them. E.g. | |
724 | <code> | |
725 | define one=1; | |
726 | int set odds; | |
727 | pair set ps; | |
728 | ||
729 | odds = [ one, (2+1), (6-one), (2*2*2-1), 9, 11 ]; | |
730 | ps = [ (1,(one+one)), (3,4)..(4,8), (5,*), (6,3..6) ]; | |
731 | </code> | |
b1a597e0 OZ |
732 | |
733 | Sets of prefixes are special: their literals does not allow ranges, but allows | |
734 | prefix patterns that are written as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>. | |
e0e8c04a | 735 | Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if |
e755986a OZ |
736 | the first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are identical and <cf>len1 <= ip1 <= len2</cf>. |
737 | A valid prefix pattern has to satisfy <cf>low <= high</cf>, but <cf/pxlen/ is not constrained by <cf/low/ | |
e0e8c04a | 738 | or <cf/high/. Obviously, a prefix matches a prefix set literal if it matches any prefix pattern in the |
b1a597e0 OZ |
739 | prefix set literal. |
740 | ||
741 | There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for | |
e755986a | 742 | <cf><m>address</m>/<m/len/{<m/len/,<m/maxlen/}</cf> (where <cf><m>maxlen</m></cf> is 32 for IPv4 and 128 for IPv6), |
bcb81251 OZ |
743 | that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf> |
744 | is a shorthand for <cf><m>address</m>/<m/len/{0,<m/len/}</cf>, that means network prefix <cf><m>address</m>/<m/len/</cf> | |
745 | and all its supernets (network prefixes that contain it). | |
b1a597e0 OZ |
746 | |
747 | 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} ]</cf> matches | |
748 | prefix <cf>1.0.0.0/8</cf>, all subprefixes of <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes | |
749 | <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf> matches all prefixes (regardless of | |
750 | IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address | |
e755986a | 751 | <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 ˜ [ 1.0.0.0/8{15,17} ]</cf> is true, |
b1a597e0 OZ |
752 | but <cf>1.0.0.0/16 ˜ [ 1.0.0.0/8- ]</cf> is false. |
753 | ||
754 | Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed | |
3f9b7bfe | 755 | in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as |
b1a597e0 OZ |
756 | <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as |
757 | <cf>192.168.0.0/16{24,32}</cf>. | |
d37f899b PM |
758 | |
759 | <tag/enum/ | |
66701947 | 760 | Enumeration types are fixed sets of possibilities. You can't define your own |
1632f1fe | 761 | variables of such type, but some route attributes are of enumeration |
a7c9f7c0 | 762 | type. Enumeration types are incompatible with each other. |
0e5373fd PM |
763 | |
764 | <tag/bgppath/ | |
a7c9f7c0 | 765 | BGP path is a list of autonomous system numbers. You can't write literals of this type. |
4cdd0784 OZ |
766 | There are several special operators on bgppaths: |
767 | ||
768 | <cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/. | |
769 | ||
770 | <cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/. | |
771 | ||
772 | Both <cf/first/ and <cf/last/ return zero if there is no appropriate ASN, | |
773 | for example if the path contains an AS set element as the first (or the last) part. | |
774 | ||
775 | <cf><m/P/.len</cf> returns the length of path <m/P/. | |
776 | ||
777 | <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result. | |
778 | Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to | |
779 | <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute | |
780 | (for example <cf/bgp_path/). | |
4a5bb2bf | 781 | |
5a203dac PM |
782 | <tag/bgpmask/ |
783 | BGP masks are patterns used for BGP path matching | |
ad586334 | 784 | (using <cf>path ˜ [= 2 3 5 * =]</cf> syntax). The masks |
5a203dac | 785 | resemble wildcard patterns as used by UNIX shells. Autonomous |
e312bb40 | 786 | system numbers match themselves, <cf/*/ matches any (even empty) |
c8a6b9a3 OZ |
787 | sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number. |
788 | For example, if <cf>bgp_path</cf> is 4 3 2 1, then: | |
ad586334 OZ |
789 | <tt>bgp_path ˜ [= * 4 3 * =]</tt> is true, but |
790 | <tt>bgp_path ˜ [= * 4 5 * =]</tt> is false. | |
92a72a4c OZ |
791 | BGP mask expressions can also contain integer expressions enclosed in parenthesis |
792 | and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. | |
ad586334 | 793 | There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *. |
4cdd0784 | 794 | |
126683fe OZ |
795 | <tag/clist/ |
796 | Clist is similar to a set, except that unlike other sets, it | |
797 | can be modified. The type is used for community list (a set | |
798 | of pairs) and for cluster list (a set of quads). There exist | |
799 | no literals of this type. There are two special operators on | |
800 | clists: | |
4cdd0784 | 801 | |
ba5c0057 OZ |
802 | <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist |
803 | <m/C/ and returns the result. If item <m/P/ is already in | |
804 | clist <m/C/, it does nothing. | |
4cdd0784 | 805 | |
ba5c0057 OZ |
806 | <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad) |
807 | <m/P/ from clist <m/C/ and returns the result. If clist | |
808 | <m/C/ does not contain item <m/P/, it does nothing. | |
809 | <m/P/ may also be a pair (or quad) set, in that case the | |
810 | operator deletes all items from clist <m/C/ that are also | |
811 | members of set <m/P/. | |
4cdd0784 OZ |
812 | |
813 | Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to | |
814 | <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute | |
815 | (for example <cf/bgp_community/). Similarly for <cf/delete/. | |
0e5373fd | 816 | |
d37f899b PM |
817 | </descrip> |
818 | ||
a7c9f7c0 | 819 | <sect>Operators |
d37f899b | 820 | |
a7c9f7c0 | 821 | <p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison |
66701947 | 822 | <cf/(a=b, a!=b, a<b, a>=b)/. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/). |
1632f1fe | 823 | Special operators include <cf/˜/ for "is element of a set" operation - it can be |
e29fa06e OZ |
824 | used on element and set of elements of the same type (returning true if element is contained in the given set), or |
825 | on two strings (returning true if first string matches a shell-like pattern stored in second string) or on IP and prefix (returning true if IP is within the range defined by that prefix), or on | |
ba5c0057 | 826 | prefix and prefix (returning true if first prefix is more specific than second one) or on bgppath and bgpmask (returning true if the path matches the mask) or on pair/quad and clist (returning true if the pair/quad is element of the clist) or on clist and pair/quad set (returning true if there is an element of the clist that is also a member of the pair/quad set). |
25696edb | 827 | |
d37f899b | 828 | |
371adba6 | 829 | <sect>Control structures |
d37f899b | 830 | |
a7c9f7c0 PM |
831 | <p>Filters support two control structures: conditions and case switches. |
832 | ||
1632f1fe | 833 | <p>Syntax of a condition is: <cf>if |
074a166d | 834 | <M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{ |
1632f1fe PM |
835 | <M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf> |
836 | clause may be omitted. If the <cf><m>boolean expression</m></cf> is true, <cf><m>command1</m></cf> is executed, otherwise <cf><m>command2</m></cf> is executed. | |
d37f899b | 837 | |
1632f1fe PM |
838 | <p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else | |
839 | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ ... ] }</cf>. The expression after | |
840 | <cf>case</cf> can be of any type which can be on the left side of the ˜ operator and anything that could | |
841 | be a member of a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ grouping. | |
842 | If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed. | |
d37f899b | 843 | |
a7c9f7c0 | 844 | <p>Here is example that uses <cf/if/ and <cf/case/ structures: |
af0b25d2 PM |
845 | |
846 | <code> | |
847 | case arg1 { | |
848 | 2: print "two"; print "I can do more commands without {}"; | |
849 | 3 .. 5: print "three to five"; | |
850 | else: print "something else"; | |
a7c9f7c0 | 851 | } |
af0b25d2 | 852 | |
8798c811 PM |
853 | if 1234 = i then printn "."; else { |
854 | print "not 1234"; | |
855 | print "You need {} around multiple commands"; | |
856 | } | |
af0b25d2 PM |
857 | </code> |
858 | ||
371adba6 | 859 | <sect>Route attributes |
0e5373fd | 860 | |
1632f1fe PM |
861 | <p>A filter is implicitly passed a route, and it can access its |
862 | attributes just like it accesses variables. Attempts to access undefined | |
a7c9f7c0 | 863 | attribute result in a runtime error; you can check if an attribute is |
1632f1fe | 864 | defined by using the <cf>defined( <m>attribute</m> )</cf> operator. |
126683fe OZ |
865 | One notable exception to this rule are attributes of clist type, where |
866 | undefined value is regarded as empty clist for most purposes. | |
a7c9f7c0 | 867 | |
36032ded | 868 | <descrip> |
cd4fecb6 | 869 | <tag><m/prefix/ net</tag> |
1632f1fe | 870 | Network the route is talking about. Read-only. (See the chapter about routing tables.) |
a7c9f7c0 PM |
871 | |
872 | <tag><m/enum/ scope</tag> | |
ff2857b0 OZ |
873 | The scope of the route. Possible values: <cf/SCOPE_HOST/ for |
874 | routes local to this host, <cf/SCOPE_LINK/ for those specific | |
875 | for a physical link, <cf/SCOPE_SITE/ and | |
876 | <cf/SCOPE_ORGANIZATION/ for private routes and | |
877 | <cf/SCOPE_UNIVERSE/ for globally visible routes. This | |
878 | attribute is not interpreted by BIRD and can be used to mark | |
879 | routes in filters. The default value for new routes is | |
880 | <cf/SCOPE_UNIVERSE/. | |
0e5373fd | 881 | |
cd4fecb6 | 882 | <tag><m/int/ preference</tag> |
f4c6ca8c | 883 | Preference of the route. Valid values are 0-65535. (See the chapter about routing tables.) |
c184d9d0 | 884 | |
cd4fecb6 | 885 | <tag><m/ip/ from</tag> |
25696edb | 886 | The router which the route has originated from. Read-only. |
0e5373fd | 887 | |
cd4fecb6 | 888 | <tag><m/ip/ gw</tag> |
a7c9f7c0 | 889 | Next hop packets routed using this route should be forwarded to. |
0e5373fd | 890 | |
e29fa06e OZ |
891 | <tag><m/string/ proto</tag> |
892 | The name of the protocol which the route has been imported from. Read-only. | |
893 | ||
cd4fecb6 | 894 | <tag><m/enum/ source</tag> |
7873e982 | 895 | what protocol has told me about this route. Possible values: <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/, <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/, <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/, <cf/RTS_PIPE/. |
c184d9d0 | 896 | |
cd4fecb6 | 897 | <tag><m/enum/ cast</tag> |
ff2857b0 OZ |
898 | |
899 | Route type (Currently <cf/RTC_UNICAST/ for normal routes, | |
900 | <cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will | |
901 | be used in the future for broadcast, multicast and anycast | |
902 | routes). Read-only. | |
c184d9d0 | 903 | |
cd4fecb6 | 904 | <tag><m/enum/ dest</tag> |
c429d4a4 | 905 | Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_DEVICE/ for routing to a directly-connected network, <cf/RTD_BLACKHOLE/ for packets to be silently discarded, <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be returned with ICMP host unreachable / ICMP administratively prohibited messages). Read-only. |
b74f45f8 OZ |
906 | |
907 | <tag><m/int/ igp_metric</tag> | |
908 | The optional attribute that can be used to specify a distance | |
909 | to the network for routes that do not have a native protocol | |
910 | metric attribute (like <cf/ospf_metric1/ for OSPF routes). It | |
911 | is used mainly by BGP to compare internal distances to boundary | |
912 | routers (see below). It is also used when the route is exported | |
913 | to OSPF as a default value for OSPF type 1 metric. | |
ba1dda49 | 914 | </descrip> |
0e5373fd | 915 | |
1632f1fe | 916 | <p>There also exist some protocol-specific attributes which are described in the corresponding protocol sections. |
0e5373fd | 917 | |
1632f1fe | 918 | <sect>Other statements |
69477cad | 919 | |
a7c9f7c0 | 920 | <p>The following statements are available: |
69477cad PM |
921 | |
922 | <descrip> | |
a7c9f7c0 | 923 | <tag><m/variable/ = <m/expr/</tag> Set variable to a given value. |
326e33f5 | 924 | |
a7c9f7c0 | 925 | <tag>accept|reject [ <m/expr/ ]</tag> Accept or reject the route, possibly printing <cf><m>expr</m></cf>. |
326e33f5 | 926 | |
1632f1fe | 927 | <tag>return <m/expr/</tag> Return <cf><m>expr</m></cf> from the current function, the function ends at this point. |
326e33f5 | 928 | |
a7c9f7c0 PM |
929 | <tag>print|printn <m/expr/ [<m/, expr.../]</tag> |
930 | Prints given expressions; useful mainly while debugging | |
931 | filters. The <cf/printn/ variant does not terminate the line. | |
69477cad PM |
932 | |
933 | <tag>quitbird</tag> | |
1632f1fe | 934 | Terminates BIRD. Useful when debugging the filter interpreter. |
69477cad PM |
935 | </descrip> |
936 | ||
371adba6 | 937 | <chapt>Protocols |
d37f899b | 938 | |
371adba6 | 939 | <sect>BGP |
1b55b1a3 | 940 | |
56ab03c7 | 941 | <p>The Border Gateway Protocol is the routing protocol used for backbone |
5a203dac | 942 | level routing in the today's Internet. Contrary to the other protocols, its convergence |
56ab03c7 MM |
943 | doesn't rely on all routers following the same rules for route selection, |
944 | making it possible to implement any routing policy at any router in the | |
945 | network, the only restriction being that if a router advertises a route, | |
946 | it must accept and forward packets according to it. | |
947 | ||
b74f45f8 OZ |
948 | <p>BGP works in terms of autonomous systems (often abbreviated as |
949 | AS). Each AS is a part of the network with common management and | |
950 | common routing policy. It is identified by a unique 16-bit number | |
951 | (ASN). Routers within each AS usually exchange AS-internal routing | |
952 | information with each other using an interior gateway protocol (IGP, | |
953 | such as OSPF or RIP). Boundary routers at the border of | |
954 | the AS communicate global (inter-AS) network reachability information with | |
955 | their neighbors in the neighboring AS'es via exterior BGP (eBGP) and | |
956 | redistribute received information to other routers in the AS via | |
957 | interior BGP (iBGP). | |
56ab03c7 MM |
958 | |
959 | <p>Each BGP router sends to its neighbors updates of the parts of its | |
5a203dac PM |
960 | routing table it wishes to export along with complete path information |
961 | (a list of AS'es the packet will travel through if it uses the particular | |
56ab03c7 MM |
962 | route) in order to avoid routing loops. |
963 | ||
5459fac6 | 964 | <p>BIRD supports all requirements of the BGP4 standard as defined in |
1adc17b4 OZ |
965 | RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt"> |
966 | It also supports the community attributes | |
967 | (RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">), | |
968 | capability negotiation | |
969 | (RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">), | |
970 | MD5 password authentication | |
971 | (RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">), | |
972 | route reflectors | |
973 | (RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">), | |
e8ba557c OZ |
974 | multiprotocol extensions |
975 | (RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">), | |
1adc17b4 OZ |
976 | and 4B AS numbers |
977 | (RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">). | |
978 | ||
979 | ||
5459fac6 MM |
980 | For IPv6, it uses the standard multiprotocol extensions defined in |
981 | RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt"> | |
982 | including changes described in the | |
5a203dac | 983 | latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt"> |
5459fac6 MM |
984 | and applied to IPv6 according to |
985 | RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">. | |
986 | ||
371adba6 | 987 | <sect1>Route selection rules |
5459fac6 MM |
988 | |
989 | <p>BGP doesn't have any simple metric, so the rules for selection of an optimal | |
990 | route among multiple BGP routes with the same preference are a bit more complex | |
5a203dac | 991 | and they are implemented according to the following algorithm. It starts the first |
5459fac6 MM |
992 | rule, if there are more "best" routes, then it uses the second rule to choose |
993 | among them and so on. | |
994 | ||
995 | <itemize> | |
5a203dac | 996 | <item>Prefer route with the highest Local Preference attribute. |
5459fac6 | 997 | <item>Prefer route with the shortest AS path. |
b74f45f8 | 998 | <item>Prefer IGP origin over EGP and EGP origin over incomplete. |
5459fac6 | 999 | <item>Prefer the lowest value of the Multiple Exit Discriminator. |
b74f45f8 OZ |
1000 | <item>Prefer routes received via eBGP over ones received via iBGP. |
1001 | <item>Prefer routes with lower internal distance to a boundary router. | |
5a203dac | 1002 | <item>Prefer the route with the lowest value of router ID of the |
5459fac6 MM |
1003 | advertising router. |
1004 | </itemize> | |
56ab03c7 | 1005 | |
b74f45f8 OZ |
1006 | <sect1>IGP routing table |
1007 | ||
1008 | <p>BGP is mainly concerned with global network reachability and with | |
1009 | routes to other autonomous systems. When such routes are redistributed | |
1010 | to routers in the AS via BGP, they contain IP addresses of a boundary | |
1011 | routers (in route attribute NEXT_HOP). BGP depends on existing IGP | |
1012 | routing table with AS-internal routes to determine immediate next hops | |
1013 | for routes and to know their internal distances to boundary routers | |
1014 | for the purpose of BGP route selection. In BIRD, there is usually | |
1015 | one routing table used for both IGP routes and BGP routes. | |
1016 | ||
371adba6 | 1017 | <sect1>Configuration |
56ab03c7 | 1018 | |
5459fac6 | 1019 | <p>Each instance of the BGP corresponds to one neighboring router. |
5a203dac PM |
1020 | This allows to set routing policy and all the other parameters differently |
1021 | for each neighbor using the following configuration parameters: | |
5459fac6 MM |
1022 | |
1023 | <descrip> | |
9be9a264 OZ |
1024 | <tag>local <m/[ip]/] as <m/number/</tag> Define which AS we |
1025 | are part of. (Note that contrary to other IP routers, BIRD is | |
1026 | able to act as a router located in multiple AS'es | |
1027 | simultaneously, but in such cases you need to tweak the BGP | |
1028 | paths manually in the filters to get consistent behavior.) | |
1029 | Optional <cf/ip/ argument specifies a source address, | |
1030 | equivalent to the <cf/source address/ option (see below). | |
5459fac6 | 1031 | This parameter is mandatory. |
5a203dac | 1032 | |
5459fac6 MM |
1033 | <tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router |
1034 | this instance will be talking to and what AS it's located in. Unless | |
1035 | you use the <cf/multihop/ clause, it must be directly connected to one | |
f8e2d916 MM |
1036 | of your router's interfaces. In case the neighbor is in the same AS |
1037 | as we are, we automatically switch to iBGP. This parameter is mandatory. | |
5a203dac | 1038 | |
9be9a264 OZ |
1039 | <tag>multihop <m/[number]/]</tag> Configure multihop BGP |
1040 | session to a neighbor that isn't directly connected. | |
1041 | Accurately, this option should be used if the configured | |
1042 | neighbor IP address does not match with any local network | |
1043 | subnets. Such IP address have to be reachable through system | |
1044 | routing table. For multihop BGP it is recommended to | |
1045 | explicitly configure <cf/source address/ to have it | |
1046 | stable. Optional <cf/number/ argument can be used to limit TTL | |
1047 | (the number of hops). | |
5459fac6 | 1048 | Default: switched off. |
5a203dac | 1049 | |
9be9a264 OZ |
1050 | <tag>source address <m/ip/</tag> Define local address we |
1051 | should use for next hop calculation and as a source address | |
1052 | for the BGP session. Default: the address of the local | |
1053 | end of the interface our neighbor is connected to. | |
1054 | ||
3f9b7bfe | 1055 | <tag>next hop self</tag> Avoid calculation of the Next Hop |
9be9a264 OZ |
1056 | attribute and always advertise our own source address as a |
1057 | next hop. This needs to be used only occasionally to | |
1058 | circumvent misconfigurations of other routers. Default: | |
1059 | disabled. | |
5a203dac | 1060 | |
3f9b7bfe OZ |
1061 | <tag>missing lladdr self|drop|ignore</tag>Next Hop attribute |
1062 | in BGP-IPv6 sometimes contains just the global IPv6 address, | |
1063 | but sometimes it has to contain both global and link-local | |
1064 | IPv6 addresses. This option specifies what to do if BIRD have | |
1065 | to send both addresses but does not know link-local address. | |
1066 | This situation might happen when routes from other protocols | |
1067 | are exported to BGP, or when improper updates are received | |
717e4c4d OZ |
1068 | from BGP peers. <cf/self/ means that BIRD advertises its own |
1069 | local address instead. <cf/drop/ means that BIRD skips that | |
1070 | prefixes and logs error. <cf/ignore/ means that BIRD ignores | |
3f9b7bfe | 1071 | the problem and sends just the global address (and therefore |
717e4c4d OZ |
1072 | forms improper BGP update). Default: <cf/self/, unless BIRD |
1073 | is configured as a route server (option <cf/rs client/), in | |
1074 | that case default is <cf/drop/, because route servers usually | |
3f9b7bfe | 1075 | does not forward packets ifselves. |
087cecd0 OZ |
1076 | |
1077 | <tag>gateway direct|recursive</tag>For received routes, their | |
1078 | <cf/gw/ (immediate next hop) attribute is computed from | |
1079 | received <cf/bgp_next_hop/ attribute. This option specifies | |
1080 | how it is computed. Direct mode means that the IP address from | |
1081 | <cf/bgp_next_hop/ is used if it is directly reachable, | |
1082 | otherwise the neighbor IP address is used. Recursive mode | |
b74f45f8 | 1083 | means that the gateway is computed by an IGP routing table |
087cecd0 OZ |
1084 | lookup for the IP address from <cf/bgp_next_hop/. Recursive |
1085 | mode is the behavior specified by the BGP standard. Direct | |
1086 | mode is simpler, does not require any routes in a routing | |
1087 | table, and was used in older versions of BIRD, but does not | |
1088 | handle well nontrivial iBGP setups and multihop. Default: | |
1089 | <cf/direct/ for singlehop eBGP, <cf/recursive/ otherwise. | |
1090 | ||
1091 | <tag>igp table <m/name/</tag> Specifies a table that is used | |
b74f45f8 OZ |
1092 | as an IGP routing table. Default: the same as the table BGP is |
1093 | connected to. | |
3f9b7bfe | 1094 | |
1adc17b4 | 1095 | <tag>password <m/string/</tag> Use this password for MD5 authentication |
4c2507da OF |
1096 | of BGP sessions. Default: no authentication. Password has to be set by |
1097 | external utility (e.g. setkey(8)) on BSD systems. | |
1adc17b4 | 1098 | |
be6e39eb OZ |
1099 | <tag>passive <m/switch/</tag> Standard BGP behavior is both |
1100 | initiating outgoing connections and accepting incoming | |
1101 | connections. In passive mode, outgoing connections are not | |
1102 | initiated. Default: off. | |
1103 | ||
a92fe607 OZ |
1104 | <tag>rr client</tag> Be a route reflector and treat the neighbor as |
1105 | a route reflection client. Default: disabled. | |
1adc17b4 OZ |
1106 | |
1107 | <tag>rr cluster id <m/IPv4 address/</tag> Route reflectors use cluster id | |
1108 | to avoid route reflection loops. When there is one route reflector in a cluster | |
1109 | it usually uses its router id as a cluster id, but when there are more route | |
1110 | reflectors in a cluster, these need to be configured (using this option) to | |
1733d080 OZ |
1111 | use a common cluster id. Clients in a cluster need not know their cluster |
1112 | id and this option is not allowed for them. Default: the same as router id. | |
1adc17b4 | 1113 | |
a92fe607 OZ |
1114 | <tag>rs client</tag> Be a route server and treat the neighbor |
1115 | as a route server client. A route server is used as a | |
1116 | replacement for full mesh EBGP routing in Internet exchange | |
1117 | points in a similar way to route reflectors used in IBGP routing. | |
3f9b7bfe | 1118 | BIRD does not implement obsoleted RFC 1863, but uses ad-hoc implementation, |
a92fe607 OZ |
1119 | which behaves like plain EBGP but reduces modifications to advertised route |
1120 | attributes to be transparent (for example does not prepend its AS number to | |
1121 | AS PATH attribute and keep MED attribute). Default: disabled. | |
1122 | ||
bf47fe4b OZ |
1123 | <tag>enable route refresh <m/switch/</tag> When BGP speaker |
1124 | changes its import filter, it has to re-examine all routes | |
1125 | received from its neighbor against the new filter. As these | |
1126 | routes might not be available, there is a BGP protocol | |
1127 | extension Route Refresh (specified in RFC 2918) that allows | |
0c75411b | 1128 | BGP speaker to request re-advertisement of all routes from its |
bf47fe4b OZ |
1129 | neighbor. This option specifies whether BIRD advertises this |
1130 | capability and accepts such requests. Even when disabled, BIRD | |
1131 | can send route refresh requests. Default: on. | |
1132 | ||
41677025 OZ |
1133 | <tag>interpret communities <m/switch/</tag> RFC 1997 demands |
1134 | that BGP speaker should process well-known communities like | |
6cb8f742 OZ |
1135 | no-export (65535, 65281) or no-advertise (65535, 65282). For |
1136 | example, received route carrying a no-adverise community | |
41677025 OZ |
1137 | should not be advertised to any of its neighbors. If this |
1138 | option is enabled (which is by default), BIRD has such | |
1139 | behavior automatically (it is evaluated when a route is | |
cda2dfb7 | 1140 | exported to the BGP protocol just before the export filter). |
41677025 OZ |
1141 | Otherwise, this integrated processing of well-known |
1142 | communities is disabled. In that case, similar behavior can be | |
1143 | implemented in the export filter. Default: on. | |
6cb8f742 | 1144 | |
1adc17b4 OZ |
1145 | <tag>enable as4 <m/switch/</tag> BGP protocol was designed to use 2B AS numbers |
1146 | and was extended later to allow 4B AS number. BIRD supports 4B AS extension, | |
1147 | but by disabling this option it can be persuaded not to advertise it and | |
1148 | to maintain old-style sessions with its neighbors. This might be useful for | |
1149 | circumventing bugs in neighbor's implementation of 4B AS extension. | |
1150 | Even when disabled (off), BIRD behaves internally as AS4-aware BGP router. | |
1151 | Default: on. | |
1152 | ||
e8ba557c OZ |
1153 | <tag>capabilities <m/switch/</tag> Use capability advertisement |
1154 | to advertise optional capabilities. This is standard behavior | |
1155 | for newer BGP implementations, but there might be some older | |
1156 | BGP implementations that reject such connection attempts. | |
1157 | When disabled (off), features that request it (4B AS support) | |
1158 | are also disabled. Default: on, with automatic fallback to | |
1159 | off when received capability-related error. | |
1160 | ||
1161 | <tag>advertise ipv4 <m/switch/</tag> Advertise IPv4 multiprotocol capability. | |
1162 | This is not a correct behavior according to the strict interpretation | |
1163 | of RFC 4760, but it is widespread and required by some BGP | |
1164 | implementations (Cisco and Quagga). This option is relevant | |
1165 | to IPv4 mode with enabled capability advertisement only. Default: on. | |
e3299ab1 | 1166 | |
2a04b045 OZ |
1167 | <tag>route limit <m/number/</tag> The maximal number of routes |
1168 | that may be imported from the protocol. If the route limit is | |
1169 | exceeded, the connection is closed with error. Default: no limit. | |
1170 | ||
5459fac6 MM |
1171 | <tag>disable after error <m/switch/</tag> When an error is encountered (either |
1172 | locally or by the other side), disable the instance automatically | |
5a203dac PM |
1173 | and wait for an administrator to fix the problem manually. Default: off. |
1174 | ||
1175 | <tag>hold time <m/number/</tag> Time in seconds to wait for a Keepalive | |
5459fac6 MM |
1176 | message from the other side before considering the connection stale. |
1177 | Default: depends on agreement with the neighboring router, we prefer | |
1178 | 240 seconds if the other side is willing to accept it. | |
5a203dac | 1179 | |
5459fac6 | 1180 | <tag>startup hold time <m/number/</tag> Value of the hold timer used |
5a203dac | 1181 | before the routers have a chance to exchange open messages and agree |
5459fac6 | 1182 | on the real value. Default: 240 seconds. |
5a203dac | 1183 | |
5459fac6 | 1184 | <tag>keepalive time <m/number/</tag> Delay in seconds between sending |
5a203dac PM |
1185 | of two consecutive Keepalive messages. Default: One third of the hold time. |
1186 | ||
5459fac6 | 1187 | <tag>connect retry time <m/number/</tag> Time in seconds to wait before |
5a203dac PM |
1188 | retrying a failed attempt to connect. Default: 120 seconds. |
1189 | ||
5459fac6 | 1190 | <tag>start delay time <m/number/</tag> Delay in seconds between protocol |
5a203dac PM |
1191 | startup and the first attempt to connect. Default: 5 seconds. |
1192 | ||
1193 | <tag>error wait time <m/number/,<m/number/</tag> Minimum and maximum delay in seconds between a protocol | |
1194 | failure (either local or reported by the peer) and automatic restart. | |
5459fac6 MM |
1195 | Doesn't apply when <cf/disable after error/ is configured. If consecutive |
1196 | errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300. | |
5a203dac | 1197 | |
5459fac6 MM |
1198 | <tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol |
1199 | failures to treat them as a error sequence which makes the <cf/error wait time/ | |
1200 | increase exponentially. Default: 300 seconds. | |
5a203dac | 1201 | |
5459fac6 MM |
1202 | <tag>path metric <m/switch/</tag> Enable comparison of path lengths |
1203 | when deciding which BGP route is the best one. Default: on. | |
5a203dac | 1204 | |
b74f45f8 OZ |
1205 | <tag>igp metric <m/switch/</tag> Enable comparison of internal |
1206 | distances to boundary routers during best route selection. Default: on. | |
1207 | ||
3228c72c OZ |
1208 | <tag>prefer older <m/switch/</tag> Standard route selection algorithm |
1209 | breaks ties by comparing router IDs. This changes the behavior | |
1210 | to prefer older routes (when both are external and from different | |
1211 | peer). For details, see RFC 5004. Default: off. | |
1212 | ||
5459fac6 MM |
1213 | <tag>default bgp_med <m/number/</tag> Value of the Multiple Exit |
1214 | Discriminator to be used during route selection when the MED attribute | |
b6bf284a | 1215 | is missing. Default: 0. |
5a203dac | 1216 | |
fbcb7d5f OZ |
1217 | <tag>default bgp_local_pref <m/number/</tag> A default value |
1218 | for the Local Preference attribute. It is used when a new | |
1219 | Local Preference attribute is attached to a route by the BGP | |
1220 | protocol itself (for example, if a route is received through | |
1221 | eBGP and therefore does not have such attribute). Default: 100 | |
1222 | (0 in pre-1.2.0 versions of BIRD). | |
5459fac6 MM |
1223 | </descrip> |
1224 | ||
371adba6 | 1225 | <sect1>Attributes |
56ab03c7 | 1226 | |
5a203dac | 1227 | <p>BGP defines several route attributes. Some of them (those marked with `<tt/I/' in the |
5459fac6 | 1228 | table below) are available on internal BGP connections only, some of them (marked |
5a203dac | 1229 | with `<tt/O/') are optional. |
5459fac6 MM |
1230 | |
1231 | <descrip> | |
326e33f5 | 1232 | <tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path |
5a203dac PM |
1233 | the packet will travel through when forwarded according to the particular route. In case of |
1234 | internal BGP it doesn't contain the number of the local AS. | |
1235 | ||
5459fac6 MM |
1236 | <tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for |
1237 | selection among multiple BGP routes (see the selection rules above). It's | |
1238 | used as an additional metric which is propagated through the whole local AS. | |
5a203dac | 1239 | |
b6bf284a OZ |
1240 | <tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route |
1241 | is an optional attribute which is used on on external (inter-AS) links to | |
1242 | convey to an adjacent AS the optimal entry point into the local AS. | |
1243 | The received attribute may be also propagated over internal BGP links | |
1244 | (and this is default behavior). The attribute value is zeroed when a route | |
1245 | is exported from a routing table to a BGP instance to ensure that the attribute | |
1246 | received from a neighboring AS is not propagated to other neighboring ASes. | |
1247 | A new value might be set in the export filter of a BGP instance. | |
1248 | See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt"> | |
1249 | for further discussion of BGP MED attribute. | |
5a203dac PM |
1250 | |
1251 | <tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/ | |
1252 | if the route has originated in an interior routing protocol or | |
1253 | <cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol | |
1254 | (nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin | |
5459fac6 | 1255 | is unknown. |
5a203dac | 1256 | |
5459fac6 MM |
1257 | <tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets |
1258 | to this destination. On internal BGP connections, it's an address of the | |
1259 | originating router if it's inside the local AS or a boundary router the | |
1260 | packet will leave the AS through if it's an exterior route, so each BGP | |
1261 | speaker within the AS has a chance to use the shortest interior path | |
1262 | possible to this point. | |
5a203dac | 1263 | |
5459fac6 | 1264 | <tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute |
5a203dac PM |
1265 | which carries no value, but the sole presence of which indicates that the route |
1266 | has been aggregated from multiple routes by some router on the path from | |
5459fac6 | 1267 | the originator. |
5a203dac | 1268 | |
5459fac6 MM |
1269 | <!-- we don't handle aggregators right since they are of a very obscure type |
1270 | <tag>bgp_aggregator</tag> | |
1271 | --> | |
1272 | <tag>clist <cf/bgp_community/ [O]</tag> List of community values associated | |
1273 | with the route. Each such value is a pair (represented as a <cf/pair/ data | |
5a203dac PM |
1274 | type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines |
1275 | the community and the second one being a per-AS identifier. There are lots | |
5459fac6 MM |
1276 | of uses of the community mechanism, but generally they are used to carry |
1277 | policy information like "don't export to USA peers". As each AS can define | |
326e33f5 | 1278 | its own routing policy, it also has a complete freedom about which community |
5a203dac | 1279 | attributes it defines and what will their semantics be. |
126683fe OZ |
1280 | |
1281 | <tag>quad <cf/bgp_originator_id/ [O]</tag> This attribute is created by the | |
1282 | route reflector when reflecting the route and contains the router ID of the | |
1283 | originator of the route in the local AS. | |
1284 | ||
1285 | <tag>clist <cf/bgp_cluster_list/ [O]</tag> This attribute contains a list | |
1286 | of cluster IDs of route reflectors. Each route reflector prepends its | |
1287 | cluster ID when reflecting the route. | |
5459fac6 MM |
1288 | </descrip> |
1289 | ||
371adba6 | 1290 | <sect1>Example |
56ab03c7 | 1291 | |
5459fac6 MM |
1292 | <p><code> |
1293 | protocol bgp { | |
96264d4d PM |
1294 | local as 65000; # Use a private AS number |
1295 | neighbor 62.168.0.130 as 5588; # Our neighbor ... | |
1296 | multihop 20 via 62.168.0.13; # ... which is connected indirectly | |
1297 | export filter { # We use non-trivial export rules | |
1298 | if source = RTS_STATIC then { # Export only static routes | |
a852c139 PM |
1299 | # Assign our community |
1300 | bgp_community.add((65000,5678)); | |
1301 | # Artificially increase path length | |
5a203dac | 1302 | # by advertising local AS number twice |
eb875dbb | 1303 | if bgp_path ~ [= 65000 =] then |
a852c139 | 1304 | bgp_path.prepend(65000); |
5459fac6 MM |
1305 | accept; |
1306 | } | |
1307 | reject; | |
1308 | }; | |
1309 | import all; | |
96264d4d | 1310 | source address 62.168.0.1; # Use a non-standard source address |
5459fac6 MM |
1311 | } |
1312 | </code> | |
1313 | ||
371adba6 | 1314 | <sect>Device |
1b55b1a3 | 1315 | |
5a203dac PM |
1316 | <p>The Device protocol is not a real routing protocol. It doesn't generate |
1317 | any routes and it only serves as a module for getting information about network | |
79a2b697 MM |
1318 | interfaces from the kernel. |
1319 | ||
0e694e04 | 1320 | <p>Except for very unusual circumstances, you probably should include |
5a203dac PM |
1321 | this protocol in the configuration since almost all other protocols |
1322 | require network interfaces to be defined for them to work with. | |
79a2b697 | 1323 | |
6f5603ba | 1324 | <sect1>Configuration |
79a2b697 MM |
1325 | |
1326 | <p><descrip> | |
1327 | <tag>scan time <m/number/</tag> Time in seconds between two scans | |
1328 | of the network interface list. On systems where we are notified about | |
1329 | interface status changes asynchronously (such as newer versions of | |
5a203dac PM |
1330 | Linux), we need to scan the list only in order to avoid confusion by lost |
1331 | notification messages, so the default time is set to a large value. | |
6f5603ba OZ |
1332 | |
1333 | <tag>primary [ "<m/mask/" ] <m/prefix/</tag> | |
1334 | If a network interface has more than one network address, | |
1335 | BIRD has to choose one of them as a primary one, because some | |
1336 | routing protocols (for example OSPFv2) suppose there is only | |
1337 | one network address per interface. By default, BIRD chooses | |
1338 | the lexicographically smallest address as the primary one. | |
1339 | ||
1340 | This option allows to specify which network address should be | |
1341 | chosen as a primary one. Network addresses that match | |
1342 | <m/prefix/ are preferred to non-matching addresses. If more | |
1343 | <cf/primary/ options are used, the first one has the highest | |
1344 | preference. If "<m/mask/" is specified, then such | |
1345 | <cf/primary/ option is relevant only to matching network | |
1346 | interfaces. | |
1347 | ||
1348 | In all cases, an address marked by operating system as | |
1349 | secondary cannot be chosen as the primary one. | |
79a2b697 MM |
1350 | </descrip> |
1351 | ||
79a2b697 | 1352 | <p>As the Device protocol doesn't generate any routes, it cannot have |
6f5603ba | 1353 | any attributes. Example configuration looks like this: |
79a2b697 MM |
1354 | |
1355 | <p><code> | |
1356 | protocol device { | |
1357 | scan time 10; # Scan the interfaces often | |
6f5603ba OZ |
1358 | primary "eth0" 192.168.1.1; |
1359 | primary 192.168.0.0/16; | |
79a2b697 MM |
1360 | } |
1361 | </code> | |
1362 | ||
371adba6 | 1363 | <sect>Direct |
1b55b1a3 | 1364 | |
79a2b697 MM |
1365 | <p>The Direct protocol is a simple generator of device routes for all the |
1366 | directly connected networks according to the list of interfaces provided | |
1367 | by the kernel via the Device protocol. | |
1368 | ||
c429d4a4 OZ |
1369 | <p>The question is whether it is a good idea to have such device |
1370 | routes in BIRD routing table. OS kernel usually handles device routes | |
1371 | for directly connected networks by itself so we don't need (and don't | |
1372 | want) to export these routes to the kernel protocol. OSPF protocol | |
1373 | creates device routes for its interfaces itself and BGP protocol is | |
1374 | usually used for exporting aggregate routes. Although there are some | |
1375 | use cases that use the direct protocol (like abusing eBGP as an IGP | |
1376 | routing protocol), in most cases it is not needed to have these device | |
1377 | routes in BIRD routing table and to use the direct protocol. | |
79a2b697 | 1378 | |
5a203dac | 1379 | <p>The only configurable thing about direct is what interfaces it watches: |
79a2b697 MM |
1380 | |
1381 | <p><descrip> | |
0e694e04 | 1382 | <tag>interface <m/pattern [, ...]/</tag> By default, the Direct |
79a2b697 MM |
1383 | protocol will generate device routes for all the interfaces |
1384 | available. If you want to restrict it to some subset of interfaces | |
1385 | (for example if you're using multiple routing tables for policy | |
1386 | routing and some of the policy domains don't contain all interfaces), | |
1387 | just use this clause. | |
1388 | </descrip> | |
1389 | ||
79a2b697 MM |
1390 | <p>Direct device routes don't contain any specific attributes. |
1391 | ||
4f88ac47 | 1392 | <p>Example config might look like this: |
79a2b697 MM |
1393 | |
1394 | <p><code> | |
1395 | protocol direct { | |
1396 | interface "-arc*", "*"; # Exclude the ARCnets | |
1397 | } | |
1398 | </code> | |
1399 | ||
371adba6 | 1400 | <sect>Kernel |
1b55b1a3 | 1401 | |
0e4789c2 | 1402 | <p>The Kernel protocol is not a real routing protocol. Instead of communicating |
c429d4a4 | 1403 | with other routers in the network, it performs synchronization of BIRD's routing |
5a203dac | 1404 | tables with the OS kernel. Basically, it sends all routing table updates to the kernel |
0e4789c2 MM |
1405 | and from time to time it scans the kernel tables to see whether some routes have |
1406 | disappeared (for example due to unnoticed up/down transition of an interface) | |
f8e2d916 | 1407 | or whether an `alien' route has been added by someone else (depending on the |
c429d4a4 | 1408 | <cf/learn/ switch, such routes are either ignored or accepted to our |
f8e2d916 | 1409 | table). |
0e4789c2 | 1410 | |
c429d4a4 OZ |
1411 | <p>Unfortunately, there is one thing that makes the routing table |
1412 | synchronization a bit more complicated. In the kernel routing table | |
1413 | there are also device routes for directly connected networks. These | |
1414 | routes are usually managed by OS itself (as a part of IP address | |
1415 | configuration) and we don't want to touch that. They are completely | |
1416 | ignored during the scan of the kernel tables and also the export of | |
1417 | device routes from BIRD tables to kernel routing tables is restricted | |
1418 | to prevent accidental interference. This restriction can be disabled using | |
1419 | <cf/device routes/ switch. | |
1420 | ||
0e4789c2 MM |
1421 | <p>If your OS supports only a single routing table, you can configure only one |
1422 | instance of the Kernel protocol. If it supports multiple tables (in order to | |
5a203dac | 1423 | allow policy routing; such an OS is for example Linux 2.2), you can run as many instances as you want, but each of |
0e4789c2 MM |
1424 | them must be connected to a different BIRD routing table and to a different |
1425 | kernel table. | |
1426 | ||
371adba6 | 1427 | <sect1>Configuration |
0e4789c2 MM |
1428 | |
1429 | <p><descrip> | |
1430 | <tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the | |
326e33f5 | 1431 | routing tables when it exits (instead of cleaning them up). |
5a203dac | 1432 | <tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the |
0e4789c2 MM |
1433 | kernel routing table. |
1434 | <tag>learn <m/switch/</tag> Enable learning of routes added to the kernel | |
1435 | routing tables by other routing daemons or by the system administrator. | |
1436 | This is possible only on systems which support identification of route | |
1437 | authorship. | |
c429d4a4 OZ |
1438 | |
1439 | <tag>device routes <m/switch/</tag> Enable export of device | |
1440 | routes to the kernel routing table. By default, such routes | |
1441 | are rejected (with the exception of explicitly configured | |
1442 | device routes from the static protocol) regardless of the | |
1443 | export filter to protect device routes in kernel routing table | |
1444 | (managed by OS itself) from accidental overwriting or erasing. | |
1445 | ||
0e4789c2 MM |
1446 | <tag>kernel table <m/number/</tag> Select which kernel table should |
1447 | this particular instance of the Kernel protocol work with. Available | |
1448 | only on systems supporting multiple routing tables. | |
1449 | </descrip> | |
1450 | ||
5a203dac | 1451 | <p>The Kernel protocol doesn't define any route attributes. |
326e33f5 | 1452 | <p>A simple configuration can look this way: |
0e4789c2 MM |
1453 | |
1454 | <p><code> | |
1455 | protocol kernel { | |
1456 | import all; | |
1457 | export all; | |
1458 | } | |
1459 | </code> | |
1460 | ||
1461 | <p>Or for a system with two routing tables: | |
1462 | ||
1463 | <p><code> | |
1464 | protocol kernel { # Primary routing table | |
1465 | learn; # Learn alien routes from the kernel | |
1466 | persist; # Don't remove routes on bird shutdown | |
1467 | scan time 10; # Scan kernel routing table every 10 seconds | |
1468 | import all; | |
1469 | export all; | |
1470 | } | |
1471 | ||
1472 | protocol kernel { # Secondary routing table | |
1473 | table auxtable; | |
1474 | kernel table 100; | |
1475 | export all; | |
a2a3ced8 | 1476 | } |
0e4789c2 MM |
1477 | </code> |
1478 | ||
371adba6 | 1479 | <sect>OSPF |
1b55b1a3 | 1480 | |
8fd12e6b OF |
1481 | <sect1>Introduction |
1482 | ||
3ca3e999 | 1483 | <p>Open Shortest Path First (OSPF) is a quite complex interior gateway |
0c75411b OZ |
1484 | protocol. The current IPv4 version (OSPFv2) is defined in RFC |
1485 | 2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt"> and | |
1486 | the current IPv6 version (OSPFv3) is defined in RFC 5340<htmlurl | |
1487 | url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt"> It's a link state | |
1488 | (a.k.a. shortest path first) protocol -- each router maintains a | |
1489 | database describing the autonomous system's topology. Each participating | |
1490 | router has an identical copy of the database and all routers run the | |
1491 | same algorithm calculating a shortest path tree with themselves as a | |
1492 | root. OSPF chooses the least cost path as the best path. | |
3ca3e999 MM |
1493 | |
1494 | <p>In OSPF, the autonomous system can be split to several areas in order | |
1495 | to reduce the amount of resources consumed for exchanging the routing | |
1496 | information and to protect the other areas from incorrect routing data. | |
1497 | Topology of the area is hidden to the rest of the autonomous system. | |
3ca3e999 MM |
1498 | |
1499 | <p>Another very important feature of OSPF is that | |
1500 | it can keep routing information from other protocols (like Static or BGP) | |
1501 | in its link state database as external routes. Each external route can | |
1632f1fe | 1502 | be tagged by the advertising router, making it possible to pass additional |
3ca3e999 MM |
1503 | information between routers on the boundary of the autonomous system. |
1504 | ||
1505 | <p>OSPF quickly detects topological changes in the autonomous system (such | |
1632f1fe | 1506 | as router interface failures) and calculates new loop-free routes after a short |
f02e4258 | 1507 | period of convergence. Only a minimal amount of |
1632f1fe | 1508 | routing traffic is involved. |
8fd12e6b | 1509 | |
3ca3e999 MM |
1510 | <p>Each router participating in OSPF routing periodically sends Hello messages |
1511 | to all its interfaces. This allows neighbors to be discovered dynamically. | |
1512 | Then the neighbors exchange theirs parts of the link state database and keep it | |
1513 | identical by flooding updates. The flooding process is reliable and ensures | |
1514 | that each router detects all changes. | |
8fd12e6b OF |
1515 | |
1516 | <sect1>Configuration | |
1517 | ||
5a64ac70 OF |
1518 | <p>In the main part of configuration, there can be multiple definitions of |
1519 | OSPF area witch different id included. These definitions includes many other | |
f02e4258 OF |
1520 | switches and multiple definitions of interfaces. Definition of interface |
1521 | may contain many switches and constant definitions and list of neighbors | |
5a64ac70 | 1522 | on nonbroadcast networks. |
8fd12e6b OF |
1523 | |
1524 | <code> | |
088bc8ad | 1525 | protocol ospf <name> { |
1632f1fe | 1526 | rfc1583compat <switch>; |
62eee823 | 1527 | tick <num>; |
088bc8ad | 1528 | area <id> { |
b2bdb406 | 1529 | stub cost <num>; |
16319aeb OF |
1530 | networks { |
1531 | <prefix>; | |
1532 | <prefix> hidden; | |
1533 | } | |
38675202 OZ |
1534 | stubnet <prefix>; |
1535 | stubnet <prefix> { | |
1536 | hidden <switch>; | |
1537 | summary <switch>; | |
1538 | cost <num>; | |
1539 | } | |
1540 | interface <interface pattern> { | |
088bc8ad | 1541 | cost <num>; |
e3bc10fd | 1542 | stub <switch>; |
088bc8ad | 1543 | hello <num>; |
a190e720 | 1544 | poll <num>; |
088bc8ad OF |
1545 | retransmit <num>; |
1546 | priority <num>; | |
1547 | wait <num>; | |
1548 | dead count <num>; | |
d8c7d9e8 | 1549 | dead <num>; |
94c42054 | 1550 | rx buffer [normal|large|<num>]; |
8fd12e6b | 1551 | type [broadcast|nonbroadcast|pointopoint]; |
a190e720 | 1552 | strict nonbroadcast <switch>; |
3242ab43 | 1553 | authentication [none|simple|cryptographic]; |
088bc8ad | 1554 | password "<text>"; |
b21f68b4 OZ |
1555 | password "<text>" { |
1556 | id <num>; | |
1557 | generate from "<date>"; | |
1558 | generate to "<date>"; | |
1559 | accept from "<date>"; | |
1560 | accept to "<date>"; | |
ea357b8b | 1561 | }; |
8fd12e6b | 1562 | neighbors { |
088bc8ad | 1563 | <ip>; |
a190e720 | 1564 | <ip> eligible; |
8fd12e6b OF |
1565 | }; |
1566 | }; | |
38675202 | 1567 | virtual link <id> { |
98ac6176 | 1568 | hello <num>; |
98ac6176 OF |
1569 | retransmit <num>; |
1570 | wait <num>; | |
1571 | dead count <num>; | |
d8c7d9e8 | 1572 | dead <num>; |
3242ab43 | 1573 | authentication [none|simple|cryptographic]; |
98ac6176 OF |
1574 | password "<text>"; |
1575 | }; | |
8fd12e6b OF |
1576 | }; |
1577 | } | |
1578 | </code> | |
1579 | ||
1580 | <descrip> | |
1632f1fe | 1581 | <tag>rfc1583compat <M>switch</M></tag> |
3ca3e999 | 1582 | This option controls compatibility of routing table |
8fd12e6b OF |
1583 | calculation with RFC 1583<htmlurl |
1584 | url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default | |
1585 | value is no. | |
1586 | ||
1587 | <tag>area <M>id</M></tag> | |
3ca3e999 MM |
1588 | This defines an OSPF area with given area ID (an integer or an IPv4 |
1589 | address, similarly to a router ID). | |
1590 | The most important area is | |
1591 | the backbone (ID 0) to which every other area must be connected. | |
8fd12e6b | 1592 | |
b2bdb406 OF |
1593 | <tag>stub cost <M>num</M></tag> |
1594 | No external (except default) routes are flooded into stub areas. | |
1595 | Setting this value marks area stub with defined cost of default route. | |
1596 | Default value is no. (Area is not stub.) | |
8fd12e6b OF |
1597 | |
1598 | <tag>tick <M>num</M></tag> | |
3b16080c | 1599 | The routing table calculation and clean-up of areas' databases |
62eee823 | 1600 | is not performed when a single link state |
3ca3e999 | 1601 | change arrives. To lower the CPU utilization, it's processed later |
62eee823 | 1602 | at periodical intervals of <m/num/ seconds. The default value is 1. |
8fd12e6b | 1603 | |
16319aeb | 1604 | <tag>networks { <m/set/ }</tag> |
0c75411b | 1605 | Definition of area IP ranges. This is used in summary LSA origination. |
16319aeb OF |
1606 | Hidden networks are not propagated into other areas. |
1607 | ||
38675202 OZ |
1608 | <tag>stubnet <m/prefix/ { <m/options/ }</tag> |
1609 | Stub networks are networks that are not transit networks | |
1610 | between OSPF routers. They are also propagated through an | |
1611 | OSPF area as a part of a link state database. By default, | |
1612 | BIRD generates a stub network record for each primary network | |
1613 | address on each OSPF interface that does not have any OSPF | |
1614 | neighbors, and also for each non-primary network address on | |
1615 | each OSPF interface. This option allows to alter a set of | |
1616 | stub networks propagated by this router. | |
1617 | ||
1618 | Each instance of this option adds a stub network with given | |
1619 | network prefix to the set of propagated stub network, unless | |
1620 | option <cf/hidden/ is used. It also suppresses default stub | |
1621 | networks for given network prefix. When option | |
1622 | <cf/summary/ is used, also default stub networks that are | |
1623 | subnetworks of given stub network are suppressed. This might | |
1624 | be used, for example, to aggregate generated stub networks. | |
1625 | ||
3ca3e999 MM |
1626 | <tag>interface <M>pattern</M></tag> |
1627 | Defines that the specified interfaces belong to the area being defined. | |
f434d191 | 1628 | See <ref id="dsc-iface" name="interface"> common option for detailed description. |
8fd12e6b | 1629 | |
98ac6176 | 1630 | <tag>virtual link <M>id</M></tag> |
3b16080c OF |
1631 | Virtual link to router with the router id. Virtual link acts as a |
1632 | point-to-point interface belonging to backbone. The actual area is | |
1633 | used as transport area. This item cannot be in the backbone. | |
98ac6176 | 1634 | |
8fd12e6b | 1635 | <tag>cost <M>num</M></tag> |
3ca3e999 | 1636 | Specifies output cost (metric) of an interface. Default value is 10. |
8fd12e6b | 1637 | |
e3bc10fd OF |
1638 | <tag>stub <M>switch</M></tag> |
1639 | If set to interface it does not listen to any packet and does not send | |
1640 | any hello. Default value is no. | |
1641 | ||
8fd12e6b | 1642 | <tag>hello <M>num</M></tag> |
3ca3e999 MM |
1643 | Specifies interval in seconds between sending of Hello messages. Beware, all |
1644 | routers on the same network need to have the same hello interval. | |
8fd12e6b OF |
1645 | Default value is 10. |
1646 | ||
a190e720 OF |
1647 | <tag>poll <M>num</M></tag> |
1648 | Specifies interval in seconds between sending of Hello messages for | |
f02e4258 | 1649 | some neighbors on NBMA network. Default value is 20. |
a190e720 | 1650 | |
8fd12e6b | 1651 | <tag>retransmit <M>num</M></tag> |
4e8ec666 | 1652 | Specifies interval in seconds between retransmissions of unacknowledged updates. |
8fd12e6b OF |
1653 | Default value is 5. |
1654 | ||
1655 | <tag>priority <M>num</M></tag> | |
3ca3e999 MM |
1656 | On every multiple access network (e.g., the Ethernet) Designed Router |
1657 | and Backup Designed router are elected. These routers have some | |
1658 | special functions in the flooding process. Higher priority increases | |
1659 | preferences in this election. Routers with priority 0 are not | |
8fd12e6b OF |
1660 | eligible. Default value is 1. |
1661 | ||
1662 | <tag>wait <M>num</M></tag> | |
3ca3e999 | 1663 | After start, router waits for the specified number of seconds between starting |
8fd12e6b OF |
1664 | election and building adjacency. Default value is 40. |
1665 | ||
1666 | <tag>dead count <M>num</M></tag> | |
3ca3e999 MM |
1667 | When the router does not receive any messages from a neighbor in |
1668 | <m/dead count/*<m/hello/ seconds, it will consider the neighbor down. | |
8fd12e6b | 1669 | |
d8c7d9e8 OF |
1670 | <tag>dead <M>num</M></tag> |
1671 | When the router does not receive any messages from a neighbor in | |
1672 | <m/dead/ seconds, it will consider the neighbor down. If both directives | |
1673 | <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence. | |
1674 | ||
94c42054 OF |
1675 | <tag>rx buffer <M>num</M></tag> |
1676 | This sets the size of buffer used for receiving packets. The buffer should | |
1677 | be bigger than maximal size of any packets. Value NORMAL (default) | |
1678 | means 2*MTU, value LARGE means maximal allowed packet - 65536. | |
1679 | ||
3ca3e999 MM |
1680 | <tag>type broadcast</tag> |
1681 | BIRD detects a type of a connected network automatically, but sometimes it's | |
1682 | convenient to force use of a different type manually. | |
16319aeb OF |
1683 | On broadcast networks, flooding and Hello messages are sent using multicasts |
1684 | (a single packet for all the neighbors). | |
8fd12e6b | 1685 | |
e3bc10fd OF |
1686 | <tag>type pointopoint</tag> |
1687 | Point-to-point networks connect just 2 routers together. No election | |
1688 | is performed there which reduces the number of messages sent. | |
1689 | ||
3ca3e999 MM |
1690 | <tag>type nonbroadcast</tag> |
1691 | On nonbroadcast networks, the packets are sent to each neighbor | |
1692 | separately because of lack of multicast capabilities. | |
8fd12e6b | 1693 | |
e3bc10fd OF |
1694 | <tag>strict nonbroadcast <M>switch</M></tag> |
1695 | If set, don't send hello to any undefined neighbor. This switch | |
5f47fd85 | 1696 | is ignored on any non-NBMA network. Default is No. |
8fd12e6b | 1697 | |
4e8ec666 | 1698 | <tag>authentication none</tag> |
3ca3e999 | 1699 | No passwords are sent in OSPF packets. This is the default value. |
8fd12e6b | 1700 | |
4e8ec666 | 1701 | <tag>authentication simple</tag> |
3ca3e999 | 1702 | Every packet carries 8 bytes of password. Received packets |
4e8ec666 | 1703 | lacking this password are ignored. This authentication mechanism is |
8fd12e6b OF |
1704 | very weak. |
1705 | ||
ea357b8b | 1706 | <tag>authentication cryptographic</tag> |
b21f68b4 | 1707 | 16-byte long MD5 digest is appended to every packet. For the digest |
ea357b8b | 1708 | generation 16-byte long passwords are used. Those passwords are |
0c75411b | 1709 | not sent via network, so this mechanism is quite secure. |
ea357b8b OF |
1710 | Packets can still be read by an attacker. |
1711 | ||
5a203dac | 1712 | <tag>password "<M>text</M>"</tag> |
ea357b8b | 1713 | An 8-byte or 16-byte password used for authentication. |
f434d191 | 1714 | See <ref id="dsc-pass" name="password"> common option for detailed description. |
8fd12e6b | 1715 | |
5a203dac | 1716 | <tag>neighbors { <m/set/ } </tag> |
3ca3e999 | 1717 | A set of neighbors to which Hello messages on nonbroadcast networks |
a190e720 OF |
1718 | are to be sent. Some of them could be marked as eligible. |
1719 | ||
8fd12e6b OF |
1720 | </descrip> |
1721 | ||
1722 | <sect1>Attributes | |
1723 | ||
c27b2449 | 1724 | <p>OSPF defines four route attributes. Each internal route has a <cf/metric/. |
f06a219a OF |
1725 | Metric is ranging from 1 to infinity (65535). |
1726 | External routes use <cf/metric type 1/ or <cf/metric type 2/. | |
1727 | A <cf/metric of type 1/ is comparable with internal <cf/metric/, a | |
1728 | <cf/metric of type 2/ is always longer | |
1729 | than any <cf/metric of type 1/ or any <cf/internal metric/. | |
126683fe OZ |
1730 | <cf/Internal metric/ or <cf/metric of type 1/ is stored in attribute |
1731 | <cf/ospf_metric1/, <cf/metric type 2/ is stored in attribute <cf/ospf_metric2/. | |
94e2bbcc | 1732 | If you specify both metrics only metric1 is used. |
126683fe OZ |
1733 | |
1734 | Each external route can also carry attribute <cf/ospf_tag/ which is a | |
1735 | 32-bit integer which is used when exporting routes to other protocols; | |
f06a219a | 1736 | otherwise, it doesn't affect routing inside the OSPF domain at all. |
126683fe OZ |
1737 | The fourth attribute <cf/ospf_router_id/ is a router ID of the router |
1738 | advertising that route/network. This attribute is read-only. Default | |
1739 | is <cf/ospf_metric2 = 10000/ and <cf/ospf_tag = 0/. | |
8fd12e6b OF |
1740 | |
1741 | <sect1>Example | |
1742 | ||
1743 | <p> | |
1744 | ||
1745 | <code> | |
1746 | protocol ospf MyOSPF { | |
67b24e7c | 1747 | rfc1583compat yes; |
3b16080c | 1748 | tick 2; |
76c7efec OF |
1749 | export filter { |
1750 | if source = RTS_BGP then { | |
1751 | ospf_metric1 = 100; | |
1752 | accept; | |
1753 | } | |
98ac6176 | 1754 | reject; |
f434d191 | 1755 | }; |
8fd12e6b | 1756 | area 0.0.0.0 { |
8fd12e6b OF |
1757 | interface "eth*" { |
1758 | cost 11; | |
1759 | hello 15; | |
1760 | priority 100; | |
1761 | retransmit 7; | |
1762 | authentication simple; | |
1763 | password "aaa"; | |
1764 | }; | |
1765 | interface "ppp*" { | |
1766 | cost 100; | |
3b16080c | 1767 | authentication cryptographic; |
f434d191 OZ |
1768 | password "abc" { |
1769 | id 1; | |
1770 | generate to "22-04-2003 11:00:06"; | |
1771 | accept from "17-01-2001 12:01:05"; | |
1772 | }; | |
1773 | password "def" { | |
1774 | id 2; | |
1775 | generate to "22-07-2005 17:03:21"; | |
1776 | accept from "22-02-2001 11:34:06"; | |
3b16080c | 1777 | }; |
8fd12e6b | 1778 | }; |
e3bc10fd OF |
1779 | interface "arc0" { |
1780 | cost 10; | |
1781 | stub yes; | |
1782 | }; | |
3b16080c | 1783 | interface "arc1"; |
8fd12e6b OF |
1784 | }; |
1785 | area 120 { | |
1786 | stub yes; | |
98ac6176 OF |
1787 | networks { |
1788 | 172.16.1.0/24; | |
1789 | 172.16.2.0/24 hidden; | |
1790 | } | |
8fd12e6b OF |
1791 | interface "-arc0" , "arc*" { |
1792 | type nonbroadcast; | |
1793 | authentication none; | |
e3bc10fd | 1794 | strict nonbroadcast yes; |
a190e720 OF |
1795 | wait 120; |
1796 | poll 40; | |
1797 | dead count 8; | |
8fd12e6b | 1798 | neighbors { |
a190e720 | 1799 | 192.168.120.1 eligible; |
8fd12e6b OF |
1800 | 192.168.120.2; |
1801 | 192.168.120.10; | |
1802 | }; | |
1803 | }; | |
1804 | }; | |
1805 | } | |
1806 | </code> | |
1807 | ||
371adba6 | 1808 | <sect>Pipe |
1b55b1a3 | 1809 | |
371adba6 | 1810 | <sect1>Introduction |
a2a3ced8 MM |
1811 | |
1812 | <p>The Pipe protocol serves as a link between two routing tables, allowing routes to be | |
5a203dac | 1813 | passed from a table declared as primary (i.e., the one the pipe is connected to using the |
a2a3ced8 MM |
1814 | <cf/table/ configuration keyword) to the secondary one (declared using <cf/peer table/) |
1815 | and vice versa, depending on what's allowed by the filters. Export filters control export | |
1816 | of routes from the primary table to the secondary one, import filters control the opposite | |
1817 | direction. | |
1818 | ||
f98e2915 | 1819 | <p>The Pipe protocol may work in the opaque mode or in the transparent |
925fe2d3 | 1820 | mode. In the opaque mode, the Pipe protocol retransmits optimal route |
f98e2915 OZ |
1821 | from one table to the other table in a similar way like other |
1822 | protocols send and receive routes. Retransmitted route will have the | |
1823 | source set to the Pipe protocol, which may limit access to protocol | |
1824 | specific route attributes. The opaque mode is a default mode. | |
1825 | ||
1826 | <p>In transparent mode, the Pipe protocol retransmits all routes from | |
1827 | one table to the other table, retaining their original source and | |
1828 | attributes. If import and export filters are set to accept, then both | |
1829 | tables would have the same content. The mode can be set by | |
1830 | <tt/mode/ option. | |
1831 | ||
5a203dac | 1832 | <p>The primary use of multiple routing tables and the Pipe protocol is for policy routing, |
a2a3ced8 MM |
1833 | where handling of a single packet doesn't depend only on its destination address, but also |
1834 | on its source address, source interface, protocol type and other similar parameters. | |
f98e2915 | 1835 | In many systems (Linux being a good example), the kernel allows to enforce routing policies |
a2a3ced8 MM |
1836 | by defining routing rules which choose one of several routing tables to be used for a packet |
1837 | according to its parameters. Setting of these rules is outside the scope of BIRD's work | |
5a203dac | 1838 | (on Linux, you can use the <tt/ip/ command), but you can create several routing tables in BIRD, |
a2a3ced8 | 1839 | connect them to the kernel ones, use filters to control which routes appear in which tables |
5a203dac | 1840 | and also you can employ the Pipe protocol for exporting a selected subset of one table to |
a2a3ced8 MM |
1841 | another one. |
1842 | ||
371adba6 | 1843 | <sect1>Configuration |
a2a3ced8 MM |
1844 | |
1845 | <p><descrip> | |
f98e2915 | 1846 | <tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The |
a2a3ced8 | 1847 | primary one is selected by the <cf/table/ keyword. |
f98e2915 OZ |
1848 | |
1849 | <tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque. | |
a2a3ced8 MM |
1850 | </descrip> |
1851 | ||
371adba6 | 1852 | <sect1>Attributes |
a2a3ced8 MM |
1853 | |
1854 | <p>The Pipe protocol doesn't define any route attributes. | |
1855 | ||
371adba6 | 1856 | <sect1>Example |
a2a3ced8 MM |
1857 | |
1858 | <p>Let's consider a router which serves as a boundary router of two different autonomous | |
1859 | systems, each of them connected to a subset of interfaces of the router, having its own | |
1860 | exterior connectivity and wishing to use the other AS as a backup connectivity in case | |
1861 | of outage of its own exterior line. | |
1862 | ||
1863 | <p>Probably the simplest solution to this situation is to use two routing tables (we'll | |
1864 | call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that packets having | |
1865 | arrived from interfaces belonging to the first AS will be routed according to <cf/as1/ | |
1866 | and similarly for the second AS. Thus we have split our router to two logical routers, | |
1867 | each one acting on its own routing table, having its own routing protocols on its own | |
1868 | interfaces. In order to use the other AS's routes for backup purposes, we can pass | |
1869 | the routes between the tables through a Pipe protocol while decreasing their preferences | |
5a203dac | 1870 | and correcting their BGP paths to reflect the AS boundary crossing. |
a2a3ced8 MM |
1871 | |
1872 | <code> | |
1873 | table as1; # Define the tables | |
1874 | table as2; | |
1875 | ||
1876 | protocol kernel kern1 { # Synchronize them with the kernel | |
1877 | table as1; | |
1878 | kernel table 1; | |
1879 | } | |
1880 | ||
1881 | protocol kernel kern2 { | |
1882 | table as2; | |
1883 | kernel table 2; | |
1884 | } | |
1885 | ||
1886 | protocol bgp bgp1 { # The outside connections | |
1887 | table as1; | |
1888 | local as 1; | |
1889 | neighbor 192.168.0.1 as 1001; | |
1890 | export all; | |
1891 | import all; | |
1892 | } | |
1893 | ||
1894 | protocol bgp bgp2 { | |
1895 | table as2; | |
1896 | local as 2; | |
1897 | neighbor 10.0.0.1 as 1002; | |
1898 | export all; | |
1899 | import all; | |
1900 | } | |
1901 | ||
1902 | protocol pipe { # The Pipe | |
1903 | table as1; | |
1904 | peer table as2; | |
1905 | export filter { | |
1906 | if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks | |
1907 | if preference>10 then preference = preference-10; | |
1908 | if source=RTS_BGP then bgp_path.prepend(1); | |
1909 | accept; | |
1910 | } | |
1911 | reject; | |
1912 | }; | |
1913 | import filter { | |
1914 | if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks | |
1915 | if preference>10 then preference = preference-10; | |
1916 | if source=RTS_BGP then bgp_path.prepend(2); | |
1917 | accept; | |
1918 | } | |
1919 | reject; | |
1920 | }; | |
1921 | } | |
1922 | </code> | |
1923 | ||
1532a244 | 1924 | <sect>RIP |
d37f899b | 1925 | |
371adba6 | 1926 | <sect1>Introduction |
d37f899b | 1927 | |
1532a244 PM |
1928 | <p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts (to all its neighbors) |
1929 | distances to all networks it can reach. When a router hears distance to another network, it increments | |
d37f899b | 1930 | it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes |
1532a244 PM |
1931 | unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually, plus |
1932 | interface metric, which is usually one). After some time, the distance reaches infinity (that's 15 in | |
1933 | RIP) and all routers know that network is unreachable. RIP tries to minimize situations where | |
a7c9f7c0 | 1934 | counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't use |
a4601845 | 1935 | RIP on networks where maximal distance is higher than 15 hosts. You can read more about RIP at <HTMLURL |
074a166d | 1936 | URL="http://www.ietf.org/html.charters/rip-charter.html" name="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4 |
64722c98 | 1937 | (RFC 1723<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1723.txt">) |
074a166d | 1938 | and IPv6 (RFC 2080<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2080.txt">) versions of RIP are supported by BIRD, historical RIPv1 (RFC 1058<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1058.txt">)is |
b21f68b4 | 1939 | not currently supported. RIPv4 MD5 authentication (RFC 2082<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2082.txt">) is supported. |
440439e3 | 1940 | |
1532a244 PM |
1941 | <p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow |
1942 | convergence, big network load and inability to handle larger networks | |
0c75411b | 1943 | makes it pretty much obsolete. (It is still usable on very small networks.) |
d37f899b | 1944 | |
371adba6 | 1945 | <sect1>Configuration |
d37f899b | 1946 | |
1532a244 | 1947 | <p>In addition to options common for all to other protocols, RIP supports the following ones: |
d37f899b PM |
1948 | |
1949 | <descrip> | |
30c34a10 OF |
1950 | <tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that |
1951 | packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded | |
b21f68b4 | 1952 | into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic |
f434d191 | 1953 | hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf> |
5a203dac | 1954 | section. Default: none. |
7581b81b | 1955 | |
1532a244 PM |
1956 | <tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table |
1957 | be honored. (Always, when sent from a host on a directly connected | |
1958 | network or never.) Routing table updates are honored only from | |
5a203dac | 1959 | neighbors, that is not configurable. Default: never. |
d37f899b PM |
1960 | </descrip> |
1961 | ||
1962 | <p>There are two options that can be specified per-interface. First is <cf>metric</cf>, with | |
7581b81b | 1963 | default one. Second is <cf>mode multicast|broadcast|quiet|nolisten|version1</cf>, it selects mode for |
1b55b1a3 | 1964 | rip to work in. If nothing is specified, rip runs in multicast mode. <cf>version1</cf> is |
1532a244 PM |
1965 | currently equivalent to <cf>broadcast</cf>, and it makes RIP talk to a broadcast address even |
1966 | through multicast mode is possible. <cf>quiet</cf> option means that RIP will not transmit | |
1967 | any periodic messages to this interface and <cf>nolisten</cf> means that RIP will send to this | |
1968 | interface but not listen to it. | |
d37f899b | 1969 | |
1532a244 PM |
1970 | <p>The following options generally override behavior specified in RFC. If you use any of these |
1971 | options, BIRD will no longer be RFC-compliant, which means it will not be able to talk to anything | |
1972 | other than equally configured BIRD. I have warned you. | |
d37f899b PM |
1973 | |
1974 | <descrip> | |
0e7a720a | 1975 | <tag>port <M>number</M></tag> |
d150c637 | 1976 | selects IP port to operate on, default 520. (This is useful when testing BIRD, if you |
1532a244 | 1977 | set this to an address >1024, you will not need to run bird with UID==0). |
d37f899b | 1978 | |
0e7a720a | 1979 | <tag>infinity <M>number</M></tag> |
1532a244 | 1980 | selects the value of infinity, default is 16. Bigger values will make protocol convergence |
d37f899b PM |
1981 | even slower. |
1982 | ||
0e7a720a | 1983 | <tag>period <M>number</M> |
1532a244 | 1984 | </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower |
326e33f5 PM |
1985 | number will mean faster convergence but bigger network |
1986 | load. Do not use values lower than 10. | |
d37f899b | 1987 | |
f3b33928 | 1988 | <tag>timeout time <M>number</M> |
1532a244 | 1989 | </tag>specifies how old route has to be to be considered unreachable. Default is 4*<cf/period/. |
d37f899b | 1990 | |
f3b33928 | 1991 | <tag>garbage time <M>number</M> |
1532a244 | 1992 | </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/. |
d37f899b PM |
1993 | </descrip> |
1994 | ||
371adba6 | 1995 | <sect1>Attributes |
d37f899b | 1996 | |
1b55b1a3 MM |
1997 | <p>RIP defines two route attributes: |
1998 | ||
1999 | <descrip> | |
2000 | <tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/). | |
2001 | When routes from different RIP instances are available and all of them have the same | |
2002 | preference, BIRD prefers the route with lowest <cf/rip_metric/. | |
5a203dac | 2003 | When importing a non-RIP route, the metric defaults to 5. |
1b55b1a3 MM |
2004 | |
2005 | <tag>int <cf/rip_tag/</tag> RIP route tag: a 16-bit number which can be used | |
2006 | to carry additional information with the route (for example, an originating AS number | |
5a203dac | 2007 | in case of external routes). When importing a non-RIP route, the tag defaults to 0. |
1b55b1a3 MM |
2008 | </descrip> |
2009 | ||
371adba6 | 2010 | <sect1>Example |
1b55b1a3 MM |
2011 | |
2012 | <p><code> | |
d37f899b PM |
2013 | protocol rip MyRIP_test { |
2014 | debug all; | |
2015 | port 1520; | |
326e33f5 PM |
2016 | period 10; |
2017 | garbage time 60; | |
f434d191 OZ |
2018 | interface "eth0" { metric 3; mode multicast; }; |
2019 | interface "eth*" { metric 2; mode broadcast; }; | |
326e33f5 | 2020 | honor neighbor; |
d37f899b PM |
2021 | authentication none; |
2022 | import filter { print "importing"; accept; }; | |
2023 | export filter { print "exporting"; accept; }; | |
2024 | } | |
a0dd1c74 | 2025 | </code> |
d37f899b | 2026 | |
371adba6 | 2027 | <sect>Static |
1b55b1a3 | 2028 | |
0e4789c2 | 2029 | <p>The Static protocol doesn't communicate with other routers in the network, |
f8e2d916 | 2030 | but instead it allows you to define routes manually. This is often used for |
79a2b697 MM |
2031 | specifying how to forward packets to parts of the network which don't use |
2032 | dynamic routing at all and also for defining sink routes (i.e., those | |
2033 | telling to return packets as undeliverable if they are in your IP block, | |
2034 | you don't have any specific destination for them and you don't want to send | |
2035 | them out through the default route to prevent routing loops). | |
2036 | ||
2037 | <p>There are three types of static routes: `classical' routes telling to | |
2038 | forward packets to a neighboring router, device routes specifying forwarding | |
2039 | to hosts on a directly connected network and special routes (sink, blackhole | |
2040 | etc.) which specify a special action to be done instead of forwarding the | |
2041 | packet. | |
2042 | ||
2043 | <p>When the particular destination is not available (the interface is down or | |
2044 | the next hop of the route is not a neighbor at the moment), Static just | |
326e33f5 | 2045 | uninstalls the route from the table it is connected to and adds it again as soon |
a00c7a18 | 2046 | as the destination becomes adjacent again. |
79a2b697 | 2047 | |
79a2b697 | 2048 | <p>The Static protocol has no configuration options. Instead, the |
326e33f5 | 2049 | definition of the protocol contains a list of static routes: |
79a2b697 MM |
2050 | |
2051 | <descrip> | |
2052 | <tag>route <m/prefix/ via <m/ip/</tag> Static route through | |
2053 | a neighboring router. | |
2054 | <tag>route <m/prefix/ via <m/"interface"/</tag> Static device | |
2055 | route through an interface to hosts on a directly connected network. | |
2056 | <tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes | |
2057 | specifying to drop the packet, return it as unreachable or return | |
2058 | it as administratively prohibited. | |
2059 | </descrip> | |
2060 | ||
79a2b697 MM |
2061 | <p>Static routes have no specific attributes. |
2062 | ||
4f88ac47 | 2063 | <p>Example static config might look like this: |
79a2b697 MM |
2064 | |
2065 | <p><code> | |
2066 | protocol static { | |
96264d4d PM |
2067 | table testable; # Connect to a non-default routing table |
2068 | route 0.0.0.0/0 via 62.168.0.13; # Default route | |
2069 | route 62.168.0.0/25 reject; # Sink route | |
2070 | route 10.2.0.0/24 via "arc0"; # Secondary network | |
79a2b697 MM |
2071 | } |
2072 | </code> | |
2073 | ||
96264d4d PM |
2074 | <chapt>Conclusions |
2075 | ||
2076 | <sect>Future work | |
2077 | ||
2078 | <p>Although BIRD supports all the commonly used routing protocols, | |
2079 | there are still some features which would surely deserve to be | |
2080 | implemented in future versions of BIRD: | |
2081 | ||
2082 | <itemize> | |
96264d4d PM |
2083 | <item>OSPF NSSA areas and opaque LSA's |
2084 | <item>Route aggregation and flap dampening | |
2085 | <item>Generation of IPv6 router advertisements | |
2086 | <item>Multipath routes | |
2087 | <item>Multicast routing protocols | |
2088 | <item>Ports to other systems | |
2089 | </itemize> | |
2090 | ||
2091 | <sect>Getting more help | |
2092 | ||
2093 | <p>If you use BIRD, you're welcome to join the bird-users mailing list | |
2094 | (<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">) | |
2095 | where you can share your experiences with the other users and consult | |
2096 | your problems with the authors. To subscribe to the list, just send a | |
2097 | <tt/subscribe bird-users/ command in a body of a mail to | |
2098 | (<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">). | |
2099 | The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">. | |
2100 | ||
2101 | <p>BIRD is a relatively young system and it probably contains some | |
2102 | bugs. You can report any problems to the bird-users list and the authors | |
2103 | will be glad to solve them, but before you do so, | |
2104 | please make sure you have read the available documentation and that you are running the latest version (available at <HTMLURL | |
2105 | URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). (Of course, a patch | |
2106 | which fixes the bug is always welcome as an attachment.) | |
2107 | ||
2108 | <p>If you want to understand what is going inside, Internet standards are | |
2109 | a good and interesting reading. You can get them from <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" name="atrey.karlin.mff.cuni.cz:/pub/rfc">). | |
69477cad | 2110 | |
c184d9d0 | 2111 | <p><it/Good luck!/ |
69477cad | 2112 | |
371adba6 | 2113 | </book> |
7581b81b | 2114 | |
a0dd1c74 | 2115 | <!-- |
75317ab8 MM |
2116 | LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel |
2117 | LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps | |
5a203dac | 2118 | LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC |
75317ab8 MM |
2119 | LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth |
2120 | LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek | |
4e8ec666 | 2121 | LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC |
5a203dac | 2122 | LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU |
4e8ec666 | 2123 | LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc |
5a203dac | 2124 | LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats |
64722c98 | 2125 | LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt |
5adc02a6 | 2126 | LocalWords: proto wildcard Ondrej Filip |
5a64ac70 | 2127 | --> |