1 <!doctype birddoc system>
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.
10 This is a slightly modified linuxdoc dtd. Anything in <descrip> tags is considered definition of
11 configuration primitives, <cf> is fragment of configuration within normal text, <m> is
12 "meta" information within fragment of configuration - something in config which is not keyword.
16 Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
22 <title>BIRD User's Guide
24 Ondrej Filip <it/<feela@network.cz>/,
25 Pavel Machek <it/<pavel@ucw.cz>/,
26 Martin Mares <it/<mj@ucw.cz>/
30 This document contains user documentation for the BIRD Internet Routing Daemon project.
33 <!-- Table of contents -->
36 <!-- Begin the document -->
43 The name `BIRD' is actually an acronym standing for `BIRD Internet Routing Daemon'.
44 Let's take a closer look at the meaning of the name:
46 <p><em/BIRD/: Well, we think we have already explained that. It's an acronym standing
47 for `BIRD Internet Routing Daemon', you remember, don't you? :-)
49 <p><em/Internet Routing/: It's a program (well, a daemon, as you are going to discover in a moment)
50 which works as a dynamic router in an Internet type network (that is, in a network running either
51 the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected
52 networks in order to allow hosts not connected directly to the same local area network to
53 communicate with each other. They also communicate with the other routers in the Internet to discover
54 the topology of the network which allows them to find optimal (in terms of some metric) rules for
55 forwarding of packets (which are called routing tables) and to adapt themselves to the
56 changing conditions such as outages of network links, building of new connections and so on. Most of
57 these routers are costly dedicated devices running obscure firmware which is hard to configure and
58 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
59 computer to act as a router and forward packets belonging to the other hosts, but only according to
60 a statically configured table.
62 <p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program running on
63 background which does the dynamic part of Internet routing, that is it communicates
64 with the other routers, calculates routing tables and sends them to the OS kernel
65 which does the actual packet forwarding. There already exist other such routing
66 daemons: routed (RIP only), GateD (non-free), Zebra<HTMLURL URL="http://www.zebra.org">
67 and MRTD<HTMLURL URL="http://sourceforge.net/projects/mrt">, but their capabilities are
68 limited and they are relatively hard to configure and maintain.
70 <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
71 to support all the routing technology used in the today's Internet or planned to be
72 used in near future and to have a clean extensible architecture allowing new routing
73 protocols to be incorporated easily. Among other features, BIRD supports:
76 <item>both IPv4 and IPv6 protocols
77 <item>multiple routing tables
78 <item>the Border Gateway Protocol (BGPv4)
79 <item>the Routing Information Protocol (RIPv2)
80 <item>the Open Shortest Path First protocol (OSPFv2)
81 <item>a virtual protocol for exchange of routes between different routing tables on a single host
82 <item>a command-line interface allowing on-line control and inspection
83 of status of the daemon
84 <item>soft reconfiguration (no need to use complex online commands
85 to change the configuration, just edit the configuration file
86 and notify BIRD to re-read it and it will smoothly switch itself
87 to the new configuration, not disturbing routing protocols
88 unless they are affected by the configuration changes)
89 <item>a powerful language for route filtering
92 <p>BIRD has been developed at the Faculty of Math and Physics, Charles University, Prague,
93 Czech Republic as a student project. It can be freely distributed under the terms of the GNU General
96 <p>BIRD has been designed to work on all UNIX-like systems. It has been developed and
97 tested under Linux 2.0 to 2.4, and then ported to FreeBSD and NetBSD, porting to other
98 systems (even non-UNIX ones) should be relatively easy due to its highly modular architecture.
100 <sect>Installing BIRD
102 <p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) and Perl, installing BIRD should be as easy as:
108 vi /usr/local/etc/bird.conf
112 <p>You can use <tt>./configure --help</tt> to get a list of configure
113 options. The most important ones are:
114 <tt/--enable-ipv6/ which enables building of an IPv6 version of BIRD,
115 <tt/--with-protocols=/ to produce a slightly smaller BIRD executable by configuring out routing protocols you don't use, and
116 <tt/--prefix=/ to install BIRD to a place different from.
117 <file>/usr/local</file>.
121 <p>You can pass several command-line options to bird:
124 <tag>-c <m/config name/</tag>
125 use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
128 enable debug messages and run bird in foreground.
130 <tag>-D <m/filename of debug log/</tag>
131 log debugging information to given file instead of stderr
133 <tag>-s <m/name of communication socket/</tag>
134 use given filename for a socket for communications with the client, default is <it/prefix/<file>/var/run/bird.ctl</file>.
137 <p>BIRD writes messages about its work to log files or syslog (according to config).
139 <chapt>About routing tables
141 <p>BIRD has one or more routing tables which may or may not be
142 synchronized with OS kernel and which may or may not be synchronized with
143 each other (see the Pipe protocol). Each routing table contains a list of
144 known routes. Each route consists of:
147 <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)
148 <item>preference of this route
149 <item>IP address of router which told us about this route
150 <item>IP address of router we should forward the packets to
152 <item>other attributes common to all routes
153 <item>dynamic attributes defined by protocols which may or
154 may not be present (typically protocol metrics)
157 Routing table maintains multiple entries
158 for a network, but at most one entry for one network and one
159 protocol. The entry with the highest preference is used for routing (we
160 will call such an entry the <it/selected route/). If
161 there are more entries with the same preference and they are from the same
162 protocol, the protocol decides (typically according to metrics). If they aren't,
163 an internal ordering is used to break the tie. You can
164 get the list of route attributes in the Route attributes section.
166 <p>Each protocol is connected to a routing table through two filters
167 which can accept, reject and modify the routes. An <it/export/
168 filter checks routes passed from the routing table to the protocol,
169 an <it/import/ filter checks routes in the opposite direction.
170 When the routing table gets a route from a protocol, it recalculates
171 the selected route and broadcasts it to all protocols connected to
172 the table. The protocols typically send the update to other routers
179 <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <it/prefix/<file>/etc/bird.conf</file> (unless the
180 <tt/-c/ command line option is given). Configuration may be changed at user's request: if you modify
181 the config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new
182 config. Then there's the client
183 which allows you to talk with BIRD in an extensive way.
185 <p>In the config, everything on a line after <cf/#/ or inside <cf>/*
186 */</cf> is a comment, whitespace characters are treated as a single space. If there's a variable number of options, they are grouped using
187 the <cf/{ }/ brackets. Each option is terminated by a <cf/;/. Configuration
190 <p>Here is an example of a simple config file. It enables
191 synchronization of routing tables with OS kernel, scans for
192 new network interfaces every 10 seconds and runs RIP on all network interfaces found.
197 persist; # Don't remove routes on BIRD shutdown
198 scan time 20; # Scan kernel routing table every 20 seconds
199 export all; # Default is export none
203 scan time 10; # Scan interfaces every 10 seconds
216 <tag>log "<m/filename/"|syslog|stderr all|{ <m/list of classes/ }</tag>
217 Set logging of messages having the given class (either <cf/all/ or <cf/{
218 error, trace }/ etc.) into selected destination. Classes are:
219 <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
220 <cf/debug/ for debugging messages,
221 <cf/trace/ when you want to know what happens in the network,
222 <cf/remote/ for messages about misbehavior of remote machines,
223 <cf/auth/ about authentication failures,
224 <cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple
225 destinations. Default: log everything to the system log.
227 <tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
228 Set global defaults of protocol debugging options. See <cf/debug/ in the following section. Default: off.
230 <tag>debug commands <m/number/</tag>
231 Control logging of client connections (0 for no logging, 1 for
232 logging of connects and disconnects, 2 and higher for logging of
233 all client commands). Default: 0.
235 <tag>filter <m/name local variables/{ <m/commands/ }</tag> Define a filter. You can learn more about filters
236 in the following chapter.
238 <tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more
239 about functions in the following chapter.
241 <tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
242 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
243 about configuring protocols in their own chapters. You can run more than one instance of
244 most protocols (like RIP or BGP). By default, no instances are configured.
246 <tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/IP address/</tag> Define a constant. You can use it later in every place
247 you could use a simple integer or an IP address.
249 <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.
251 <tag>table <m/name/</tag> Create a new routing table. The default
252 routing table is created implicitly, other routing tables have
253 to be added by this command.
255 <tag>eval <m/expr/</tag> Evaluates given filter expression. It
256 is used by us for testing of filters.
259 <sect>Protocol options
261 <p>For each protocol instance, you can configure a bunch of options.
262 Some of them (those described in this section) are generic, some are
263 specific to the protocol (see sections talking about the protocols).
265 <p>Several options use a <cf><m/switch/</cf> argument. It can be either
266 <cf/on/, <cf/yes/ or a numeric expression with a non-zero value for the
267 option to be enabled or <cf/off/, <cf/no/ or a numeric expression evaluating
268 to zero to disable it. An empty <cf><m/switch/</cf> is equivalent to <cf/on/
269 ("silence means agreement").
272 <tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
274 <tag>disabled <m/switch/</tag> Disables the protocol. You can change the disable/enable status from the command
275 line interface without needing to touch the configuration. Disabled protocols are not activated. Default: protocol is enabled.
277 <tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
278 Set protocol debugging options. If asked, each protocol is capable of
279 writing trace messages about its work to the log (with category
280 <cf/trace/). You can either request printing of <cf/all/ trace messages
281 or only of the types selected: <cf/states/ for protocol state changes
282 (protocol going up, down, starting, stopping etc.),
283 <cf/routes/ for routes exchanged with the routing table,
284 <cf/filters/ for details on route filtering,
285 <cf/interfaces/ for interface change events sent to the protocol,
286 <cf/events/ for events internal to the protocol and
287 <cf/packets/ for packets sent and received by the protocol. Default: off.
289 <tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag>
290 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/.
292 <tag>export <m/filter/</tag> This is similar to the <cf>import</cf> keyword, except that it
293 works in the direction from the routing table to the protocol. Default: <cf/none/.
295 <tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
298 <p>There are several options that give sense only with certain protocols:
301 <tag>passwords { password "<m/password/" from <m/time/ to <m/time/ passive <m/time/ id
302 <m/num/ [...] }</tag> Specifies passwords to be used with this protocol. <cf>Passive <m/time/</cf> is
303 time from which the password is not used for sending, but it is recognized on reception. <cf/id/ is password ID as needed by
304 certain protocols. Format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
306 <tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [...] } ]</tag> Specifies which
307 interfaces is this protocol active on and allows you to set options on a
308 per-interface basis. Mask is specified as in shell-like patterns, thus <cf>interface
309 "*" { mode broadcast; };</cf> will start the protocol on all interfaces with <cf>mode
310 broadcast;</cf> option. If the first character of mask is <cf/-/, such interfaces are
311 excluded. Masks are parsed left-to-right, thus <cf/interface "-eth*", "*";/ means all but
312 the ethernets. Default: none.
316 <chapt>Remote control
318 <p>You can use the command-line client <file>birdc</file> to talk with
319 a running BIRD. Communication is done using a <file/bird.ctl/ UNIX domain
320 socket (unless changed with the <tt/-s/ option given to both the server and
321 the client). The commands can perform simple actions such as enabling/disabling
322 of protocols, telling BIRD to show various information, telling it to
323 show routing table filtered by filter, or asking BIRD to
324 reconfigure. Press <tt/?/ at any time to get online help. Option
325 <tt/-v/ can be passed to the client, to make it dump numeric return
326 codes along with the messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your
327 own applications could do that, too -- the format of communication between
328 BIRD and <file/birdc/ is stable (see the programmer's documentation).
330 <p>Here is a brief list of supported functions:
333 <tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
334 Dump contents of internal data structures to the debugging output.
336 <tag>show status</tag>
337 Show router status, that is BIRD version, uptime and time from last reconfiguration.
339 <tag>show protocols [all]</tag>
340 Show list of protocol instances along with tables they are connected to and protocol status, possibly giving verbose information, if <cf/all/ is specified.
342 <tag>show ospf [interface|neighbors] [<m/name/] ["<m/interface/"]</tag>
343 Show detailed information about OSPF protocol, possibly giving a verbose list of interfaces and neighbors. The <m/name/ of the protocol instance can be omitted if there exists only a single instance.
345 <tag>show static [<m/name/]</tag>
346 Show detailed information about static routes. The <m/name/ of the protocol instance can be omitted if there exists only a single instance.
348 <tag>show interfaces [summary]</tag>
349 Show the list of interfaces. For each interface, print its type, state, MTU and addresses assigned.
351 <tag>show symbols</tag>
352 Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
354 <tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(import|preimport) <m/p/] [<m/options/]</tag>
355 Show contents of a routing table (by default of the main one),
356 that is routes, their metrics and (in case the <cf/all/ switch is given)
357 all their attributes.
359 <p>You can specify a <m/prefix/ if you want to print routes for a
360 specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get
361 the entry which will be used for forwarding of packets to the given
362 destination. By default, all routes for each network are printed with
363 the selected one at the top, unless <cf/primary/ is given in which case
364 only the selected route is shown.
366 <p>You can also ask for printing only routes processed and accepted by
367 a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
368 </cf> or matching a given condition (<cf>where <m/condition/</cf>).
369 The <cf/import/ and <cf/preimport/ switches ask for printing of entries
370 that are imported to the specified protocol. With <cf/preimport/, the
371 import filter of the protocol is skipped.
373 <p>The <cf/stats/ switch requests showing of route statistics (the
374 number of networks, number of routes before and after filtering). If
375 you use <cf/count/ instead, only the statistics will be printed.
377 <tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
378 Enable, disable or restart a given protocol instance, instances matching the <cf><m/pattern/</cf> or <cf/all/ instances.
380 <tag>configure ["<m/config file/"]</tag>
381 Reload configuration from a given file.
386 <tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
387 Control protocol debugging.
394 <p>BIRD contains a simple programming language. (No, it can't yet read mail :-). There are
395 two objects in this language: filters and functions. Filters are interpreted by BIRD core when a route is
396 being passed between protocols and routing tables. The filter language contains control structures such
397 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>.
399 <p>Filter gets the route, looks at its attributes and
400 modifies some of them if it wishes. At the end, it decides whether to
401 pass the changed route through (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks
408 if defined( rip_metric ) then
414 if rip_metric > 10 then
415 reject "RIP metric is too big";
421 <p>As you can see, a filter has a header, a list of local variables, and a body. The header consists of
422 the <cf/filter/ keyword followed by a (unique) name of filter. The list of local variables consists of
423 <cf><M>type name</M>;</cf> pairs where each pair defines one local variable. The body consists of
424 <cf> { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You can group
425 several statements to a single compound statement by using braces (<cf>{ <M>statements</M> }</cf>) which is useful if
426 you want to make a bigger block of code conditional.
428 <p>BIRD supports functions, so that you don't have to repeat the same blocks of code over and
429 over. Functions can have zero or more parameters and they can have local variables. Recursion is not allowed. Function definitions
439 function with_parameters (int parameter)
445 <p>Unlike in C, variables are declared after the <cf/function/ line, but before the first <cf/{/. You can't declare
446 variables in nested blocks. Functions are called like in C: <cf>name();
447 with_parameters(5);</cf>. Function may return values using the <cf>return <m/[expr]/</cf>
448 command. Returning a value exits from current function (this is similar to C).
450 <p>Filters are declared in a way similar to functions except they can't have explicit
451 parameters. They get a route table entry as an implicit parameter, it is also passed automatically
452 to any functions called. The filter must terminate with either
453 <cf/accept/ or <cf/reject/ statement. If there's a runtime error in filter, the route
456 <p>A nice trick to debug filters is to use <cf>show route filter
457 <m/name/</cf> from the command line client. An example session might look
461 pavel@bug:~/bird$ ./birdc -s bird.ctl
464 10.0.0.0/8 dev eth0 [direct1 23:21] (240)
465 195.113.30.2/32 dev tunl1 [direct1 23:21] (240)
466 127.0.0.0/8 dev lo [direct1 23:21] (240)
468 show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
469 bird> show route filter { if 127.0.0.5 ˜ net then accept; }
470 127.0.0.0/8 dev lo [direct1 23:21] (240)
476 <p>Each variable and each value has certain type. Booleans, integers and enums are
477 incompatible with each other (that is to prevent you from shooting in the foot).
480 <tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
481 <cf/false/. Boolean is the only type you can use in <cf/if/
484 <tag/int/ This is a general integer type, you can expect it to store signed values from -2000000000
485 to +2000000000. Overflows are not checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
487 <tag/pair/ This is a pair of two short integers. Each component can have values from 0 to
488 65535. Literals of this type is written as <cf/(1234,5678)/.
490 <tag/string/ This is a string of characters. There are no ways to modify strings in
491 filters. You can pass them between functions, assign them to variables of type <cf/string/, print
492 such variables, but you can't concatenate two strings. String literals
493 are written as <cf/"This is a string constant"/.
495 <tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it
496 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>
497 on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP
498 address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
500 <tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
501 <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
502 <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
503 operators on prefixes:
504 <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
505 length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
507 <tag/int|ip|prefix|pair|enum set/
508 Filters recognize four types of sets. Sets are similar to strings: you can pass them around
509 but you can't modify them. Literals of type <cf>set int</cf> look like <cf>
510 [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
511 sets. Sets of prefixes are special: you can specify which prefix lengths should match them by
512 using <cf>[ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]</cf>. <cf>3.0.0.0/8{5,6}</cf> matches
513 prefixes <cf/3.X.X.X/ whose prefix length is 5 to 6. <cf><m>address</m>/<m>num</m>+</cf> is a shorthand for <cf><m>address</m>/{0,<m/num/}</cf>,
514 <cf><m>address</m>/<m/num/-</cf> is a shorthand for <cf><m>address</m>/{0,<m/num-1/}</cf>. For example,
515 <cf>1.2.0.0/16 ˜ [ 1.0.0.0/8{ 15 , 17 } ]</cf> is true, but
516 <cf>1.0.0.0/8 ˜ [ 1.0.0.0/8- ]</cf> is false.
519 Enumeration types are fixed sets of possibilities. You can't define your own
520 variables of such type, but some route attributes are of enumeration
521 type. Enumeration types are incompatible with each other.
524 BGP path is a list of autonomous system numbers. You can't write literals of this type.
527 BGP masks are patterns used for BGP path matching
528 (using <cf>path ˜ /2 3 5 ?/</cf> syntax). The masks
529 resemble wildcard patterns as used by UNIX shells. Autonomous
530 system numbers match themselves, <cf/?/ matches any (even empty)
531 sequence of arbitrary AS numbers (<cf/*/ hasn't been chosen, because
532 <cf>/*</cf> starts a comment). For example:
533 <tt>/4 3 2 1/ ˜ /? 4 3 ?/</tt> is true, but
534 <tt>/4 3 2 1/ ˜ /? 4 5 ?/</tt> is false.
536 Community list is similar to set of pairs,
537 except that unlike other sets, it can be modified.
538 There exist no literals of this type.
544 <p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
545 <cf/(a=b, a!=b, a<b, a>=b)/. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/).
546 Special operators include <cf/˜/ for "is element of a set" operation - it can be
547 used on element and set of elements of the same type (returning true if element is contained in the given set), or on IP and prefix (returning true if IP is within the range defined by that prefix), or on
548 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 and clist (returning true if the community is element of the community list).
551 <sect>Control structures
553 <p>Filters support two control structures: conditions and case switches.
555 <p>Syntax of a condition is: <cf>if
556 <M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
557 <M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
558 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.
560 <p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else |
561 <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ ... ] }</cf>. The expression after
562 <cf>case</cf> can be of any type which can be on the left side of the ˜ operator and anything that could
563 be a member of a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ grouping.
564 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.
566 <p>Here is example that uses <cf/if/ and <cf/case/ structures:
570 2: print "two"; print "I can do more commands without {}";
571 3 .. 5: print "three to five";
572 else: print "something else";
575 if 1234 = i then printn "."; else {
577 print "You need {} around multiple commands";
581 <sect>Route attributes
583 <p>A filter is implicitly passed a route, and it can access its
584 attributes just like it accesses variables. Attempts to access undefined
585 attribute result in a runtime error; you can check if an attribute is
586 defined by using the <cf>defined( <m>attribute</m> )</cf> operator.
589 <tag><m/prefix/ net</tag>
590 Network the route is talking about. Read-only. (See the chapter about routing tables.)
592 <tag><m/enum/ scope</tag>
593 Address scope of the network (<cf/SCOPE_HOST/ for addresses local to this host, <cf/SCOPE_LINK/ for those specific for a physical link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private addresses, <cf/SCOPE_UNIVERSE/ for globally visible addresses).
595 <tag><m/int/ preference</tag>
596 Preference of the route. (See the chapter about routing tables.)
598 <tag><m/ip/ from</tag>
599 The router which the route has originated from. Read-only.
602 Next hop packets routed using this route should be forwarded to.
604 <tag><m/enum/ source</tag>
605 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_EXT/, <cf/RTS_BGP/, <cf/RTS_PIPE/.
607 <tag><m/enum/ cast</tag>
608 Route type (<cf/RTC_UNICAST/ for normal routes, <cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ for broadcast, multicast and anycast routes). Read-only.
610 <tag><m/enum/ dest</tag>
611 Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_NETWORK/ 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.
614 <p>There also exist some protocol-specific attributes which are described in the corresponding protocol sections.
616 <sect>Other statements
618 <p>The following statements are available:
621 <tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
623 <tag>accept|reject [ <m/expr/ ]</tag> Accept or reject the route, possibly printing <cf><m>expr</m></cf>.
625 <tag>return <m/expr/</tag> Return <cf><m>expr</m></cf> from the current function, the function ends at this point.
627 <tag>print|printn <m/expr/ [<m/, expr.../]</tag>
628 Prints given expressions; useful mainly while debugging
629 filters. The <cf/printn/ variant does not terminate the line.
632 Terminates BIRD. Useful when debugging the filter interpreter.
639 <p>The Border Gateway Protocol is the routing protocol used for backbone
640 level routing in the today's Internet. Contrary to the other protocols, its convergence
641 doesn't rely on all routers following the same rules for route selection,
642 making it possible to implement any routing policy at any router in the
643 network, the only restriction being that if a router advertises a route,
644 it must accept and forward packets according to it.
646 <p>BGP works in terms of autonomous systems (often abbreviated as AS). Each
647 AS is a part of the network with common management and common routing policy. It is identified by a unique 16-bit number.
648 Routers within each AS usually communicate with each other using either a interior routing
649 protocol (such as OSPF or RIP) or an interior variant of BGP (called iBGP).
650 Boundary routers at the border of the AS communicate with their peers
651 in the neighboring AS'es via exterior BGP (eBGP).
653 <p>Each BGP router sends to its neighbors updates of the parts of its
654 routing table it wishes to export along with complete path information
655 (a list of AS'es the packet will travel through if it uses the particular
656 route) in order to avoid routing loops.
658 <p>BIRD supports all requirements of the BGP4 standard as defined in
659 RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
660 It also supports the community attributes
661 (RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
662 capability negotiation
663 (RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
664 MD5 password authentication
665 (RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
667 (RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
669 (RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">).
672 For IPv6, it uses the standard multiprotocol extensions defined in
673 RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
674 including changes described in the
675 latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
676 and applied to IPv6 according to
677 RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
679 <sect1>Route selection rules
681 <p>BGP doesn't have any simple metric, so the rules for selection of an optimal
682 route among multiple BGP routes with the same preference are a bit more complex
683 and they are implemented according to the following algorithm. It starts the first
684 rule, if there are more "best" routes, then it uses the second rule to choose
685 among them and so on.
688 <item>Prefer route with the highest Local Preference attribute.
689 <item>Prefer route with the shortest AS path.
690 <item>Prefer IGP origin over EGP and EGP over incomplete.
691 <item>Prefer the lowest value of the Multiple Exit Discriminator.
692 <item>Prefer internal routes over external ones.
693 <item>Prefer the route with the lowest value of router ID of the
699 <p>Each instance of the BGP corresponds to one neighboring router.
700 This allows to set routing policy and all the other parameters differently
701 for each neighbor using the following configuration parameters:
704 <tag>local as <m/number/</tag> Define which AS we are part of. (Note that
705 contrary to other IP routers, BIRD is able to act as a router located
706 in multiple AS'es simultaneously, but in such cases you need to tweak
707 the BGP paths manually in the filters to get consistent behavior.)
708 This parameter is mandatory.
710 <tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router
711 this instance will be talking to and what AS it's located in. Unless
712 you use the <cf/multihop/ clause, it must be directly connected to one
713 of your router's interfaces. In case the neighbor is in the same AS
714 as we are, we automatically switch to iBGP. This parameter is mandatory.
716 <tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a
717 neighbor which is connected at most <m/number/ hops far and to which
718 we should route via our direct neighbor with address <m/ip/.
719 Default: switched off.
721 <tag>next hop self</tag> Avoid calculation of the Next Hop attribute
722 and always advertise our own source address (see below) as a next hop.
723 This needs to be used only
724 occasionally to circumvent misconfigurations of other routers.
727 <tag>source address <m/ip/</tag> Define local address we should use
728 for next hop calculation. Default: the address of the local end
729 of the interface our neighbor is connected to.
731 <tag>password <m/string/</tag> Use this password for MD5 authentication
732 of BGP sessions. Default: no authentication.
734 <tag>rr client</tag> Be a route reflector and treat the neighbor as
735 a route reflection client. Default: disabled.
737 <tag>rr cluster id <m/IPv4 address/</tag> Route reflectors use cluster id
738 to avoid route reflection loops. When there is one route reflector in a cluster
739 it usually uses its router id as a cluster id, but when there are more route
740 reflectors in a cluster, these need to be configured (using this option) to
741 use a common cluster id. Clients in a cluster need not known their cluster
742 id and this option is not allowed to them Default: a same as router id.
744 <tag>rs client</tag> Be a route server and treat the neighbor
745 as a route server client. A route server is used as a
746 replacement for full mesh EBGP routing in Internet exchange
747 points in a similar way to route reflectors used in IBGP routing.
748 Bird does not implement obsoleted RFC 1863, but uses ad-hoc implementation,
749 which behaves like plain EBGP but reduces modifications to advertised route
750 attributes to be transparent (for example does not prepend its AS number to
751 AS PATH attribute and keep MED attribute). Default: disabled.
753 <tag>enable as4 <m/switch/</tag> BGP protocol was designed to use 2B AS numbers
754 and was extended later to allow 4B AS number. BIRD supports 4B AS extension,
755 but by disabling this option it can be persuaded not to advertise it and
756 to maintain old-style sessions with its neighbors. This might be useful for
757 circumventing bugs in neighbor's implementation of 4B AS extension.
758 Even when disabled (off), BIRD behaves internally as AS4-aware BGP router.
761 <tag>disable after error <m/switch/</tag> When an error is encountered (either
762 locally or by the other side), disable the instance automatically
763 and wait for an administrator to fix the problem manually. Default: off.
765 <tag>hold time <m/number/</tag> Time in seconds to wait for a Keepalive
766 message from the other side before considering the connection stale.
767 Default: depends on agreement with the neighboring router, we prefer
768 240 seconds if the other side is willing to accept it.
770 <tag>startup hold time <m/number/</tag> Value of the hold timer used
771 before the routers have a chance to exchange open messages and agree
772 on the real value. Default: 240 seconds.
774 <tag>keepalive time <m/number/</tag> Delay in seconds between sending
775 of two consecutive Keepalive messages. Default: One third of the hold time.
777 <tag>connect retry time <m/number/</tag> Time in seconds to wait before
778 retrying a failed attempt to connect. Default: 120 seconds.
780 <tag>start delay time <m/number/</tag> Delay in seconds between protocol
781 startup and the first attempt to connect. Default: 5 seconds.
783 <tag>error wait time <m/number/,<m/number/</tag> Minimum and maximum delay in seconds between a protocol
784 failure (either local or reported by the peer) and automatic restart.
785 Doesn't apply when <cf/disable after error/ is configured. If consecutive
786 errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300.
788 <tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol
789 failures to treat them as a error sequence which makes the <cf/error wait time/
790 increase exponentially. Default: 300 seconds.
792 <tag>path metric <m/switch/</tag> Enable comparison of path lengths
793 when deciding which BGP route is the best one. Default: on.
795 <tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
796 Discriminator to be used during route selection when the MED attribute
797 is missing. Default: 0.
799 <tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference
800 to be used during route selection when the Local Preference attribute
801 is missing. Default: 0.
806 <p>BGP defines several route attributes. Some of them (those marked with `<tt/I/' in the
807 table below) are available on internal BGP connections only, some of them (marked
808 with `<tt/O/') are optional.
811 <tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
812 the packet will travel through when forwarded according to the particular route. In case of
813 internal BGP it doesn't contain the number of the local AS.
815 <tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for
816 selection among multiple BGP routes (see the selection rules above). It's
817 used as an additional metric which is propagated through the whole local AS.
819 <tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
820 is an optional attribute which is used on on external (inter-AS) links to
821 convey to an adjacent AS the optimal entry point into the local AS.
822 The received attribute may be also propagated over internal BGP links
823 (and this is default behavior). The attribute value is zeroed when a route
824 is exported from a routing table to a BGP instance to ensure that the attribute
825 received from a neighboring AS is not propagated to other neighboring ASes.
826 A new value might be set in the export filter of a BGP instance.
827 See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
828 for further discussion of BGP MED attribute.
830 <tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
831 if the route has originated in an interior routing protocol or
832 <cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
833 (nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
836 <tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets
837 to this destination. On internal BGP connections, it's an address of the
838 originating router if it's inside the local AS or a boundary router the
839 packet will leave the AS through if it's an exterior route, so each BGP
840 speaker within the AS has a chance to use the shortest interior path
841 possible to this point.
843 <tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute
844 which carries no value, but the sole presence of which indicates that the route
845 has been aggregated from multiple routes by some router on the path from
848 <!-- we don't handle aggregators right since they are of a very obscure type
849 <tag>bgp_aggregator</tag>
851 <tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
852 with the route. Each such value is a pair (represented as a <cf/pair/ data
853 type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
854 the community and the second one being a per-AS identifier. There are lots
855 of uses of the community mechanism, but generally they are used to carry
856 policy information like "don't export to USA peers". As each AS can define
857 its own routing policy, it also has a complete freedom about which community
858 attributes it defines and what will their semantics be.
865 local as 65000; # Use a private AS number
866 neighbor 62.168.0.130 as 5588; # Our neighbor ...
867 multihop 20 via 62.168.0.13; # ... which is connected indirectly
868 export filter { # We use non-trivial export rules
869 if source = RTS_STATIC then { # Export only static routes
870 # Assign our community
871 bgp_community.add((65000,5678));
872 # Artificially increase path length
873 # by advertising local AS number twice
874 if bgp_path ~ / 65000 / then
875 bgp_path.prepend(65000);
881 source address 62.168.0.1; # Use a non-standard source address
887 <p>The Device protocol is not a real routing protocol. It doesn't generate
888 any routes and it only serves as a module for getting information about network
889 interfaces from the kernel.
891 <p>Except for very unusual circumstances, you probably should include
892 this protocol in the configuration since almost all other protocols
893 require network interfaces to be defined for them to work with.
895 <p>The only configurable thing is interface scan time:
898 <tag>scan time <m/number/</tag> Time in seconds between two scans
899 of the network interface list. On systems where we are notified about
900 interface status changes asynchronously (such as newer versions of
901 Linux), we need to scan the list only in order to avoid confusion by lost
902 notification messages, so the default time is set to a large value.
905 <p>As the Device protocol doesn't generate any routes, it cannot have
906 any attributes. Example configuration looks really simple:
910 scan time 10; # Scan the interfaces often
916 <p>The Direct protocol is a simple generator of device routes for all the
917 directly connected networks according to the list of interfaces provided
918 by the kernel via the Device protocol.
920 <p>It's highly recommended to include this protocol in your configuration
921 unless you want to use BIRD as a route server or a route reflector, that is
922 on a machine which doesn't forward packets itself and only participates in
923 distribution of routing information.
925 <p>The only configurable thing about direct is what interfaces it watches:
928 <tag>interface <m/pattern [, ...]/</tag> By default, the Direct
929 protocol will generate device routes for all the interfaces
930 available. If you want to restrict it to some subset of interfaces
931 (for example if you're using multiple routing tables for policy
932 routing and some of the policy domains don't contain all interfaces),
933 just use this clause.
936 <p>Direct device routes don't contain any specific attributes.
938 <p>Example config might look like this:
942 interface "-arc*", "*"; # Exclude the ARCnets
948 <p>The Kernel protocol is not a real routing protocol. Instead of communicating
949 the with other routers in the network, it performs synchronization of BIRD's routing
950 tables with the OS kernel. Basically, it sends all routing table updates to the kernel
951 and from time to time it scans the kernel tables to see whether some routes have
952 disappeared (for example due to unnoticed up/down transition of an interface)
953 or whether an `alien' route has been added by someone else (depending on the
954 <cf/learn/ switch, such routes are either deleted or accepted to our
957 <p>If your OS supports only a single routing table, you can configure only one
958 instance of the Kernel protocol. If it supports multiple tables (in order to
959 allow policy routing; such an OS is for example Linux 2.2), you can run as many instances as you want, but each of
960 them must be connected to a different BIRD routing table and to a different
966 <tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
967 routing tables when it exits (instead of cleaning them up).
968 <tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
969 kernel routing table.
970 <tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
971 routing tables by other routing daemons or by the system administrator.
972 This is possible only on systems which support identification of route
974 <tag>kernel table <m/number/</tag> Select which kernel table should
975 this particular instance of the Kernel protocol work with. Available
976 only on systems supporting multiple routing tables.
979 <p>The Kernel protocol doesn't define any route attributes.
980 <p>A simple configuration can look this way:
989 <p>Or for a system with two routing tables:
992 protocol kernel { # Primary routing table
993 learn; # Learn alien routes from the kernel
994 persist; # Don't remove routes on bird shutdown
995 scan time 10; # Scan kernel routing table every 10 seconds
1000 protocol kernel { # Secondary routing table
1011 <p>Open Shortest Path First (OSPF) is a quite complex interior gateway
1012 protocol. The current IPv4 version (OSPFv2) is defined
1013 in RFC 2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt">. It's a link
1014 state (a.k.a. shortest path first) protocol -- each router maintains a database
1015 describing the autonomous system's topology. Each participating router
1016 has an identical copy of the database and all routers run the same algorithm
1017 calculating a shortest path tree with themselves as a root.
1018 OSPF chooses the least cost path as the best path.
1019 (OSPFv3 - OSPF for IPv6 is not supported yet.)
1021 <p>In OSPF, the autonomous system can be split to several areas in order
1022 to reduce the amount of resources consumed for exchanging the routing
1023 information and to protect the other areas from incorrect routing data.
1024 Topology of the area is hidden to the rest of the autonomous system.
1026 <p>Another very important feature of OSPF is that
1027 it can keep routing information from other protocols (like Static or BGP)
1028 in its link state database as external routes. Each external route can
1029 be tagged by the advertising router, making it possible to pass additional
1030 information between routers on the boundary of the autonomous system.
1032 <p>OSPF quickly detects topological changes in the autonomous system (such
1033 as router interface failures) and calculates new loop-free routes after a short
1034 period of convergence. Only a minimal amount of
1035 routing traffic is involved.
1037 <p>Each router participating in OSPF routing periodically sends Hello messages
1038 to all its interfaces. This allows neighbors to be discovered dynamically.
1039 Then the neighbors exchange theirs parts of the link state database and keep it
1040 identical by flooding updates. The flooding process is reliable and ensures
1041 that each router detects all changes.
1043 <sect1>Configuration
1045 <p>In the main part of configuration, there can be multiple definitions of
1046 OSPF area witch different id included. These definitions includes many other
1047 switches and multiple definitions of interfaces. Definition of interface
1048 may contain many switches and constant definitions and list of neighbors
1049 on nonbroadcast networks.
1052 protocol ospf <name> {
1053 rfc1583compat <switch>;
1056 stub cost <num>;
1059 <prefix> hidden;
1061 interface <interface pattern>
1064 stub <switch>;
1067 retransmit <num>;
1068 priority <num>;
1070 dead count <num>;
1072 rx buffer [normal|large|<num>];
1073 type [broadcast|nonbroadcast|pointopoint];
1074 strict nonbroadcast <switch>;
1075 authentication [none|simple|cryptographics];
1076 password "<text>";
1077 password "<text>" {
1079 generate from "<date>";
1080 generate to "<date>";
1081 accept from "<date>";
1082 accept to "<date>";
1086 <ip> eligible;
1089 virtual link <id>
1092 retransmit <num>;
1094 dead count <num>;
1096 authentication [none|simple];
1097 password "<text>";
1104 <tag>rfc1583compat <M>switch</M></tag>
1105 This option controls compatibility of routing table
1106 calculation with RFC 1583<htmlurl
1107 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1110 <tag>area <M>id</M></tag>
1111 This defines an OSPF area with given area ID (an integer or an IPv4
1112 address, similarly to a router ID).
1113 The most important area is
1114 the backbone (ID 0) to which every other area must be connected.
1116 <tag>stub cost <M>num</M></tag>
1117 No external (except default) routes are flooded into stub areas.
1118 Setting this value marks area stub with defined cost of default route.
1119 Default value is no. (Area is not stub.)
1121 <tag>tick <M>num</M></tag>
1122 The routing table calculation and clean-up of areas' databases
1123 is not performed when a single link state
1124 change arrives. To lower the CPU utilization, it's processed later
1125 at periodical intervals of <m/num/ seconds. The default value is 1.
1127 <tag>networks { <m/set/ }</tag>
1128 Definition of area IP ranges. This is used in summary lsa origination.
1129 Hidden networks are not propagated into other areas.
1131 <tag>interface <M>pattern</M></tag>
1132 Defines that the specified interfaces belong to the area being defined.
1134 <tag>virtual link <M>id</M></tag>
1135 Virtual link to router with the router id. Virtual link acts as a
1136 point-to-point interface belonging to backbone. The actual area is
1137 used as transport area. This item cannot be in the backbone.
1139 <tag>cost <M>num</M></tag>
1140 Specifies output cost (metric) of an interface. Default value is 10.
1142 <tag>stub <M>switch</M></tag>
1143 If set to interface it does not listen to any packet and does not send
1144 any hello. Default value is no.
1146 <tag>hello <M>num</M></tag>
1147 Specifies interval in seconds between sending of Hello messages. Beware, all
1148 routers on the same network need to have the same hello interval.
1149 Default value is 10.
1151 <tag>poll <M>num</M></tag>
1152 Specifies interval in seconds between sending of Hello messages for
1153 some neighbors on NBMA network. Default value is 20.
1155 <tag>retransmit <M>num</M></tag>
1156 Specifies interval in seconds between retransmissions of unacknowledged updates.
1159 <tag>priority <M>num</M></tag>
1160 On every multiple access network (e.g., the Ethernet) Designed Router
1161 and Backup Designed router are elected. These routers have some
1162 special functions in the flooding process. Higher priority increases
1163 preferences in this election. Routers with priority 0 are not
1164 eligible. Default value is 1.
1166 <tag>wait <M>num</M></tag>
1167 After start, router waits for the specified number of seconds between starting
1168 election and building adjacency. Default value is 40.
1170 <tag>dead count <M>num</M></tag>
1171 When the router does not receive any messages from a neighbor in
1172 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
1174 <tag>dead <M>num</M></tag>
1175 When the router does not receive any messages from a neighbor in
1176 <m/dead/ seconds, it will consider the neighbor down. If both directives
1177 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
1179 <tag>rx buffer <M>num</M></tag>
1180 This sets the size of buffer used for receiving packets. The buffer should
1181 be bigger than maximal size of any packets. Value NORMAL (default)
1182 means 2*MTU, value LARGE means maximal allowed packet - 65536.
1184 <tag>type broadcast</tag>
1185 BIRD detects a type of a connected network automatically, but sometimes it's
1186 convenient to force use of a different type manually.
1187 On broadcast networks, flooding and Hello messages are sent using multicasts
1188 (a single packet for all the neighbors).
1190 <tag>type pointopoint</tag>
1191 Point-to-point networks connect just 2 routers together. No election
1192 is performed there which reduces the number of messages sent.
1194 <tag>type nonbroadcast</tag>
1195 On nonbroadcast networks, the packets are sent to each neighbor
1196 separately because of lack of multicast capabilities.
1198 <tag>strict nonbroadcast <M>switch</M></tag>
1199 If set, don't send hello to any undefined neighbor. This switch
1200 is ignored on on any non-NBMA network. Default is No.
1202 <tag>authentication none</tag>
1203 No passwords are sent in OSPF packets. This is the default value.
1205 <tag>authentication simple</tag>
1206 Every packet carries 8 bytes of password. Received packets
1207 lacking this password are ignored. This authentication mechanism is
1210 <tag>authentication cryptographic</tag>
1211 16-byte long MD5 digest is appended to every packet. For the digest
1212 generation 16-byte long passwords are used. Those passwords are
1213 not sent via network, so this mechanismus is quite secure.
1214 Packets can still be read by an attacker.
1216 <tag>password "<M>text</M>"</tag>
1217 An 8-byte or 16-byte password used for authentication.
1219 <tag>id <M>num</M></tag>
1220 ID of the password, (0-255). If it's not used, BIRD will choose
1221 ID based on an order of the password item in the interface. For
1222 example, second password item in one interface will have default
1225 <tag>generate from <M>date</M></tag>
1226 The start time of the usage of the password for packet signing.
1228 <tag>generate to <M>date</M></tag>
1229 The last time of the usage of the password for packet signing.
1231 <tag>accept from <M>date</M></tag>
1232 The start time of the usage of the password for packet verification.
1234 <tag>accept to <M>date</M></tag>
1235 The last time of the usage of the password for packet verification.
1237 <tag>neighbors { <m/set/ } </tag>
1238 A set of neighbors to which Hello messages on nonbroadcast networks
1239 are to be sent. Some of them could be marked as eligible.
1245 <p>OSPF defines three route attributes. Each internal route has a <cf/metric/
1246 Metric is ranging from 1 to infinity (65535).
1247 External routes use <cf/metric type 1/ or <cf/metric type 2/.
1248 A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
1249 <cf/metric of type 2/ is always longer
1250 than any <cf/metric of type 1/ or any <cf/internal metric/.
1251 If you specify both metrics only metric1 is used.
1252 Each external route can also carry a <cf/tag/ which is a 32-bit
1253 integer which is used when exporting routes to other protocols;
1254 otherwise, it doesn't affect routing inside the OSPF domain at all.
1255 Default is <cf/metric of type 2 = 10000/ and <cf/tag = 0/.
1262 protocol ospf MyOSPF {
1263 rfc1583compatibility yes;
1266 if source = RTS_BGP then {
1278 authentication simple;
1283 authentication cryptographic;
1287 generate to "22-04-2003 11:00:06";
1288 accept from "17-01-2001 12:01:05";
1292 generate to "22-07-2005 17:03:21";
1293 accept from "22-02-2001 11:34:06";
1307 172.16.2.0/24 hidden;
1309 interface "-arc0" , "arc*" {
1311 authentication none;
1312 strict nonbroadcast yes;
1317 192.168.120.1 eligible;
1330 <p>The Pipe protocol serves as a link between two routing tables, allowing routes to be
1331 passed from a table declared as primary (i.e., the one the pipe is connected to using the
1332 <cf/table/ configuration keyword) to the secondary one (declared using <cf/peer table/)
1333 and vice versa, depending on what's allowed by the filters. Export filters control export
1334 of routes from the primary table to the secondary one, import filters control the opposite
1337 <p>The primary use of multiple routing tables and the Pipe protocol is for policy routing,
1338 where handling of a single packet doesn't depend only on its destination address, but also
1339 on its source address, source interface, protocol type and other similar parameters.
1340 In many systems (Linux 2.2 being a good example), the kernel allows to enforce routing policies
1341 by defining routing rules which choose one of several routing tables to be used for a packet
1342 according to its parameters. Setting of these rules is outside the scope of BIRD's work
1343 (on Linux, you can use the <tt/ip/ command), but you can create several routing tables in BIRD,
1344 connect them to the kernel ones, use filters to control which routes appear in which tables
1345 and also you can employ the Pipe protocol for exporting a selected subset of one table to
1348 <sect1>Configuration
1351 <tag>peer table <m/table/</tag> Define secondary routing table to connect to. The
1352 primary one is selected by the <cf/table/ keyword.
1357 <p>The Pipe protocol doesn't define any route attributes.
1361 <p>Let's consider a router which serves as a boundary router of two different autonomous
1362 systems, each of them connected to a subset of interfaces of the router, having its own
1363 exterior connectivity and wishing to use the other AS as a backup connectivity in case
1364 of outage of its own exterior line.
1366 <p>Probably the simplest solution to this situation is to use two routing tables (we'll
1367 call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that packets having
1368 arrived from interfaces belonging to the first AS will be routed according to <cf/as1/
1369 and similarly for the second AS. Thus we have split our router to two logical routers,
1370 each one acting on its own routing table, having its own routing protocols on its own
1371 interfaces. In order to use the other AS's routes for backup purposes, we can pass
1372 the routes between the tables through a Pipe protocol while decreasing their preferences
1373 and correcting their BGP paths to reflect the AS boundary crossing.
1376 table as1; # Define the tables
1379 protocol kernel kern1 { # Synchronize them with the kernel
1384 protocol kernel kern2 {
1389 protocol bgp bgp1 { # The outside connections
1392 neighbor 192.168.0.1 as 1001;
1400 neighbor 10.0.0.1 as 1002;
1405 protocol pipe { # The Pipe
1409 if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks
1410 if preference>10 then preference = preference-10;
1411 if source=RTS_BGP then bgp_path.prepend(1);
1417 if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks
1418 if preference>10 then preference = preference-10;
1419 if source=RTS_BGP then bgp_path.prepend(2);
1431 <p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts (to all its neighbors)
1432 distances to all networks it can reach. When a router hears distance to another network, it increments
1433 it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes
1434 unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually, plus
1435 interface metric, which is usually one). After some time, the distance reaches infinity (that's 15 in
1436 RIP) and all routers know that network is unreachable. RIP tries to minimize situations where
1437 counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't use
1438 RIP on networks where maximal distance is higher than 15 hosts. You can read more about RIP at <HTMLURL
1439 URL="http://www.ietf.org/html.charters/rip-charter.html" name="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4
1440 (RFC 1723<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1723.txt">)
1441 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
1442 not currently supported. RIPv4 MD5 authentication (RFC 2082<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2082.txt">) is supported.
1444 <p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow
1445 convergence, big network load and inability to handle larger networks
1446 makes it pretty much obsolete in IPv4 world. (It is still usable on
1447 very small networks.) It is widely used in IPv6 networks,
1448 because there are no good implementations of OSPFv3.
1450 <sect1>Configuration
1452 <p>In addition to options common for all to other protocols, RIP supports the following ones:
1455 <tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
1456 packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
1457 into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
1458 hash. If you set authentication to not-none, it is a good idea to add <cf>passwords { }</cf>
1459 section. Default: none.
1461 <tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
1462 be honored. (Always, when sent from a host on a directly connected
1463 network or never.) Routing table updates are honored only from
1464 neighbors, that is not configurable. Default: never.
1467 <p>There are two options that can be specified per-interface. First is <cf>metric</cf>, with
1468 default one. Second is <cf>mode multicast|broadcast|quiet|nolisten|version1</cf>, it selects mode for
1469 rip to work in. If nothing is specified, rip runs in multicast mode. <cf>version1</cf> is
1470 currently equivalent to <cf>broadcast</cf>, and it makes RIP talk to a broadcast address even
1471 through multicast mode is possible. <cf>quiet</cf> option means that RIP will not transmit
1472 any periodic messages to this interface and <cf>nolisten</cf> means that RIP will send to this
1473 interface but not listen to it.
1475 <p>The following options generally override behavior specified in RFC. If you use any of these
1476 options, BIRD will no longer be RFC-compliant, which means it will not be able to talk to anything
1477 other than equally configured BIRD. I have warned you.
1480 <tag>port <M>number</M></tag>
1481 selects IP port to operate on, default 520. (This is useful when testing BIRD, if you
1482 set this to an address >1024, you will not need to run bird with UID==0).
1484 <tag>infinity <M>number</M></tag>
1485 selects the value of infinity, default is 16. Bigger values will make protocol convergence
1488 <tag>period <M>number</M>
1489 </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
1490 number will mean faster convergence but bigger network
1491 load. Do not use values lower than 10.
1493 <tag>timeout time <M>number</M>
1494 </tag>specifies how old route has to be to be considered unreachable. Default is 4*<cf/period/.
1496 <tag>garbage time <M>number</M>
1497 </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
1502 <p>RIP defines two route attributes:
1505 <tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
1506 When routes from different RIP instances are available and all of them have the same
1507 preference, BIRD prefers the route with lowest <cf/rip_metric/.
1508 When importing a non-RIP route, the metric defaults to 5.
1510 <tag>int <cf/rip_tag/</tag> RIP route tag: a 16-bit number which can be used
1511 to carry additional information with the route (for example, an originating AS number
1512 in case of external routes). When importing a non-RIP route, the tag defaults to 0.
1518 protocol rip MyRIP_test {
1523 interface "eth0" { metric 3; mode multicast; }
1524 "eth1" { metric 2; mode broadcast; };
1526 authentication none;
1527 import filter { print "importing"; accept; };
1528 export filter { print "exporting"; accept; };
1534 <p>The Static protocol doesn't communicate with other routers in the network,
1535 but instead it allows you to define routes manually. This is often used for
1536 specifying how to forward packets to parts of the network which don't use
1537 dynamic routing at all and also for defining sink routes (i.e., those
1538 telling to return packets as undeliverable if they are in your IP block,
1539 you don't have any specific destination for them and you don't want to send
1540 them out through the default route to prevent routing loops).
1542 <p>There are three types of static routes: `classical' routes telling to
1543 forward packets to a neighboring router, device routes specifying forwarding
1544 to hosts on a directly connected network and special routes (sink, blackhole
1545 etc.) which specify a special action to be done instead of forwarding the
1548 <p>When the particular destination is not available (the interface is down or
1549 the next hop of the route is not a neighbor at the moment), Static just
1550 uninstalls the route from the table it is connected to and adds it again as soon
1551 as the destination becomes adjacent again.
1553 <p>The Static protocol has no configuration options. Instead, the
1554 definition of the protocol contains a list of static routes:
1557 <tag>route <m/prefix/ via <m/ip/</tag> Static route through
1558 a neighboring router.
1559 <tag>route <m/prefix/ via <m/"interface"/</tag> Static device
1560 route through an interface to hosts on a directly connected network.
1561 <tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
1562 specifying to drop the packet, return it as unreachable or return
1563 it as administratively prohibited.
1566 <p>Static routes have no specific attributes.
1568 <p>Example static config might look like this:
1572 table testable; # Connect to a non-default routing table
1573 route 0.0.0.0/0 via 62.168.0.13; # Default route
1574 route 62.168.0.0/25 reject; # Sink route
1575 route 10.2.0.0/24 via "arc0"; # Secondary network
1583 <p>Although BIRD supports all the commonly used routing protocols,
1584 there are still some features which would surely deserve to be
1585 implemented in future versions of BIRD:
1588 <item>OSPF for IPv6 networks
1589 <item>OSPF NSSA areas and opaque LSA's
1590 <item>Route aggregation and flap dampening
1591 <item>Generation of IPv6 router advertisements
1592 <item>Multipath routes
1593 <item>Multicast routing protocols
1594 <item>Ports to other systems
1597 <sect>Getting more help
1599 <p>If you use BIRD, you're welcome to join the bird-users mailing list
1600 (<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
1601 where you can share your experiences with the other users and consult
1602 your problems with the authors. To subscribe to the list, just send a
1603 <tt/subscribe bird-users/ command in a body of a mail to
1604 (<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
1605 The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
1607 <p>BIRD is a relatively young system and it probably contains some
1608 bugs. You can report any problems to the bird-users list and the authors
1609 will be glad to solve them, but before you do so,
1610 please make sure you have read the available documentation and that you are running the latest version (available at <HTMLURL
1611 URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). (Of course, a patch
1612 which fixes the bug is always welcome as an attachment.)
1614 <p>If you want to understand what is going inside, Internet standards are
1615 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">).
1622 LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
1623 LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps
1624 LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC
1625 LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth
1626 LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek
1627 LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC
1628 LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU
1629 LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc
1630 LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats
1631 LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt
1632 LocalWords: proto wildcard