1 <!doctype birddoc system>
6 This documentation can have 4 forms: sgml (this is master copy), html, ASCII
7 text and dvi/postscript (generated from sgml using sgmltools). You should always
10 This is a slightly modified linuxdoc dtd. Anything in <descrip> tags is
11 considered definition of configuration primitives, <cf> is fragment of
12 configuration within normal text, <m> is "meta" information within fragment of
13 configuration - something in config which is not keyword.
17 Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
23 <title>BIRD User's Guide
25 Ondrej Filip <it/<feela@network.cz>/,
26 Pavel Machek <it/<pavel@ucw.cz>/,
27 Martin Mares <it/<mj@ucw.cz>/,
28 Ondrej Zajicek <it/<santiago@crfreenet.org>/
32 This document contains user documentation for the BIRD Internet Routing Daemon project.
35 <!-- Table of contents -->
38 <!-- Begin the document -->
46 The name `BIRD' is actually an acronym standing for `BIRD Internet Routing
47 Daemon'. Let's take a closer look at the meaning of the name:
49 <p><em/BIRD/: Well, we think we have already explained that. It's an acronym
50 standing for `BIRD Internet Routing Daemon', you remember, don't you? :-)
52 <p><em/Internet Routing/: It's a program (well, a daemon, as you are going to
53 discover in a moment) which works as a dynamic router in an Internet type
54 network (that is, in a network running either the IPv4 or the IPv6 protocol).
55 Routers are devices which forward packets between interconnected networks in
56 order to allow hosts not connected directly to the same local area network to
57 communicate with each other. They also communicate with the other routers in the
58 Internet to discover the topology of the network which allows them to find
59 optimal (in terms of some metric) rules for forwarding of packets (which are
60 called routing tables) and to adapt themselves to the changing conditions such
61 as outages of network links, building of new connections and so on. Most of
62 these routers are costly dedicated devices running obscure firmware which is
63 hard to configure and not open to any changes (on the other hand, their special
64 hardware design allows them to keep up with lots of high-speed network
65 interfaces, better than general-purpose computer does). Fortunately, most
66 operating systems of the UNIX family allow an ordinary computer to act as a
67 router and forward packets belonging to the other hosts, but only according to a
68 statically configured table.
70 <p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program
71 running on background which does the dynamic part of Internet routing, that is
72 it communicates with the other routers, calculates routing tables and sends them
73 to the OS kernel which does the actual packet forwarding. There already exist
74 other such routing daemons: routed (RIP only), GateD (non-free),
75 Zebra <HTMLURL URL="http://www.zebra.org"> and
76 MRTD <HTMLURL URL="http://sourceforge.net/projects/mrt">,
77 but their capabilities are limited and they are relatively hard to configure
80 <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
81 to support all the routing technology used in the today's Internet or planned to
82 be used in near future and to have a clean extensible architecture allowing new
83 routing protocols to be incorporated easily. Among other features, BIRD
87 <item>both IPv4 and IPv6 protocols
88 <item>multiple routing tables
89 <item>the Border Gateway Protocol (BGPv4)
90 <item>the Routing Information Protocol (RIPv2)
91 <item>the Open Shortest Path First protocol (OSPFv2, OSPFv3)
92 <item>the Router Advertisements for IPv6 hosts
93 <item>a virtual protocol for exchange of routes between different
94 routing tables on a single host
95 <item>a command-line interface allowing on-line control and inspection
96 of status of the daemon
97 <item>soft reconfiguration (no need to use complex online commands to
98 change the configuration, just edit the configuration file and
99 notify BIRD to re-read it and it will smoothly switch itself to
100 the new configuration, not disturbing routing protocols unless
101 they are affected by the configuration changes)
102 <item>a powerful language for route filtering
105 <p>BIRD has been developed at the Faculty of Math and Physics, Charles
106 University, Prague, Czech Republic as a student project. It can be freely
107 distributed under the terms of the GNU General Public License.
109 <p>BIRD has been designed to work on all UNIX-like systems. It has been
110 developed and tested under Linux 2.0 to 2.6, and then ported to FreeBSD, NetBSD
111 and OpenBSD, porting to other systems (even non-UNIX ones) should be relatively
112 easy due to its highly modular architecture.
114 <p>BIRD supports either IPv4 or IPv6 protocol, but have to be compiled separately
115 for each one. Therefore, a dualstack router would run two instances of BIRD (one
116 for IPv4 and one for IPv6), with completely separate setups (configuration
120 <sect>Installing BIRD
122 <p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make)
123 and Perl, installing BIRD should be as easy as:
129 vi /usr/local/etc/bird.conf
133 <p>You can use <tt>./configure --help</tt> to get a list of configure
134 options. The most important ones are: <tt/--enable-ipv6/ which enables building
135 of an IPv6 version of BIRD, <tt/--with-protocols=/ to produce a slightly smaller
136 BIRD executable by configuring out routing protocols you don't use, and
137 <tt/--prefix=/ to install BIRD to a place different from <file>/usr/local</file>.
142 <p>You can pass several command-line options to bird:
145 <tag>-c <m/config name/</tag>
146 use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
149 enable debug messages and run bird in foreground.
151 <tag>-D <m/filename of debug log/</tag>
152 log debugging information to given file instead of stderr.
155 just parse the config file and exit. Return value is zero if the config
156 file is valid, nonzero if there are some errors.
158 <tag>-s <m/name of communication socket/</tag>
159 use given filename for a socket for communications with the client,
160 default is <it/prefix/<file>/var/run/bird.ctl</file>.
162 <tag>-P <m/name of PID file/</tag>
163 create a PID file with given filename.
165 <tag>-u <m/user/</tag>
166 drop privileges and use that user ID, see the next section for details.
168 <tag>-g <m/group/</tag>
169 use that group ID, see the next section for details.
172 run bird in foreground.
175 apply graceful restart recovery after start.
178 <p>BIRD writes messages about its work to log files or syslog (according to config).
183 <p>BIRD, as a routing daemon, uses several privileged operations (like setting
184 routing table and using raw sockets). Traditionally, BIRD is executed and runs
185 with root privileges, which may be prone to security problems. The recommended
186 way is to use a privilege restriction (options <cf/-u/, <cf/-g/). In that case
187 BIRD is executed with root privileges, but it changes its user and group ID to
188 an unprivileged ones, while using Linux capabilities to retain just required
189 privileges (capabilities CAP_NET_*). Note that the control socket is created
190 before the privileges are dropped, but the config file is read after that. The
191 privilege restriction is not implemented in BSD port of BIRD.
193 <p>A nonprivileged user (as an argument to <cf/-u/ options) may be the user
194 <cf/nobody/, but it is suggested to use a new dedicated user account (like
195 <cf/bird/). The similar considerations apply for the group option, but there is
196 one more condition -- the users in the same group can use <file/birdc/ to
199 <p>Finally, there is a possibility to use external tools to run BIRD in an
200 environment with restricted privileges. This may need some configuration, but it
201 is generally easy -- BIRD needs just the standard library, privileges to read
202 the config file and create the control socket and the CAP_NET_* capabilities.
205 <chapt>About routing tables
207 <p>BIRD has one or more routing tables which may or may not be synchronized with
208 OS kernel and which may or may not be synchronized with each other (see the Pipe
209 protocol). Each routing table contains a list of known routes. Each route
213 <item>network prefix this route is for (network address and prefix
214 length -- the number of bits forming the network part of the
215 address; also known as a netmask)
216 <item>preference of this route
217 <item>IP address of router which told us about this route
218 <item>IP address of router we should forward the packets to using this
220 <item>other attributes common to all routes
221 <item>dynamic attributes defined by protocols which may or may not be
222 present (typically protocol metrics)
225 Routing table maintains multiple entries for a network, but at most one entry
226 for one network and one protocol. The entry with the highest preference is used
227 for routing (we will call such an entry the <it/selected route/). If there are
228 more entries with the same preference and they are from the same protocol, the
229 protocol decides (typically according to metrics). If they aren't, an internal
230 ordering is used to break the tie. You can get the list of route attributes in
231 the Route attributes section.
233 <p>Each protocol is connected to a routing table through two filters which can
234 accept, reject and modify the routes. An <it/export/ filter checks routes passed
235 from the routing table to the protocol, an <it/import/ filter checks routes in
236 the opposite direction. When the routing table gets a route from a protocol, it
237 recalculates the selected route and broadcasts it to all protocols connected to
238 the table. The protocols typically send the update to other routers in the
239 network. Note that although most protocols are interested in receiving just
240 selected routes, some protocols (e.g. the <cf/Pipe/ protocol) receive and
241 process all entries in routing tables (accepted by filters).
243 <p><label id="dsc-sorted">Usually, a routing table just chooses a selected route
244 from a list of entries for one network. But if the <cf/sorted/ option is
245 activated, these lists of entries are kept completely sorted (according to
246 preference or some protocol-dependent metric). This is needed for some features
247 of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to
248 accept not just a selected route, but the first route (in the sorted list) that
249 is accepted by filters), but it is incompatible with some other features (e.g.
250 <cf/deterministic med/ option of BGP protocol, which activates a way of choosing
251 selected route that cannot be described using comparison and ordering). Minor
252 advantage is that routes are shown sorted in <cf/show route/, minor disadvantage
253 is that it is slightly more computationally expensive.
256 <sect>Graceful restart
258 <p>When BIRD is started after restart or crash, it repopulates routing tables in
259 an uncoordinated manner, like after clean start. This may be impractical in some
260 cases, because if the forwarding plane (i.e. kernel routing tables) remains
261 intact, then its synchronization with BIRD would temporarily disrupt packet
262 forwarding until protocols converge. Graceful restart is a mechanism that could
263 help with this issue. Generally, it works by starting protocols and letting them
264 repopulate routing tables while deferring route propagation until protocols
265 acknowledge their convergence. Note that graceful restart behavior have to be
266 configured for all relevant protocols and requires protocol-specific support
267 (currently implemented for Kernel and BGP protocols), it is activated for
268 particular boot by option <cf/-R/.
275 <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads
276 <it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option
277 is given). Configuration may be changed at user's request: if you modify the
278 config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new
279 config. Then there's the client which allows you to talk with BIRD in an
282 <p>In the config, everything on a line after <cf/#/ or inside <cf>/* */</cf> is
283 a comment, whitespace characters are treated as a single space. If there's a
284 variable number of options, they are grouped using the <cf/{ }/ brackets. Each
285 option is terminated by a <cf/;/. Configuration is case sensitive. There are two
286 ways how to name symbols (like protocol names, filter names, constats etc.). You
287 can either use a simple string starting with a letter followed by any
288 combination of letters and numbers (e.g. "R123", "myfilter", "bgp5") or you can
289 enclose the name into apostrophes (<cf/'/) and than you can use any combination
290 of numbers, letters. hyphens, dots and colons (e.g. "'1:strange-name'",
291 "'-NAME-'", "'cool::name'").
293 <p>Here is an example of a simple config file. It enables synchronization of
294 routing tables with OS kernel, scans for new network interfaces every 10 seconds
295 and runs RIP on all network interfaces found.
299 persist; # Don't remove routes on BIRD shutdown
300 scan time 20; # Scan kernel routing table every 20 seconds
301 export all; # Default is export none
305 scan time 10; # Scan interfaces every 10 seconds
319 <tag>include "<m/filename/"</tag>
320 This statement causes inclusion of a new file. <m/Filename/ could also
321 be a wildcard. The maximal depth is 5. Note that this statement could be
322 used anywhere in the config file, not just as a top-level option.
324 <tag><label id="dsc-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag>
325 Set logging of messages having the given class (either <cf/all/ or
326 <cf/{ error, trace }/ etc.) into selected destination (a file specified
327 as a filename string, syslog with optional name argument, or the stderr
328 output). Classes are:
329 <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
330 <cf/debug/ for debugging messages,
331 <cf/trace/ when you want to know what happens in the network,
332 <cf/remote/ for messages about misbehavior of remote machines,
333 <cf/auth/ about authentication failures,
334 <cf/bug/ for internal BIRD bugs.
335 You may specify more than one <cf/log/ line to establish logging to
336 multiple destinations. Default: log everything to the system log.
338 <tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
339 Set global defaults of protocol debugging options. See <cf/debug/ in the
340 following section. Default: off.
342 <tag>debug commands <m/number/</tag>
343 Control logging of client connections (0 for no logging, 1 for logging
344 of connects and disconnects, 2 and higher for logging of all client
345 commands). Default: 0.
347 <tag>mrtdump "<m/filename/"</tag>
348 Set MRTdump file name. This option must be specified to allow MRTdump
349 feature. Default: no dump file.
351 <tag>mrtdump protocols all|off|{ states, messages }</tag>
352 Set global defaults of MRTdump options. See <cf/mrtdump/ in the
353 following section. Default: off.
355 <tag>filter <m/name local variables/{ <m/commands/ }</tag>
356 Define a filter. You can learn more about filters in the following
359 <tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag>
360 Define a function. You can learn more about functions in the following chapter.
362 <tag>protocol rip|ospf|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
363 Define a protocol instance called <cf><m/name/</cf> (or with a name like
364 "rip5" generated automatically if you don't specify any
365 <cf><m/name/</cf>). You can learn more about configuring protocols in
366 their own chapters. When <cf>from <m/name2/</cf> expression is used,
367 initial protocol options are taken from protocol or template
368 <cf><m/name2/</cf> You can run more than one instance of most protocols
369 (like RIP or BGP). By default, no instances are configured.
371 <tag>template rip|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
372 Define a protocol template instance called <m/name/ (or with a name like
373 "bgp1" generated automatically if you don't specify any <m/name/).
374 Protocol templates can be used to group common options when many
375 similarly configured protocol instances are to be defined. Protocol
376 instances (and other templates) can use templates by using <cf/from/
377 expression and the name of the template. At the moment templates (and
378 <cf/from/ expression) are not implemented for OSPF protocol.
380 <tag>define <m/constant/ = <m/expression/</tag>
381 Define a constant. You can use it later in every place you could use a
382 value of the same type. Besides, there are some predefined numeric
383 constants based on /etc/iproute2/rt_* files. A list of defined constants
384 can be seen (together with other symbols) using 'show symbols' command.
386 <tag>router id <m/IPv4 address/</tag>
387 Set BIRD's router ID. It's a world-wide unique identification of your
388 router, usually one of router's IPv4 addresses. Default: in IPv4
389 version, the lowest IP address of a non-loopback interface. In IPv6
390 version, this option is mandatory.
392 <tag>router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...]</tag>
393 Set BIRD's router ID based on an IP address of an interface specified by
394 an interface pattern. The option is applicable for IPv4 version only.
395 See <ref id="dsc-iface" name="interface"> section for detailed
396 description of interface patterns with extended clauses.
398 <tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
399 This option allows to specify address and port where BGP protocol should
400 listen. It is global option as listening socket is common to all BGP
401 instances. Default is to listen on all addresses (0.0.0.0) and port 179.
402 In IPv6 mode, option <cf/dual/ can be used to specify that BGP socket
403 should accept both IPv4 and IPv6 connections (but even in that case,
404 BIRD would accept IPv6 routes only). Such behavior was default in older
407 <tag>graceful restart wait <m/number/</tag>
408 During graceful restart recovery, BIRD waits for convergence of routing
409 protocols. This option allows to specify a timeout for the recovery to
410 prevent waiting indefinitely if some protocols cannot converge. Default:
413 <tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
414 This option allows to specify a format of date/time used by BIRD. The
415 first argument specifies for which purpose such format is used.
416 <cf/route/ is a format used in 'show route' command output,
417 <cf/protocol/ is used in 'show protocols' command output, <cf/base/ is
418 used for other commands and <cf/log/ is used in a log file.
420 "<m/format1/" is a format string using <it/strftime(3)/ notation (see
421 <it/man strftime/ for details). <m/limit> and "<m/format2/" allow to
422 specify the second format string for times in past deeper than <m/limit/
423 seconds. There are few shorthands: <cf/iso long/ is a ISO 8601 date/time
424 format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F %T"/.
425 <cf/iso short/ is a variant of ISO 8601 that uses just the time format
426 (hh:mm:ss) for near times (up to 20 hours in the past) and the date
427 format (YYYY-MM-DD) for far times. This is a shorthand for
428 <cf/"%T" 72000 "%F"/.
430 By default, BIRD uses the <cf/iso short/ format for <cf/route/ and
431 <cf/protocol/ times, and the <cf/iso long/ format for <cf/base/ and
434 In pre-1.4.0 versions, BIRD used an short, ad-hoc format for <cf/route/
435 and <cf/protocol/ times, and a <cf/iso long/ similar format (DD-MM-YYYY
436 hh:mm:ss) for <cf/base/ and <cf/log/. These timeformats could be set by
437 <cf/old short/ and <cf/old long/ compatibility shorthands.
439 <tag>table <m/name/ [sorted]</tag>
440 Create a new routing table. The default routing table is created
441 implicitly, other routing tables have to be added by this command.
442 Option <cf/sorted/ can be used to enable sorting of routes, see
443 <ref id="dsc-sorted" name="sorted table"> description for details.
445 <tag>roa table <m/name/ [ { roa table options ... } ]</tag>
446 Create a new ROA (Route Origin Authorization) table. ROA tables can be
447 used to validate route origination of BGP routes. A ROA table contains
448 ROA entries, each consist of a network prefix, a max prefix length and
449 an AS number. A ROA entry specifies prefixes which could be originated
450 by that AS number. ROA tables could be filled with data from RPKI (RFC
451 6480) or from public databases like Whois. ROA tables are examined by
452 <cf/roa_check()/ operator in filters.
454 Currently, there is just one option, <cf>roa <m/prefix/ max <m/num/ as
455 <m/num/</cf>, which can be used to populate the ROA table with static
456 ROA entries. The option may be used multiple times. Other entries can be
457 added dynamically by <cf/add roa/ command.
459 <tag>eval <m/expr/</tag>
460 Evaluates given filter expression. It is used by us for testing of filters.
464 <sect>Protocol options
466 <p>For each protocol instance, you can configure a bunch of options. Some of
467 them (those described in this section) are generic, some are specific to the
468 protocol (see sections talking about the protocols).
470 <p>Several options use a <m/switch/ argument. It can be either <cf/on/,
471 <cf/yes/ or a numeric expression with a non-zero value for the option to be
472 enabled or <cf/off/, <cf/no/ or a numeric expression evaluating to zero to
473 disable it. An empty <m/switch/ is equivalent to <cf/on/ ("silence means
477 <tag>preference <m/expr/</tag>
478 Sets the preference of routes generated by this protocol. Default:
481 <tag>disabled <m/switch/</tag>
482 Disables the protocol. You can change the disable/enable status from the
483 command line interface without needing to touch the configuration.
484 Disabled protocols are not activated. Default: protocol is enabled.
486 <tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
487 Set protocol debugging options. If asked, each protocol is capable of
488 writing trace messages about its work to the log (with category
489 <cf/trace/). You can either request printing of <cf/all/ trace messages
490 or only of the types selected: <cf/states/ for protocol state changes
491 (protocol going up, down, starting, stopping etc.), <cf/routes/ for
492 routes exchanged with the routing table, <cf/filters/ for details on
493 route filtering, <cf/interfaces/ for interface change events sent to the
494 protocol, <cf/events/ for events internal to the protocol and <cf/packets/
495 for packets sent and received by the protocol. Default: off.
497 <tag>mrtdump all|off|{ states, messages }</tag>
498 Set protocol MRTdump flags. MRTdump is a standard binary format for
499 logging information from routing protocols and daemons. These flags
500 control what kind of information is logged from the protocol to the
501 MRTdump file (which must be specified by global <cf/mrtdump/ option, see
502 the previous section). Although these flags are similar to flags of
503 <cf/debug/ option, their meaning is different and protocol-specific. For
504 BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs
505 received BGP messages. Other protocols does not support MRTdump yet.
507 <tag>router id <m/IPv4 address/</tag>
508 This option can be used to override global router id for a given
509 protocol. Default: uses global router id.
511 <tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag>
512 Specify a filter to be used for filtering routes coming from the
513 protocol to the routing table. <cf/all/ is shorthand for <cf/where true/
514 and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/.
516 <tag>export <m/filter/</tag>
517 This is similar to the <cf>import</cf> keyword, except that it works in
518 the direction from the routing table to the protocol. Default: <cf/none/.
520 <tag>import keep filtered <m/switch/</tag>
521 Usually, if an import filter rejects a route, the route is forgotten.
522 When this option is active, these routes are kept in the routing table,
523 but they are hidden and not propagated to other protocols. But it is
524 possible to show them using <cf/show route filtered/. Note that this
525 option does not work for the pipe protocol. Default: off.
527 <tag><label id="import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
528 Specify an import route limit (a maximum number of routes imported from
529 the protocol) and optionally the action to be taken when the limit is
530 hit. Warn action just prints warning log message. Block action discards
531 new routes coming from the protocol. Restart and disable actions shut
532 the protocol down like appropriate commands. Disable is the default
533 action if an action is not explicitly specified. Note that limits are
534 reset during protocol reconfigure, reload or restart. Default: <cf/off/.
536 <tag>receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
537 Specify an receive route limit (a maximum number of routes received from
538 the protocol and remembered). It works almost identically to <cf>import
539 limit</cf> option, the only difference is that if <cf/import keep
540 filtered/ option is active, filtered routes are counted towards the
541 limit and blocked routes are forgotten, as the main purpose of the
542 receive limit is to protect routing tables from overflow. Import limit,
543 on the contrary, counts accepted routes only and routes blocked by the
544 limit are handled like filtered routes. Default: <cf/off/.
546 <tag>export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
547 Specify an export route limit, works similarly to the <cf>import
548 limit</cf> option, but for the routes exported to the protocol. This
549 option is experimental, there are some problems in details of its
550 behavior -- the number of exported routes can temporarily exceed the
551 limit without triggering it during protocol reload, exported routes
552 counter ignores route blocking and block action also blocks route
553 updates of already accepted routes -- and these details will probably
554 change in the future. Default: <cf/off/.
556 <tag>description "<m/text/"</tag>
557 This is an optional description of the protocol. It is displayed as a
558 part of the output of 'show route all' command.
560 <tag>table <m/name/</tag>
561 Connect this protocol to a non-default routing table.
564 <p>There are several options that give sense only with certain protocols:
567 <tag><label id="dsc-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...] [ { <m/option/ ; [...] } ]</tag>
568 Specifies a set of interfaces on which the protocol is activated with
569 given interface-specific options. A set of interfaces specified by one
570 interface option is described using an interface pattern. The interface
571 pattern consists of a sequence of clauses (separated by commas), each
572 clause is a mask specified as a shell-like pattern. Interfaces are
573 matched by their name.
575 An interface matches the pattern if it matches any of its clauses. If
576 the clause begins with <cf/-/, matching interfaces are excluded. Patterns
577 are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/
578 means eth0 and all non-ethernets.
580 Some protocols (namely OSPFv2 and Direct) support extended clauses that
581 may contain a mask, a prefix, or both of them. An interface matches such
582 clause if its name matches the mask (if specified) and its address
583 matches the prefix (if specified). Extended clauses are used when the
584 protocol handles multiple addresses on an interface independently.
586 An interface option can be used more times with different interface-specific
587 options, in that case for given interface the first matching interface
590 This option is allowed in BFD, Direct, OSPF, RAdv and RIP protocols, but
591 in OSPF protocol it is used in the <cf/area/ subsection.
597 <cf>interface "*" { type broadcast; };</cf> - start the protocol on all
598 interfaces with <cf>type broadcast</cf> option.
600 <cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the
601 protocol on enumerated interfaces with <cf>type ptp</cf> option.
603 <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
604 on all interfaces that have address from 192.168.0.0/16, but not from
607 <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
608 on all interfaces that have address from 192.168.0.0/16, but not from
611 <cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all
612 ethernet interfaces that have address from 192.168.1.0/24.
614 <tag><label id="dsc-prio">tx class|dscp <m/num/</tag>
615 This option specifies the value of ToS/DS/Class field in IP headers of
616 the outgoing protocol packets. This may affect how the protocol packets
617 are processed by the network relative to the other network traffic. With
618 <cf/class/ keyword, the value (0-255) is used for the whole ToS/Class
619 octet (but two bits reserved for ECN are ignored). With <cf/dscp/
620 keyword, the value (0-63) is used just for the DS field in the octet.
621 Default value is 0xc0 (DSCP 0x30 - CS6).
623 <tag>tx priority <m/num/</tag>
624 This option specifies the local packet priority. This may affect how the
625 protocol packets are processed in the local TX queues. This option is
626 Linux specific. Default value is 7 (highest priority, privileged traffic).
628 <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>
629 Specifies a password that can be used by the protocol. Password option
630 can be used more times to specify more passwords. If more passwords are
631 specified, it is a protocol-dependent decision which one is really
632 used. Specifying passwords does not mean that authentication is enabled,
633 authentication can be enabled by separate, protocol-dependent
634 <cf/authentication/ option.
636 This option is allowed in OSPF and RIP protocols. BGP has also
637 <cf/password/ option, but it is slightly different and described
643 <p>Password option can contain section with some (not necessary all) password sub-options:
646 <tag>id <M>num</M></tag>
647 ID of the password, (0-255). If it's not used, BIRD will choose ID based
648 on an order of the password item in the interface. For example, second
649 password item in one interface will have default ID 2. ID is used by
650 some routing protocols to identify which password was used to
651 authenticate protocol packets.
653 <tag>generate from "<m/time/"</tag>
654 The start time of the usage of the password for packet signing.
655 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
657 <tag>generate to "<m/time/"</tag>
658 The last time of the usage of the password for packet signing.
660 <tag>accept from "<m/time/"</tag>
661 The start time of the usage of the password for packet verification.
663 <tag>accept to "<m/time/"</tag>
664 The last time of the usage of the password for packet verification.
667 <chapt>Remote control
669 <p>You can use the command-line client <file>birdc</file> to talk with a running
670 BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless
671 changed with the <tt/-s/ option given to both the server and the client). The
672 commands can perform simple actions such as enabling/disabling of protocols,
673 telling BIRD to show various information, telling it to show routing table
674 filtered by filter, or asking BIRD to reconfigure. Press <tt/?/ at any time to
675 get online help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
676 client, which allows just read-only commands (<cf/show .../). Option <tt/-v/ can
677 be passed to the client, to make it dump numeric return codes along with the
678 messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your
679 own applications could do that, too -- the format of communication between BIRD
680 and <file/birdc/ is stable (see the programmer's documentation).
682 <p>There is also lightweight variant of BIRD client called <file/birdcl/, which
683 does not support command line editing and history and has minimal dependencies.
684 This is useful for running BIRD in resource constrained environments, where
685 Readline library (required for regular BIRD client) is not available.
687 <p>Many commands have the <m/name/ of the protocol instance as an argument.
688 This argument can be omitted if there exists only a single instance.
690 <p>Here is a brief list of supported functions:
693 <tag>show status</tag>
694 Show router status, that is BIRD version, uptime and time from last
697 <tag>show protocols [all]</tag>
698 Show list of protocol instances along with tables they are connected to
699 and protocol status, possibly giving verbose information, if <cf/all/ is
702 <tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
703 Show detailed information about OSPF interfaces.
705 <tag>show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
706 Show a list of OSPF neighbors and a state of adjacency to them.
708 <tag>show ospf state [all] [<m/name/]</tag>
709 Show detailed information about OSPF areas based on a content of the
710 link-state database. It shows network topology, stub networks,
711 aggregated networks and routers from other areas and external routes.
712 The command shows information about reachable network nodes, use option
713 <cf/all/ to show information about all network nodes in the link-state
716 <tag>show ospf topology [all] [<m/name/]</tag>
717 Show a topology of OSPF areas based on a content of the link-state
718 database. It is just a stripped-down version of 'show ospf state'.
720 <tag>show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag>
721 Show contents of an OSPF LSA database. Options could be used to filter
724 <tag>show static [<m/name/]</tag>
725 Show detailed information about static routes.
727 <tag>show bfd sessions [<m/name/]</tag>
728 Show information about BFD sessions.
730 <tag>show interfaces [summary]</tag>
731 Show the list of interfaces. For each interface, print its type, state,
732 MTU and addresses assigned.
734 <tag>show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
735 Show the list of symbols defined in the configuration (names of
736 protocols, routing tables etc.).
738 <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>
739 Show contents of a routing table (by default of the main one or the
740 table attached to a respective protocol), that is routes, their metrics
741 and (in case the <cf/all/ switch is given) all their attributes.
743 <p>You can specify a <m/prefix/ if you want to print routes for a
744 specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get
745 the entry which will be used for forwarding of packets to the given
746 destination. By default, all routes for each network are printed with
747 the selected one at the top, unless <cf/primary/ is given in which case
748 only the selected route is shown.
750 <p>You can also ask for printing only routes processed and accepted by
751 a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
752 </cf> or matching a given condition (<cf>where <m/condition/</cf>).
753 The <cf/export/ and <cf/preexport/ switches ask for printing of entries
754 that are exported to the specified protocol. With <cf/preexport/, the
755 export filter of the protocol is skipped.
757 <p>You can also select just routes added by a specific protocol.
758 <cf>protocol <m/p/</cf>.
760 <p>If BIRD is configured to keep filtered routes (see <cf/import keep
761 filtered/ option), you can show them instead of routes by using
762 <cf/filtered/ switch.
764 <p>The <cf/stats/ switch requests showing of route statistics (the
765 number of networks, number of routes before and after filtering). If
766 you use <cf/count/ instead, only the statistics will be printed.
768 <tag>show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag>
769 Show contents of a ROA table (by default of the first one). You can
770 specify a <m/prefix/ to print ROA entries for a specific network. If you
771 use <cf>for <m/prefix/</cf>, you'll get all entries relevant for route
772 validation of the network prefix; i.e., ROA entries whose prefixes cover
773 the network prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA
774 entries covered by the network prefix. You could also use <cf/as/ option
775 to show just entries for given AS.
777 <tag>add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
778 Add a new ROA entry to a ROA table. Such entry is called <it/dynamic/
779 compared to <it/static/ entries specified in the config file. These
780 dynamic entries survive reconfiguration.
782 <tag>delete roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
783 Delete the specified ROA entry from a ROA table. Only dynamic ROA
784 entries (i.e., the ones added by <cf/add roa/ command) can be deleted.
786 <tag>flush roa [table <m/t/>]</tag>
787 Remove all dynamic ROA entries from a ROA table.
789 <tag>configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
790 Reload configuration from a given file. BIRD will smoothly switch itself
791 to the new configuration, protocols are reconfigured if possible,
792 restarted otherwise. Changes in filters usually lead to restart of
795 If <cf/soft/ option is used, changes in filters does not cause BIRD to
796 restart affected protocols, therefore already accepted routes (according
797 to old filters) would be still propagated, but new routes would be
798 processed according to the new filters.
800 If <cf/timeout/ option is used, config timer is activated. The new
801 configuration could be either confirmed using <cf/configure confirm/
802 command, or it will be reverted to the old one when the config timer
803 expires. This is useful for cases when reconfiguration breaks current
804 routing and a router becames inaccessible for an administrator. The
805 config timeout expiration is equivalent to <cf/configure undo/
806 command. The timeout duration could be specified, default is 300 s.
808 <tag>configure confirm</tag>
809 Deactivate the config undo timer and therefore confirm the current
812 <tag>configure undo</tag>
813 Undo the last configuration change and smoothly switch back to the
814 previous (stored) configuration. If the last configuration change was
815 soft, the undo change is also soft. There is only one level of undo, but
816 in some specific cases when several reconfiguration requests are given
817 immediately in a row and the intermediate ones are skipped then the undo
818 also skips them back.
820 <tag>configure check ["<m/config file/"]</tag>
821 Read and parse given config file, but do not use it. useful for checking
822 syntactic and some semantic validity of an config file.
824 <tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
825 Enable, disable or restart a given protocol instance, instances matching
826 the <cf><m/pattern/</cf> or <cf/all/ instances.
828 <tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
829 Reload a given protocol instance, that means re-import routes from the
830 protocol instance and re-export preferred routes to the instance. If
831 <cf/in/ or <cf/out/ options are used, the command is restricted to one
832 direction (re-import or re-export).
834 This command is useful if appropriate filters have changed but the
835 protocol instance was not restarted (or reloaded), therefore it still
836 propagates the old set of routes. For example when <cf/configure soft/
837 command was used to change filters.
839 Re-export always succeeds, but re-import is protocol-dependent and might
840 fail (for example, if BGP neighbor does not support route-refresh
841 extension). In that case, re-export is also skipped. Note that for the
842 pipe protocol, both directions are always reloaded together (<cf/in/ or
843 <cf/out/ options are ignored in that case).
848 <tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
849 Control protocol debugging.
851 <tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
852 Dump contents of internal data structures to the debugging output.
854 <tag>echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
855 Control echoing of log messages to the command-line output.
856 See <ref id="dsc-log" name="log option"> for a list of log classes.
858 <tag>eval <m/expr/</tag>
859 Evaluate given expression.
867 <p>BIRD contains a simple programming language. (No, it can't yet read mail :-).
868 There are two objects in this language: filters and functions. Filters are
869 interpreted by BIRD core when a route is being passed between protocols and
870 routing tables. The filter language contains control structures such as if's and
871 switches, but it allows no loops. An example of a filter using many features can
872 be found in <file>filter/test.conf</file>.
874 <p>Filter gets the route, looks at its attributes and modifies some of them if
875 it wishes. At the end, it decides whether to pass the changed route through
876 (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks like
883 if defined( rip_metric ) then
889 if rip_metric > 10 then
890 reject "RIP metric is too big";
896 <p>As you can see, a filter has a header, a list of local variables, and a body.
897 The header consists of the <cf/filter/ keyword followed by a (unique) name of
898 filter. The list of local variables consists of <cf><M>type name</M>;</cf>
899 pairs where each pair defines one local variable. The body consists of <cf>
900 { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You
901 can group several statements to a single compound statement by using braces
902 (<cf>{ <M>statements</M> }</cf>) which is useful if you want to make a bigger
903 block of code conditional.
905 <p>BIRD supports functions, so that you don't have to repeat the same blocks of
906 code over and over. Functions can have zero or more parameters and they can have
907 local variables. Recursion is not allowed. Function definitions look like this:
916 function with_parameters (int parameter)
922 <p>Unlike in C, variables are declared after the <cf/function/ line, but before
923 the first <cf/{/. You can't declare variables in nested blocks. Functions are
924 called like in C: <cf>name(); with_parameters(5);</cf>. Function may return
925 values using the <cf>return <m/[expr]/</cf> command. Returning a value exits
926 from current function (this is similar to C).
928 <p>Filters are declared in a way similar to functions except they can't have
929 explicit parameters. They get a route table entry as an implicit parameter, it
930 is also passed automatically to any functions called. The filter must terminate
931 with either <cf/accept/ or <cf/reject/ statement. If there's a runtime error in
932 filter, the route is rejected.
934 <p>A nice trick to debug filters is to use <cf>show route filter <m/name/</cf>
935 from the command line client. An example session might look like:
938 pavel@bug:~/bird$ ./birdc -s bird.ctl
941 10.0.0.0/8 dev eth0 [direct1 23:21] (240)
942 195.113.30.2/32 dev tunl1 [direct1 23:21] (240)
943 127.0.0.0/8 dev lo [direct1 23:21] (240)
945 show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
946 bird> show route filter { if 127.0.0.5 ˜ net then accept; }
947 127.0.0.0/8 dev lo [direct1 23:21] (240)
954 <p>Each variable and each value has certain type. Booleans, integers and enums
955 are incompatible with each other (that is to prevent you from shooting in the
960 This is a boolean type, it can have only two values, <cf/true/ and
961 <cf/false/. Boolean is the only type you can use in <cf/if/ statements.
964 This is a general integer type. It is an unsigned 32bit type; i.e., you
965 can expect it to store values from 0 to 4294967295. Overflows are not
966 checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
969 This is a pair of two short integers. Each component can have values
970 from 0 to 65535. Literals of this type are written as <cf/(1234,5678)/.
971 The same syntax can also be used to construct a pair from two arbitrary
972 integer expressions (for example <cf/(1+2,a)/).
975 This is a dotted quad of numbers used to represent router IDs (and
976 others). Each component can have a value from 0 to 255. Literals of
977 this type are written like IPv4 addresses.
980 This is a string of characters. There are no ways to modify strings in
981 filters. You can pass them between functions, assign them to variables
982 of type <cf/string/, print such variables, use standard string
983 comparison operations (e.g. <cf/=, !=, <, >, <=, >=/), but
984 you can't concatenate two strings. String literals are written as
985 <cf/"This is a string constant"/. Additionaly matching <cf/˜/
986 operator could be used to match a string value against a shell pattern
987 (represented also as a string).
990 This type can hold a single IP address. Depending on the compile-time
991 configuration of BIRD you are using, it is either an IPv4 or IPv6
992 address. IP addresses are written in the standard notation
993 (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator
994 <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out all but
995 first <cf><M>num</M></cf> bits from the IP address. So
996 <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
999 This type can hold a network prefix consisting of IP address and prefix
1000 length. Prefix literals are written as <cf><m/ipaddress//<m/pxlen/</cf>,
1001 or <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
1002 operators on prefixes: <cf/.ip/ which extracts the IP address from the
1003 pair, and <cf/.len/, which separates prefix length from the pair.
1004 So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
1008 This is a specialized type used to represent BGP extended community
1009 values. It is essentially a 64bit value, literals of this type are
1010 usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>, where
1011 <cf/kind/ is a kind of extended community (e.g. <cf/rt/ / <cf/ro/ for a
1012 route target / route origin communities), the format and possible values
1013 of <cf/key/ and <cf/value/ are usually integers, but it depends on the
1014 used kind. Similarly to pairs, ECs can be constructed using expressions
1015 for <cf/key/ and <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
1016 <cf/myas/ is an integer variable).
1018 <tag/int|pair|quad|ip|prefix|ec|enum set/
1019 Filters recognize four types of sets. Sets are similar to strings: you
1020 can pass them around but you can't modify them. Literals of type <cf>int
1021 set</cf> look like <cf> [ 1, 2, 5..7 ]</cf>. As you can see, both simple
1022 values and ranges are permitted in sets.
1024 For pair sets, expressions like <cf/(123,*)/ can be used to denote
1025 ranges (in that case <cf/(123,0)..(123,65535)/). You can also use
1026 <cf/(123,5..100)/ for range <cf/(123,5)..(123,100)/. You can also use
1027 <cf/*/ and <cf/a..b/ expressions in the first part of a pair, note that
1028 such expressions are translated to a set of intervals, which may be
1029 memory intensive. E.g. <cf/(*,4..20)/ is translated to <cf/(0,4..20),
1030 (1,4..20), (2,4..20), ... (65535, 4..20)/.
1032 EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123,
1033 10..20)/ or <cf/(ro, 123, *)/. Expressions requiring the translation
1034 (like <cf/(rt, *, 3)/) are not allowed (as they usually have 4B range
1037 You can also use expressions for int, pair and EC set values. However it
1038 must be possible to evaluate these expressions before daemon boots. So
1039 you can use only constants inside them. E.g.
1048 odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
1049 ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
1050 es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
1053 Sets of prefixes are special: their literals does not allow ranges, but
1054 allows prefix patterns that are written
1055 as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
1056 Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix
1057 pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if the
1058 first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are
1059 identical and <cf>len1 <= ip1 <= len2</cf>. A valid prefix pattern
1060 has to satisfy <cf>low <= high</cf>, but <cf/pxlen/ is not
1061 constrained by <cf/low/ or <cf/high/. Obviously, a prefix matches a
1062 prefix set literal if it matches any prefix pattern in the prefix set
1065 There are also two shorthands for prefix patterns: <cf><m/address//<m/len/+</cf>
1066 is a shorthand for <cf><m/address//<m/len/{<m/len/,<m/maxlen/}</cf>
1067 (where <cf><m/maxlen/</cf> is 32 for IPv4 and 128 for IPv6), that means
1068 network prefix <cf><m/address//<m/len/</cf> and all its subnets.
1069 <cf><m/address//<m/len/-</cf> is a shorthand for
1070 <cf><m/address//<m/len/{0,<m/len/}</cf>, that means network prefix
1071 <cf><m/address//<m/len/</cf> and all its supernets (network prefixes
1074 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}
1075 ]</cf> matches prefix <cf>1.0.0.0/8</cf>, all subprefixes of
1076 <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes
1077 <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf>
1078 matches all prefixes (regardless of IP address) whose prefix length is
1079 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP
1080 address <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 ˜ [ 1.0.0.0/8{15,17} ]</cf>
1081 is true, but <cf>1.0.0.0/16 ˜ [ 1.0.0.0/8- ]</cf> is false.
1083 Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
1084 in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as
1085 <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
1086 <cf>192.168.0.0/16{24,32}</cf>.
1089 Enumeration types are fixed sets of possibilities. You can't define your
1090 own variables of such type, but some route attributes are of enumeration
1091 type. Enumeration types are incompatible with each other.
1094 BGP path is a list of autonomous system numbers. You can't write
1095 literals of this type. There are several special operators on bgppaths:
1097 <cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/.
1099 <cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/.
1101 Both <cf/first/ and <cf/last/ return zero if there is no appropriate
1102 ASN, for example if the path contains an AS set element as the first (or
1105 <cf><m/P/.len</cf> returns the length of path <m/P/.
1107 <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and
1110 <cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN <m/A/ from
1111 from path <m/P/ and returns the result. <m/A/ may also be an integer
1112 set, in that case the operator deletes all ASNs from path <m/P/ that are
1113 also members of set <m/A/.
1115 <cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path <m/P/ that are
1116 not members of integer set <m/A/. I.e., <cf/filter/ do the same as
1117 <cf/delete/ with inverted set <m/A/.
1119 Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
1120 <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
1121 (for example <cf/bgp_path/). Similarly for <cf/delete/ and <cf/filter/.
1124 BGP masks are patterns used for BGP path matching (using <cf>path
1125 ˜ [= 2 3 5 * =]</cf> syntax). The masks resemble wildcard patterns
1126 as used by UNIX shells. Autonomous system numbers match themselves,
1127 <cf/*/ matches any (even empty) sequence of arbitrary AS numbers and
1128 <cf/?/ matches one arbitrary AS number. For example, if <cf>bgp_path</cf>
1129 is 4 3 2 1, then: <tt>bgp_path ˜ [= * 4 3 * =]</tt> is true,
1130 but <tt>bgp_path ˜ [= * 4 5 * =]</tt> is false. BGP mask
1131 expressions can also contain integer expressions enclosed in parenthesis
1132 and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. There is
1133 also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
1136 Clist is similar to a set, except that unlike other sets, it can be
1137 modified. The type is used for community list (a set of pairs) and for
1138 cluster list (a set of quads). There exist no literals of this type.
1139 There are three special operators on clists:
1141 <cf><m/C/.len</cf> returns the length of clist <m/C/.
1143 <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and
1144 returns the result. If item <m/P/ is already in clist <m/C/, it does
1145 nothing. <m/P/ may also be a clist, in that case all its members are
1146 added; i.e., it works as clist union.
1148 <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad) <m/P/ from clist
1149 <m/C/ and returns the result. If clist <m/C/ does not contain item
1150 <m/P/, it does nothing. <m/P/ may also be a pair (or quad) set, in that
1151 case the operator deletes all items from clist <m/C/ that are also
1152 members of set <m/P/. Moreover, <m/P/ may also be a clist, which works
1153 analogously; i.e., it works as clist difference.
1155 <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist <m/C/ that are
1156 not members of pair (or quad) set <m/P/. I.e., <cf/filter/ do the same
1157 as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which
1158 works analogously; i.e., it works as clist intersection.
1160 Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
1161 <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute (for
1162 example <cf/bgp_community/). Similarly for <cf/delete/ and <cf/filter/.
1165 Eclist is a data type used for BGP extended community lists. Eclists
1166 are very similar to clists, but they are sets of ECs instead of pairs.
1167 The same operations (like <cf/add/, <cf/delete/, or <cf/˜/
1168 membership operator) can be used to modify or test eclists, with ECs
1169 instead of pairs as arguments.
1175 <p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>,
1176 parentheses <cf/(a*(b+c))/, comparison <cf/(a=b, a!=b, a<b, a>=b)/.
1177 Logical operations include unary not (<cf/!/), and (<cf/&&/) and or
1178 (<cf/||/). Special operators include <cf/˜/ for "is element
1179 of a set" operation - it can be used on element and set of elements of the same
1180 type (returning true if element is contained in the given set), or on two
1181 strings (returning true if first string matches a shell-like pattern stored in
1182 second string) or on IP and prefix (returning true if IP is within the range
1183 defined by that prefix), or on prefix and prefix (returning true if first prefix
1184 is more specific than second one) or on bgppath and bgpmask (returning true if
1185 the path matches the mask) or on number and bgppath (returning true if the
1186 number is in the path) or on bgppath and int (number) set (returning true if any
1187 ASN from the path is in the set) or on pair/quad and clist (returning true if
1188 the pair/quad is element of the clist) or on clist and pair/quad set (returning
1189 true if there is an element of the clist that is also a member of the pair/quad
1192 <p>There is one operator related to ROA infrastructure - <cf/roa_check()/. It
1193 examines a ROA table and does RFC 6483 route origin validation for a given
1194 network prefix. The basic usage is <cf>roa_check(<m/table/)</cf>, which checks
1195 current route (which should be from BGP to have AS_PATH argument) in the
1196 specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA,
1197 ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant
1198 ROAs but none of them match. There is also an extended variant
1199 <cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to specify a
1200 prefix and an ASN as arguments.
1203 <sect>Control structures
1205 <p>Filters support two control structures: conditions and case switches.
1207 <p>Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/command1/;
1208 else <m/command2/;</cf> and you can use <cf>{ <m/command_1/; <m/command_2/;
1209 <M>...</M> }</cf> instead of either command. The <cf>else</cf> clause may be
1210 omitted. If the <cf><m>boolean expression</m></cf> is true, <m/command1/ is
1211 executed, otherwise <m/command2/ is executed.
1213 <p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case
1214 <m/expr/ { else: | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [
1215 ... ] }</cf>. The expression after <cf>case</cf> can be of any type which can be
1216 on the left side of the ˜ operator and anything that could be a member of
1217 a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/
1218 grouping. If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements
1219 between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches
1220 neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed.
1222 <p>Here is example that uses <cf/if/ and <cf/case/ structures:
1226 2: print "two"; print "I can do more commands without {}";
1227 3 .. 5: print "three to five";
1228 else: print "something else";
1231 if 1234 = i then printn "."; else {
1233 print "You need {} around multiple commands";
1238 <sect>Route attributes
1240 <p>A filter is implicitly passed a route, and it can access its attributes just
1241 like it accesses variables. Attempts to access undefined attribute result in a
1242 runtime error; you can check if an attribute is defined by using the
1243 <cf>defined( <m>attribute</m> )</cf> operator. One notable exception to this
1244 rule are attributes of clist type, where undefined value is regarded as empty
1245 clist for most purposes.
1248 <tag><m/prefix/ net</tag>
1249 Network the route is talking about. Read-only. (See the chapter about
1252 <tag><m/enum/ scope</tag>
1253 The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes
1254 local to this host, <cf/SCOPE_LINK/ for those specific for a physical
1255 link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private routes and
1256 <cf/SCOPE_UNIVERSE/ for globally visible routes. This attribute is not
1257 interpreted by BIRD and can be used to mark routes in filters. The
1258 default value for new routes is <cf/SCOPE_UNIVERSE/.
1260 <tag><m/int/ preference</tag>
1261 Preference of the route. Valid values are 0-65535. (See the chapter
1262 about routing tables.)
1264 <tag><m/ip/ from</tag>
1265 The router which the route has originated from.
1267 <tag><m/ip/ gw</tag>
1268 Next hop packets routed using this route should be forwarded to.
1270 <tag><m/string/ proto</tag>
1271 The name of the protocol which the route has been imported from.
1274 <tag><m/enum/ source</tag>
1275 what protocol has told me about this route. Possible values:
1276 <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/,
1277 <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/,
1278 <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/,
1281 <tag><m/enum/ cast</tag>
1282 Route type (Currently <cf/RTC_UNICAST/ for normal routes,
1283 <cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will be used in
1284 the future for broadcast, multicast and anycast routes). Read-only.
1286 <tag><m/enum/ dest</tag>
1287 Type of destination the packets should be sent to
1288 (<cf/RTD_ROUTER/ for forwarding to a neighboring router,
1289 <cf/RTD_DEVICE/ for routing to a directly-connected network,
1290 <cf/RTD_MULTIPATH/ for multipath destinations,
1291 <cf/RTD_BLACKHOLE/ for packets to be silently discarded,
1292 <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be
1293 returned with ICMP host unreachable / ICMP administratively prohibited
1294 messages). Can be changed, but only to <cf/RTD_BLACKHOLE/,
1295 <cf/RTD_UNREACHABLE/ or <cf/RTD_PROHIBIT/.
1297 <tag><m/string/ ifname</tag>
1298 Name of the outgoing interface. Sink routes (like blackhole, unreachable
1299 or prohibit) and multipath routes have no interface associated with
1300 them, so <cf/ifname/ returns an empty string for such routes. Read-only.
1302 <tag><m/int/ ifindex</tag>
1303 Index of the outgoing interface. System wide index of the interface. May
1304 be used for interface matching, however indexes might change on interface
1305 creation/removal. Zero is returned for routes with undefined outgoing
1306 interfaces. Read-only.
1308 <tag><m/int/ igp_metric</tag>
1309 The optional attribute that can be used to specify a distance to the
1310 network for routes that do not have a native protocol metric attribute
1311 (like <cf/ospf_metric1/ for OSPF routes). It is used mainly by BGP to
1312 compare internal distances to boundary routers (see below). It is also
1313 used when the route is exported to OSPF as a default value for OSPF type
1317 <p>There also exist some protocol-specific attributes which are described in the
1318 corresponding protocol sections.
1321 <sect>Other statements
1323 <p>The following statements are available:
1326 <tag><m/variable/ = <m/expr/</tag>
1327 Set variable to a given value.
1329 <tag>accept|reject [ <m/expr/ ]</tag>
1330 Accept or reject the route, possibly printing <cf><m>expr</m></cf>.
1332 <tag>return <m/expr/</tag>
1333 Return <cf><m>expr</m></cf> from the current function, the function ends
1336 <tag>print|printn <m/expr/ [<m/, expr.../]</tag>
1337 Prints given expressions; useful mainly while debugging filters. The
1338 <cf/printn/ variant does not terminate the line.
1341 Terminates BIRD. Useful when debugging the filter interpreter.
1347 <sect><label id="sect-bfd">BFD
1351 <p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it
1352 is an independent tool providing liveness and failure detection. Routing
1353 protocols like OSPF and BGP use integrated periodic "hello" messages to monitor
1354 liveness of neighbors, but detection times of these mechanisms are high (e.g. 40
1355 seconds by default in OSPF, could be set down to several seconds). BFD offers
1356 universal, fast and low-overhead mechanism for failure detection, which could be
1357 attached to any routing protocol in an advisory role.
1359 <p>BFD consists of mostly independent BFD sessions. Each session monitors an
1360 unicast bidirectional path between two BFD-enabled routers. This is done by
1361 periodically sending control packets in both directions. BFD does not handle
1362 neighbor discovery, BFD sessions are created on demand by request of other
1363 protocols (like OSPF or BGP), which supply appropriate information like IP
1364 addresses and associated interfaces. When a session changes its state, these
1365 protocols are notified and act accordingly (e.g. break an OSPF adjacency when
1366 the BFD session went down).
1368 <p>BIRD implements basic BFD behavior as defined in
1369 RFC 5880<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5880.txt">
1370 (some advanced features like the echo mode or authentication are not implemented),
1371 IP transport for BFD as defined in
1372 RFC 5881<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5881.txt"> and
1373 RFC 5883<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5883.txt">
1374 and interaction with client protocols as defined in
1375 RFC 5882<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5882.txt">.
1377 <p>Note that BFD implementation in BIRD is currently a new feature in
1378 development, expect some rough edges and possible UI and configuration changes
1379 in the future. Also note that we currently support at most one protocol instance.
1381 <p>BFD packets are sent with a dynamic source port number. Linux systems use by
1382 default a bit different dynamic port range than the IANA approved one
1383 (49152-65535). If you experience problems with compatibility, please adjust
1384 <cf>/proc/sys/net/ipv4/ip_local_port_range</cf>
1386 <sect1>Configuration
1388 <p>BFD configuration consists mainly of multiple definitions of interfaces.
1389 Most BFD config options are session specific. When a new session is requested
1390 and dynamically created, it is configured from one of these definitions. For
1391 sessions to directly connected neighbors, <cf/interface/ definitions are chosen
1392 based on the interface associated with the session, while <cf/multihop/
1393 definition is used for multihop sessions. If no definition is relevant, the
1394 session is just created with the default configuration. Therefore, an empty BFD
1395 configuration is often sufficient.
1397 <p>Note that to use BFD for other protocols like OSPF or BGP, these protocols
1398 also have to be configured to request BFD sessions, usually by <cf/bfd/ option.
1400 <p>Some of BFD session options require <m/time/ value, which has to be specified
1401 with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds
1402 are allowed as units, practical minimum values are usually in order of tens of
1406 protocol bfd [<name>] {
1407 interface <interface pattern> {
1408 interval <time>;
1409 min rx interval <time>;
1410 min tx interval <time>;
1411 idle tx interval <time>;
1412 multiplier <num>;
1413 passive <switch>;
1416 interval <time>;
1417 min rx interval <time>;
1418 min tx interval <time>;
1419 idle tx interval <time>;
1420 multiplier <num>;
1421 passive <switch>;
1423 neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>];
1428 <tag>interface <m/pattern [, ...]/ { <m/options/ }</tag>
1429 Interface definitions allow to specify options for sessions associated
1430 with such interfaces and also may contain interface specific options.
1431 See <ref id="dsc-iface" name="interface"> common option for a detailed
1432 description of interface patterns. Note that contrary to the behavior of
1433 <cf/interface/ definitions of other protocols, BFD protocol would accept
1434 sessions (in default configuration) even on interfaces not covered by
1437 <tag>multihop { <m/options/ }</tag>
1438 Multihop definitions allow to specify options for multihop BFD sessions,
1439 in the same manner as <cf/interface/ definitions are used for directly
1440 connected sessions. Currently only one such definition (for all multihop
1441 sessions) could be used.
1443 <tag>neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag>
1444 BFD sessions are usually created on demand as requested by other
1445 protocols (like OSPF or BGP). This option allows to explicitly add
1446 a BFD session to the specified neighbor regardless of such requests.
1448 The session is identified by the IP address of the neighbor, with
1449 optional specification of used interface and local IP. By default
1450 the neighbor must be directly connected, unless the the session is
1451 configured as multihop. Note that local IP must be specified for
1455 <p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions):
1458 <tag>interval <m/time/</tag>
1459 BFD ensures availability of the forwarding path associated with the
1460 session by periodically sending BFD control packets in both
1461 directions. The rate of such packets is controlled by two options,
1462 <cf/min rx interval/ and <cf/min tx interval/ (see below). This option
1463 is just a shorthand to set both of these options together.
1465 <tag>min rx interval <m/time/</tag>
1466 This option specifies the minimum RX interval, which is announced to the
1467 neighbor and used there to limit the neighbor's rate of generated BFD
1468 control packets. Default: 10 ms.
1470 <tag>min tx interval <m/time/</tag>
1471 This option specifies the desired TX interval, which controls the rate
1472 of generated BFD control packets (together with <cf/min rx interval/
1473 announced by the neighbor). Note that this value is used only if the BFD
1474 session is up, otherwise the value of <cf/idle tx interval/ is used
1475 instead. Default: 100 ms.
1477 <tag>idle tx interval <m/time/</tag>
1478 In order to limit unnecessary traffic in cases where a neighbor is not
1479 available or not running BFD, the rate of generated BFD control packets
1480 is lower when the BFD session is not up. This option specifies the
1481 desired TX interval in such cases instead of <cf/min tx interval/.
1484 <tag>multiplier <m/num/</tag>
1485 Failure detection time for BFD sessions is based on established rate of
1486 BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this
1487 multiplier, which is essentially (ignoring jitter) a number of missed
1488 packets after which the session is declared down. Note that rates and
1489 multipliers could be different in each direction of a BFD session.
1492 <tag>passive <m/switch/</tag>
1493 Generally, both BFD session endpoinds try to establish the session by
1494 sending control packets to the other side. This option allows to enable
1495 passive mode, which means that the router does not send BFD packets
1496 until it has received one from the other side. Default: disabled.
1504 min rx interval 20 ms;
1505 min tx interval 50 ms;
1506 idle tx interval 300 ms;
1518 neighbor 192.168.1.10;
1519 neighbor 192.168.2.2 dev "eth2";
1520 neighbor 192.168.10.1 local 192.168.1.1 multihop;
1527 <p>The Border Gateway Protocol is the routing protocol used for backbone level
1528 routing in the today's Internet. Contrary to other protocols, its convergence
1529 does not rely on all routers following the same rules for route selection,
1530 making it possible to implement any routing policy at any router in the network,
1531 the only restriction being that if a router advertises a route, it must accept
1532 and forward packets according to it.
1534 <p>BGP works in terms of autonomous systems (often abbreviated as AS). Each AS
1535 is a part of the network with common management and common routing policy. It is
1536 identified by a unique 16-bit number (ASN). Routers within each AS usually
1537 exchange AS-internal routing information with each other using an interior
1538 gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of
1539 the AS communicate global (inter-AS) network reachability information with their
1540 neighbors in the neighboring AS'es via exterior BGP (eBGP) and redistribute
1541 received information to other routers in the AS via interior BGP (iBGP).
1543 <p>Each BGP router sends to its neighbors updates of the parts of its routing
1544 table it wishes to export along with complete path information (a list of AS'es
1545 the packet will travel through if it uses the particular route) in order to
1546 avoid routing loops.
1548 <p>BIRD supports all requirements of the BGP4 standard as defined in
1549 RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
1550 It also supports the community attributes
1551 (RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
1552 capability negotiation
1553 (RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
1554 MD5 password authentication
1555 (RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
1556 extended communities
1557 (RFC 4360<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt">),
1559 (RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
1561 (RFC 4724<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4724.txt">),
1562 multiprotocol extensions
1563 (RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
1565 (RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">),
1566 and 4B AS numbers in extended communities
1567 (RFC 5668<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt">).
1570 For IPv6, it uses the standard multiprotocol extensions defined in
1571 RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">
1572 and applied to IPv6 according to
1573 RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
1575 <sect1>Route selection rules
1577 <p>BGP doesn't have any simple metric, so the rules for selection of an optimal
1578 route among multiple BGP routes with the same preference are a bit more complex
1579 and they are implemented according to the following algorithm. It starts the
1580 first rule, if there are more "best" routes, then it uses the second rule to
1581 choose among them and so on.
1584 <item>Prefer route with the highest Local Preference attribute.
1585 <item>Prefer route with the shortest AS path.
1586 <item>Prefer IGP origin over EGP and EGP origin over incomplete.
1587 <item>Prefer the lowest value of the Multiple Exit Discriminator.
1588 <item>Prefer routes received via eBGP over ones received via iBGP.
1589 <item>Prefer routes with lower internal distance to a boundary router.
1590 <item>Prefer the route with the lowest value of router ID of the
1594 <sect1>IGP routing table
1596 <p>BGP is mainly concerned with global network reachability and with routes to
1597 other autonomous systems. When such routes are redistributed to routers in the
1598 AS via BGP, they contain IP addresses of a boundary routers (in route attribute
1599 NEXT_HOP). BGP depends on existing IGP routing table with AS-internal routes to
1600 determine immediate next hops for routes and to know their internal distances to
1601 boundary routers for the purpose of BGP route selection. In BIRD, there is
1602 usually one routing table used for both IGP routes and BGP routes.
1604 <sect1>Configuration
1606 <p>Each instance of the BGP corresponds to one neighboring router. This allows
1607 to set routing policy and all the other parameters differently for each neighbor
1608 using the following configuration parameters:
1611 <tag>local [<m/ip/] as <m/number/</tag>
1612 Define which AS we are part of. (Note that contrary to other IP routers,
1613 BIRD is able to act as a router located in multiple AS'es simultaneously,
1614 but in such cases you need to tweak the BGP paths manually in the filters
1615 to get consistent behavior.) Optional <cf/ip/ argument specifies a source
1616 address, equivalent to the <cf/source address/ option (see below). This
1617 parameter is mandatory.
1619 <tag>neighbor <m/ip/ as <m/number/</tag>
1620 Define neighboring router this instance will be talking to and what AS
1621 it's located in. In case the neighbor is in the same AS as we are, we
1622 automatically switch to iBGP. This parameter is mandatory.
1625 Specify that the neighbor is directly connected. The IP address of the
1626 neighbor must be from a directly reachable IP range (i.e. associated
1627 with one of your router's interfaces), otherwise the BGP session
1628 wouldn't start but it would wait for such interface to appear. The
1629 alternative is the <cf/multihop/ option. Default: enabled for eBGP.
1631 <tag>multihop [<m/number/]</tag>
1632 Configure multihop BGP session to a neighbor that isn't directly
1633 connected. Accurately, this option should be used if the configured
1634 neighbor IP address does not match with any local network subnets. Such
1635 IP address have to be reachable through system routing table. The
1636 alternative is the <cf/direct/ option. For multihop BGP it is
1637 recommended to explicitly configure the source address to have it
1638 stable. Optional <cf/number/ argument can be used to specify the number
1639 of hops (used for TTL). Note that the number of networks (edges) in a
1640 path is counted; i.e., if two BGP speakers are separated by one router,
1641 the number of hops is 2. Default: enabled for iBGP.
1643 <tag>source address <m/ip/</tag>
1644 Define local address we should use for next hop calculation and as a
1645 source address for the BGP session. Default: the address of the local
1646 end of the interface our neighbor is connected to.
1648 <tag>next hop self</tag>
1649 Avoid calculation of the Next Hop attribute and always advertise our own
1650 source address as a next hop. This needs to be used only occasionally to
1651 circumvent misconfigurations of other routers. Default: disabled.
1653 <tag>next hop keep</tag>
1654 Forward the received Next Hop attribute even in situations where the
1655 local address should be used instead, like when the route is sent to an
1656 interface with a different subnet. Default: disabled.
1658 <tag>missing lladdr self|drop|ignore</tag>
1659 Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6
1660 address, but sometimes it has to contain both global and link-local IPv6
1661 addresses. This option specifies what to do if BIRD have to send both
1662 addresses but does not know link-local address. This situation might
1663 happen when routes from other protocols are exported to BGP, or when
1664 improper updates are received from BGP peers. <cf/self/ means that BIRD
1665 advertises its own local address instead. <cf/drop/ means that BIRD
1666 skips that prefixes and logs error. <cf/ignore/ means that BIRD ignores
1667 the problem and sends just the global address (and therefore forms
1668 improper BGP update). Default: <cf/self/, unless BIRD is configured as a
1669 route server (option <cf/rs client/), in that case default is <cf/ignore/,
1670 because route servers usually do not forward packets themselves.
1672 <tag>gateway direct|recursive</tag>
1673 For received routes, their <cf/gw/ (immediate next hop) attribute is
1674 computed from received <cf/bgp_next_hop/ attribute. This option
1675 specifies how it is computed. Direct mode means that the IP address from
1676 <cf/bgp_next_hop/ is used if it is directly reachable, otherwise the
1677 neighbor IP address is used. Recursive mode means that the gateway is
1678 computed by an IGP routing table lookup for the IP address from
1679 <cf/bgp_next_hop/. Recursive mode is the behavior specified by the BGP
1680 standard. Direct mode is simpler, does not require any routes in a
1681 routing table, and was used in older versions of BIRD, but does not
1682 handle well nontrivial iBGP setups and multihop. Recursive mode is
1683 incompatible with <ref id="dsc-sorted" name="sorted tables">. Default:
1684 <cf/direct/ for direct sessions, <cf/recursive/ for multihop sessions.
1686 <tag>igp table <m/name/</tag>
1687 Specifies a table that is used as an IGP routing table. Default: the
1688 same as the table BGP is connected to.
1690 <tag>bfd <M>switch</M></tag>
1691 BGP could use BFD protocol as an advisory mechanism for neighbor
1692 liveness and failure detection. If enabled, BIRD setups a BFD session
1693 for the BGP neighbor and tracks its liveness by it. This has an
1694 advantage of an order of magnitude lower detection times in case of
1695 failure. Note that BFD protocol also has to be configured, see
1696 <ref id="sect-bfd" name="BFD"> section for details. Default: disabled.
1698 <tag>ttl security <m/switch/</tag>
1699 Use GTSM (RFC 5082 - the generalized TTL security mechanism). GTSM
1700 protects against spoofed packets by ignoring received packets with a
1701 smaller than expected TTL. To work properly, GTSM have to be enabled on
1702 both sides of a BGP session. If both <cf/ttl security/ and <cf/multihop/
1703 options are enabled, <cf/multihop/ option should specify proper hop
1704 value to compute expected TTL. Kernel support required: Linux: 2.6.34+
1705 (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only. Note that full
1706 (ICMP protection, for example) RFC 5082 support is provided by Linux
1707 only. Default: disabled.
1709 <tag>password <m/string/</tag>
1710 Use this password for MD5 authentication of BGP sessions. Default: no
1711 authentication. Password has to be set by external utility
1712 (e.g. setkey(8)) on BSD systems.
1714 <tag>passive <m/switch/</tag>
1715 Standard BGP behavior is both initiating outgoing connections and
1716 accepting incoming connections. In passive mode, outgoing connections
1717 are not initiated. Default: off.
1719 <tag>rr client</tag>
1720 Be a route reflector and treat the neighbor as a route reflection
1721 client. Default: disabled.
1723 <tag>rr cluster id <m/IPv4 address/</tag>
1724 Route reflectors use cluster id to avoid route reflection loops. When
1725 there is one route reflector in a cluster it usually uses its router id
1726 as a cluster id, but when there are more route reflectors in a cluster,
1727 these need to be configured (using this option) to use a common cluster
1728 id. Clients in a cluster need not know their cluster id and this option
1729 is not allowed for them. Default: the same as router id.
1731 <tag>rs client</tag>
1732 Be a route server and treat the neighbor as a route server client.
1733 A route server is used as a replacement for full mesh EBGP routing in
1734 Internet exchange points in a similar way to route reflectors used in
1735 IBGP routing. BIRD does not implement obsoleted RFC 1863, but uses
1736 ad-hoc implementation, which behaves like plain EBGP but reduces
1737 modifications to advertised route attributes to be transparent (for
1738 example does not prepend its AS number to AS PATH attribute and keeps
1739 MED attribute). Default: disabled.
1741 <tag>secondary <m/switch/</tag>
1742 Usually, if an export filter rejects a selected route, no other route is
1743 propagated for that network. This option allows to try the next route in
1744 order until one that is accepted is found or all routes for that network
1745 are rejected. This can be used for route servers that need to propagate
1746 different tables to each client but do not want to have these tables
1747 explicitly (to conserve memory). This option requires that the connected
1748 routing table is <ref id="dsc-sorted" name="sorted">. Default: off.
1750 <tag>add paths <m/switch/|rx|tx</tag>
1751 Standard BGP can propagate only one path (route) per destination network
1752 (usually the selected one). This option controls the add-path protocol
1753 extension, which allows to advertise any number of paths to a
1754 destination. Note that to be active, add-path has to be enabled on both
1755 sides of the BGP session, but it could be enabled separately for RX and
1756 TX direction. When active, all available routes accepted by the export
1757 filter are advertised to the neighbor. Default: off.
1759 <tag>allow local as [<m/number/]</tag>
1760 BGP prevents routing loops by rejecting received routes with the local
1761 AS number in the AS path. This option allows to loose or disable the
1762 check. Optional <cf/number/ argument can be used to specify the maximum
1763 number of local ASNs in the AS path that is allowed for received
1764 routes. When the option is used without the argument, the check is
1765 completely disabled and you should ensure loop-free behavior by some
1766 other means. Default: 0 (no local AS number allowed).
1768 <tag>enable route refresh <m/switch/</tag>
1769 When BGP speaker changes its import filter, it has to re-examine all
1770 routes received from its neighbor against the new filter. As these
1771 routes might not be available, there is a BGP protocol extension Route
1772 Refresh (specified in RFC 2918) that allows BGP speaker to request
1773 re-advertisement of all routes from its neighbor. This option specifies
1774 whether BIRD advertises this capability and accepts such requests. Even
1775 when disabled, BIRD can send route refresh requests. Default: on.
1777 <tag>graceful restart <m/switch/|aware</tag>
1778 When a BGP speaker restarts or crashes, neighbors will discard all
1779 received paths from the speaker, which disrupts packet forwarding even
1780 when the forwarding plane of the speaker remains intact. RFC 4724
1781 specifies an optional graceful restart mechanism to alleviate this
1782 issue. This option controls the mechanism. It has three states:
1783 Disabled, when no support is provided. Aware, when the graceful restart
1784 support is announced and the support for restarting neighbors is
1785 provided, but no local graceful restart is allowed (i.e. receiving-only
1786 role). Enabled, when the full graceful restart support is provided
1787 (i.e. both restarting and receiving role). Note that proper support for
1788 local graceful restart requires also configuration of other protocols.
1791 <tag>graceful restart time <m/number/</tag>
1792 The restart time is announced in the BGP graceful restart capability
1793 and specifies how long the neighbor would wait for the BGP session to
1794 re-establish after a restart before deleting stale routes. Default:
1797 <tag>interpret communities <m/switch/</tag>
1798 RFC 1997 demands that BGP speaker should process well-known communities
1799 like no-export (65535, 65281) or no-advertise (65535, 65282). For
1800 example, received route carrying a no-adverise community should not be
1801 advertised to any of its neighbors. If this option is enabled (which is
1802 by default), BIRD has such behavior automatically (it is evaluated when
1803 a route is exported to the BGP protocol just before the export filter).
1804 Otherwise, this integrated processing of well-known communities is
1805 disabled. In that case, similar behavior can be implemented in the
1806 export filter. Default: on.
1808 <tag>enable as4 <m/switch/</tag>
1809 BGP protocol was designed to use 2B AS numbers and was extended later to
1810 allow 4B AS number. BIRD supports 4B AS extension, but by disabling this
1811 option it can be persuaded not to advertise it and to maintain old-style
1812 sessions with its neighbors. This might be useful for circumventing bugs
1813 in neighbor's implementation of 4B AS extension. Even when disabled
1814 (off), BIRD behaves internally as AS4-aware BGP router. Default: on.
1816 <tag>capabilities <m/switch/</tag>
1817 Use capability advertisement to advertise optional capabilities. This is
1818 standard behavior for newer BGP implementations, but there might be some
1819 older BGP implementations that reject such connection attempts. When
1820 disabled (off), features that request it (4B AS support) are also
1821 disabled. Default: on, with automatic fallback to off when received
1822 capability-related error.
1824 <tag>advertise ipv4 <m/switch/</tag>
1825 Advertise IPv4 multiprotocol capability. This is not a correct behavior
1826 according to the strict interpretation of RFC 4760, but it is widespread
1827 and required by some BGP implementations (Cisco and Quagga). This option
1828 is relevant to IPv4 mode with enabled capability advertisement
1831 <tag>route limit <m/number/</tag>
1832 The maximal number of routes that may be imported from the protocol. If
1833 the route limit is exceeded, the connection is closed with an error.
1834 Limit is currently implemented as <cf>import limit <m/number/ action
1835 restart</cf>. This option is obsolete and it is replaced by
1836 <ref id="import-limit" name="import limit option">. Default: no limit.
1838 <tag>disable after error <m/switch/</tag>
1839 When an error is encountered (either locally or by the other side),
1840 disable the instance automatically and wait for an administrator to fix
1841 the problem manually. Default: off.
1843 <tag>hold time <m/number/</tag>
1844 Time in seconds to wait for a Keepalive message from the other side
1845 before considering the connection stale. Default: depends on agreement
1846 with the neighboring router, we prefer 240 seconds if the other side is
1847 willing to accept it.
1849 <tag>startup hold time <m/number/</tag>
1850 Value of the hold timer used before the routers have a chance to exchange
1851 open messages and agree on the real value. Default: 240 seconds.
1853 <tag>keepalive time <m/number/</tag>
1854 Delay in seconds between sending of two consecutive Keepalive messages.
1855 Default: One third of the hold time.
1857 <tag>connect retry time <m/number/</tag>
1858 Time in seconds to wait before retrying a failed attempt to connect.
1859 Default: 120 seconds.
1861 <tag>start delay time <m/number/</tag>
1862 Delay in seconds between protocol startup and the first attempt to
1863 connect. Default: 5 seconds.
1865 <tag>error wait time <m/number/,<m/number/</tag>
1866 Minimum and maximum delay in seconds between a protocol failure (either
1867 local or reported by the peer) and automatic restart. Doesn't apply
1868 when <cf/disable after error/ is configured. If consecutive errors
1869 happen, the delay is increased exponentially until it reaches the
1870 maximum. Default: 60, 300.
1872 <tag>error forget time <m/number/</tag>
1873 Maximum time in seconds between two protocol failures to treat them as a
1874 error sequence which makes <cf/error wait time/ increase exponentially.
1875 Default: 300 seconds.
1877 <tag>path metric <m/switch/</tag>
1878 Enable comparison of path lengths when deciding which BGP route is the
1879 best one. Default: on.
1881 <tag>med metric <m/switch/</tag>
1882 Enable comparison of MED attributes (during best route selection) even
1883 between routes received from different ASes. This may be useful if all
1884 MED attributes contain some consistent metric, perhaps enforced in
1885 import filters of AS boundary routers. If this option is disabled, MED
1886 attributes are compared only if routes are received from the same AS
1887 (which is the standard behavior). Default: off.
1889 <tag>deterministic med <m/switch/</tag>
1890 BGP route selection algorithm is often viewed as a comparison between
1891 individual routes (e.g. if a new route appears and is better than the
1892 current best one, it is chosen as the new best one). But the proper
1893 route selection, as specified by RFC 4271, cannot be fully implemented
1894 in that way. The problem is mainly in handling the MED attribute. BIRD,
1895 by default, uses an simplification based on individual route comparison,
1896 which in some cases may lead to temporally dependent behavior (i.e. the
1897 selection is dependent on the order in which routes appeared). This
1898 option enables a different (and slower) algorithm implementing proper
1899 RFC 4271 route selection, which is deterministic. Alternative way how to
1900 get deterministic behavior is to use <cf/med metric/ option. This option
1901 is incompatible with <ref id="dsc-sorted" name="sorted tables">.
1904 <tag>igp metric <m/switch/</tag>
1905 Enable comparison of internal distances to boundary routers during best
1906 route selection. Default: on.
1908 <tag>prefer older <m/switch/</tag>
1909 Standard route selection algorithm breaks ties by comparing router IDs.
1910 This changes the behavior to prefer older routes (when both are external
1911 and from different peer). For details, see RFC 5004. Default: off.
1913 <tag>default bgp_med <m/number/</tag>
1914 Value of the Multiple Exit Discriminator to be used during route
1915 selection when the MED attribute is missing. Default: 0.
1917 <tag>default bgp_local_pref <m/number/</tag>
1918 A default value for the Local Preference attribute. It is used when
1919 a new Local Preference attribute is attached to a route by the BGP
1920 protocol itself (for example, if a route is received through eBGP and
1921 therefore does not have such attribute). Default: 100 (0 in pre-1.2.0
1927 <p>BGP defines several route attributes. Some of them (those marked with
1928 `<tt/I/' in the table below) are available on internal BGP connections only,
1929 some of them (marked with `<tt/O/') are optional.
1932 <tag>bgppath <cf/bgp_path/</tag>
1933 Sequence of AS numbers describing the AS path the packet will travel
1934 through when forwarded according to the particular route. In case of
1935 internal BGP it doesn't contain the number of the local AS.
1937 <tag>int <cf/bgp_local_pref/ [I]</tag>
1938 Local preference value used for selection among multiple BGP routes (see
1939 the selection rules above). It's used as an additional metric which is
1940 propagated through the whole local AS.
1942 <tag>int <cf/bgp_med/ [O]</tag>
1943 The Multiple Exit Discriminator of the route is an optional attribute
1944 which is used on external (inter-AS) links to convey to an adjacent AS
1945 the optimal entry point into the local AS. The received attribute is
1946 also propagated over internal BGP links. The attribute value is zeroed
1947 when a route is exported to an external BGP instance to ensure that the
1948 attribute received from a neighboring AS is not propagated to other
1949 neighboring ASes. A new value might be set in the export filter of an
1950 external BGP instance. See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
1951 for further discussion of BGP MED attribute.
1953 <tag>enum <cf/bgp_origin/</tag>
1954 Origin of the route: either <cf/ORIGIN_IGP/ if the route has originated
1955 in an interior routing protocol or <cf/ORIGIN_EGP/ if it's been imported
1956 from the <tt>EGP</tt> protocol (nowadays it seems to be obsolete) or
1957 <cf/ORIGIN_INCOMPLETE/ if the origin is unknown.
1959 <tag>ip <cf/bgp_next_hop/</tag>
1960 Next hop to be used for forwarding of packets to this destination. On
1961 internal BGP connections, it's an address of the originating router if
1962 it's inside the local AS or a boundary router the packet will leave the
1963 AS through if it's an exterior route, so each BGP speaker within the AS
1964 has a chance to use the shortest interior path possible to this point.
1966 <tag>void <cf/bgp_atomic_aggr/ [O]</tag>
1967 This is an optional attribute which carries no value, but the sole
1968 presence of which indicates that the route has been aggregated from
1969 multiple routes by some router on the path from the originator.
1971 <!-- we don't handle aggregators right since they are of a very obscure type
1972 <tag>bgp_aggregator</tag>
1974 <tag>clist <cf/bgp_community/ [O]</tag>
1975 List of community values associated with the route. Each such value is a
1976 pair (represented as a <cf/pair/ data type inside the filters) of 16-bit
1977 integers, the first of them containing the number of the AS which
1978 defines the community and the second one being a per-AS identifier.
1979 There are lots of uses of the community mechanism, but generally they
1980 are used to carry policy information like "don't export to USA peers".
1981 As each AS can define its own routing policy, it also has a complete
1982 freedom about which community attributes it defines and what will their
1985 <tag>eclist <cf/bgp_ext_community/ [O]</tag>
1986 List of extended community values associated with the route. Extended
1987 communities have similar usage as plain communities, but they have an
1988 extended range (to allow 4B ASNs) and a nontrivial structure with a type
1989 field. Individual community values are represented using an <cf/ec/ data
1990 type inside the filters.
1992 <tag>quad <cf/bgp_originator_id/ [I, O]</tag>
1993 This attribute is created by the route reflector when reflecting the
1994 route and contains the router ID of the originator of the route in the
1997 <tag>clist <cf/bgp_cluster_list/ [I, O]</tag>
1998 This attribute contains a list of cluster IDs of route reflectors. Each
1999 route reflector prepends its cluster ID when reflecting the route.
2006 local as 65000; # Use a private AS number
2007 neighbor 198.51.100.130 as 64496; # Our neighbor ...
2008 multihop; # ... which is connected indirectly
2009 export filter { # We use non-trivial export rules
2010 if source = RTS_STATIC then { # Export only static routes
2011 # Assign our community
2012 bgp_community.add((65000,64501));
2013 # Artificially increase path length
2014 # by advertising local AS number twice
2015 if bgp_path ~ [= 65000 =] then
2016 bgp_path.prepend(65000);
2022 source address 198.51.100.14; # Use a non-standard source address
2029 <p>The Device protocol is not a real routing protocol. It doesn't generate any
2030 routes and it only serves as a module for getting information about network
2031 interfaces from the kernel.
2033 <p>Except for very unusual circumstances, you probably should include this
2034 protocol in the configuration since almost all other protocols require network
2035 interfaces to be defined for them to work with.
2037 <sect1>Configuration
2041 <tag>scan time <m/number/</tag>
2043 Time in seconds between two scans of the network interface list. On
2044 systems where we are notified about interface status changes
2045 asynchronously (such as newer versions of Linux), we need to scan the
2046 list only in order to avoid confusion by lost notification messages,
2047 so the default time is set to a large value.
2049 <tag>primary [ "<m/mask/" ] <m/prefix/</tag>
2050 If a network interface has more than one network address, BIRD has to
2051 choose one of them as a primary one. By default, BIRD chooses the
2052 lexicographically smallest address as the primary one.
2054 This option allows to specify which network address should be chosen as
2055 a primary one. Network addresses that match <m/prefix/ are preferred to
2056 non-matching addresses. If more <cf/primary/ options are used, the first
2057 one has the highest preference. If "<m/mask/" is specified, then such
2058 <cf/primary/ option is relevant only to matching network interfaces.
2060 In all cases, an address marked by operating system as secondary cannot
2061 be chosen as the primary one.
2064 <p>As the Device protocol doesn't generate any routes, it cannot have
2065 any attributes. Example configuration looks like this:
2069 scan time 10; # Scan the interfaces often
2070 primary "eth0" 192.168.1.1;
2071 primary 192.168.0.0/16;
2078 <p>The Direct protocol is a simple generator of device routes for all the
2079 directly connected networks according to the list of interfaces provided by the
2080 kernel via the Device protocol.
2082 <p>The question is whether it is a good idea to have such device routes in BIRD
2083 routing table. OS kernel usually handles device routes for directly connected
2084 networks by itself so we don't need (and don't want) to export these routes to
2085 the kernel protocol. OSPF protocol creates device routes for its interfaces
2086 itself and BGP protocol is usually used for exporting aggregate routes. Although
2087 there are some use cases that use the direct protocol (like abusing eBGP as an
2088 IGP routing protocol), in most cases it is not needed to have these device
2089 routes in BIRD routing table and to use the direct protocol.
2091 <p>There is one notable case when you definitely want to use the direct protocol
2092 -- running BIRD on BSD systems. Having high priority device routes for directly
2093 connected networks from the direct protocol protects kernel device routes from
2094 being overwritten or removed by IGP routes during some transient network
2095 conditions, because a lower priority IGP route for the same network is not
2096 exported to the kernel routing table. This is an issue on BSD systems only, as
2097 on Linux systems BIRD cannot change non-BIRD route in the kernel routing table.
2099 <p>The only configurable thing about direct is what interfaces it watches:
2102 <tag>interface <m/pattern [, ...]/</tag>
2103 By default, the Direct protocol will generate device routes for all the
2104 interfaces available. If you want to restrict it to some subset of
2105 interfaces or addresses (e.g. if you're using multiple routing tables
2106 for policy routing and some of the policy domains don't contain all
2107 interfaces), just use this clause. See <ref id="dsc-iface" name="interface">
2108 common option for detailed description. The Direct protocol uses
2109 extended interface clauses.
2112 <p>Direct device routes don't contain any specific attributes.
2114 <p>Example config might look like this:
2118 interface "-arc*", "*"; # Exclude the ARCnets
2125 <p>The Kernel protocol is not a real routing protocol. Instead of communicating
2126 with other routers in the network, it performs synchronization of BIRD's routing
2127 tables with the OS kernel. Basically, it sends all routing table updates to the
2128 kernel and from time to time it scans the kernel tables to see whether some
2129 routes have disappeared (for example due to unnoticed up/down transition of an
2130 interface) or whether an `alien' route has been added by someone else (depending
2131 on the <cf/learn/ switch, such routes are either ignored or accepted to our
2134 <p>Unfortunately, there is one thing that makes the routing table synchronization
2135 a bit more complicated. In the kernel routing table there are also device routes
2136 for directly connected networks. These routes are usually managed by OS itself
2137 (as a part of IP address configuration) and we don't want to touch that. They
2138 are completely ignored during the scan of the kernel tables and also the export
2139 of device routes from BIRD tables to kernel routing tables is restricted to
2140 prevent accidental interference. This restriction can be disabled using
2141 <cf/device routes/ switch.
2143 <p>If your OS supports only a single routing table, you can configure only one
2144 instance of the Kernel protocol. If it supports multiple tables (in order to
2145 allow policy routing; such an OS is for example Linux), you can run as many
2146 instances as you want, but each of them must be connected to a different BIRD
2147 routing table and to a different kernel table.
2149 <p>Because the kernel protocol is partially integrated with the connected
2150 routing table, there are two limitations - it is not possible to connect more
2151 kernel protocols to the same routing table and changing route destination
2152 (gateway) in an export filter of a kernel protocol does not work. Both
2153 limitations can be overcome using another routing table and the pipe protocol.
2155 <sect1>Configuration
2158 <tag>persist <m/switch/</tag>
2159 Tell BIRD to leave all its routes in the routing tables when it exits
2160 (instead of cleaning them up).
2162 <tag>scan time <m/number/</tag>
2163 Time in seconds between two consecutive scans of the kernel routing
2166 <tag>learn <m/switch/</tag>
2167 Enable learning of routes added to the kernel routing tables by other
2168 routing daemons or by the system administrator. This is possible only on
2169 systems which support identification of route authorship.
2171 <tag>device routes <m/switch/</tag>
2172 Enable export of device routes to the kernel routing table. By default,
2173 such routes are rejected (with the exception of explicitly configured
2174 device routes from the static protocol) regardless of the export filter
2175 to protect device routes in kernel routing table (managed by OS itself)
2176 from accidental overwriting or erasing.
2178 <tag>kernel table <m/number/</tag>
2179 Select which kernel table should this particular instance of the Kernel
2180 protocol work with. Available only on systems supporting multiple
2183 <tag>graceful restart <m/switch/</tag>
2184 Participate in graceful restart recovery. If this option is enabled and
2185 a graceful restart recovery is active, the Kernel protocol will defer
2186 synchronization of routing tables until the end of the recovery. Note
2187 that import of kernel routes to BIRD is not affected.
2192 <p>The Kernel protocol defines several attributes. These attributes are
2193 translated to appropriate system (and OS-specific) route attributes. We support
2197 <tag>int <cf/krt_source/</tag>
2198 The original source of the imported kernel route. The value is
2199 system-dependent. On Linux, it is a value of the protocol field of the
2200 route. See /etc/iproute2/rt_protos for common values. On BSD, it is
2201 based on STATIC and PROTOx flags. The attribute is read-only.
2203 <tag>int <cf/krt_metric/</tag>
2204 The kernel metric of the route. When multiple same routes are in a
2205 kernel routing table, the Linux kernel chooses one with lower metric.
2207 <tag>ip <cf/krt_prefsrc/</tag> (Linux)
2208 The preferred source address. Used in source address selection for
2209 outgoing packets. Have to be one of IP addresses of the router.
2211 <tag>int <cf/krt_realm/</tag> (Linux)
2212 The realm of the route. Can be used for traffic classification.
2217 <p>A simple configuration can look this way:
2225 <p>Or for a system with two routing tables:
2228 protocol kernel { # Primary routing table
2229 learn; # Learn alien routes from the kernel
2230 persist; # Don't remove routes on bird shutdown
2231 scan time 10; # Scan kernel routing table every 10 seconds
2236 protocol kernel { # Secondary routing table
2248 <p>Open Shortest Path First (OSPF) is a quite complex interior gateway
2249 protocol. The current IPv4 version (OSPFv2) is defined in RFC 2328
2250 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt">
2251 and the current IPv6 version (OSPFv3) is defined in RFC 5340
2252 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt">
2253 It's a link state (a.k.a. shortest path first) protocol -- each router maintains
2254 a database describing the autonomous system's topology. Each participating
2255 router has an identical copy of the database and all routers run the same
2256 algorithm calculating a shortest path tree with themselves as a root. OSPF
2257 chooses the least cost path as the best path.
2259 <p>In OSPF, the autonomous system can be split to several areas in order to
2260 reduce the amount of resources consumed for exchanging the routing information
2261 and to protect the other areas from incorrect routing data. Topology of the area
2262 is hidden to the rest of the autonomous system.
2264 <p>Another very important feature of OSPF is that it can keep routing information
2265 from other protocols (like Static or BGP) in its link state database as external
2266 routes. Each external route can be tagged by the advertising router, making it
2267 possible to pass additional information between routers on the boundary of the
2270 <p>OSPF quickly detects topological changes in the autonomous system (such as
2271 router interface failures) and calculates new loop-free routes after a short
2272 period of convergence. Only a minimal amount of routing traffic is involved.
2274 <p>Each router participating in OSPF routing periodically sends Hello messages
2275 to all its interfaces. This allows neighbors to be discovered dynamically. Then
2276 the neighbors exchange theirs parts of the link state database and keep it
2277 identical by flooding updates. The flooding process is reliable and ensures that
2278 each router detects all changes.
2280 <sect1>Configuration
2282 <p>In the main part of configuration, there can be multiple definitions of OSPF
2283 areas, each with a different id. These definitions includes many other switches
2284 and multiple definitions of interfaces. Definition of interface may contain many
2285 switches and constant definitions and list of neighbors on nonbroadcast
2289 protocol ospf <name> {
2290 rfc1583compat <switch>;
2291 stub router <switch>;
2293 ecmp <switch> [limit <num>];
2294 merge external <switch>;
2298 summary <switch>;
2299 default nssa <switch>;
2300 default cost <num>;
2301 default cost2 <num>;
2302 translator <switch>;
2303 translator stability <num>;
2307 <prefix> hidden;
2311 <prefix> hidden;
2312 <prefix> tag <num>;
2314 stubnet <prefix>;
2315 stubnet <prefix> {
2316 hidden <switch>;
2317 summary <switch>;
2320 interface <interface pattern> [instance <num>] {
2322 stub <switch>;
2325 retransmit <num>;
2326 priority <num>;
2328 dead count <num>;
2330 secondary <switch>;
2331 rx buffer [normal|large|<num>];
2332 tx length <num>;
2333 type [broadcast|bcast|pointopoint|ptp|
2334 nonbroadcast|nbma|pointomultipoint|ptmp];
2335 strict nonbroadcast <switch>;
2336 real broadcast <switch>;
2337 ptp netmask <switch>;
2338 check link <switch>;
2340 ecmp weight <num>;
2341 ttl security [<switch>; | tx only]
2342 tx class|dscp <num>;
2343 tx priority <num>;
2344 authentication [none|simple|cryptographic];
2345 password "<text>";
2346 password "<text>" {
2348 generate from "<date>";
2349 generate to "<date>";
2350 accept from "<date>";
2351 accept to "<date>";
2355 <ip> eligible;
2358 virtual link <id> [instance <num>] {
2360 retransmit <num>;
2362 dead count <num>;
2364 authentication [none|simple|cryptographic];
2365 password "<text>";
2372 <tag>rfc1583compat <M>switch</M></tag>
2373 This option controls compatibility of routing table calculation with
2374 RFC 1583 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">.
2375 Default value is no.
2377 <tag>stub router <M>switch</M></tag>
2378 This option configures the router to be a stub router, i.e., a router
2379 that participates in the OSPF topology but does not allow transit
2380 traffic. In OSPFv2, this is implemented by advertising maximum metric
2381 for outgoing links, as suggested by
2382 RFC 3137 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3137.txt">.
2383 In OSPFv3, the stub router behavior is announced by clearing the R-bit
2384 in the router LSA. Default value is no.
2386 <tag>tick <M>num</M></tag>
2387 The routing table calculation and clean-up of areas' databases is not
2388 performed when a single link state change arrives. To lower the CPU
2389 utilization, it's processed later at periodical intervals of <m/num/
2390 seconds. The default value is 1.
2392 <tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
2393 This option specifies whether OSPF is allowed to generate ECMP
2394 (equal-cost multipath) routes. Such routes are used when there are
2395 several directions to the destination, each with the same (computed)
2396 cost. This option also allows to specify a limit on maximal number of
2397 nexthops in one route. By default, ECMP is disabled. If enabled,
2398 default value of the limit is 16.
2400 <tag>merge external <M>switch</M></tag>
2401 This option specifies whether OSPF should merge external routes from
2402 different routers/LSAs for the same destination. When enabled together
2403 with <cf/ecmp/, equal-cost external routes will be combined to multipath
2404 routes in the same way as regular routes. When disabled, external routes
2405 from different LSAs are treated as separate even if they represents the
2406 same destination. Default value is no.
2408 <tag>area <M>id</M></tag>
2409 This defines an OSPF area with given area ID (an integer or an IPv4
2410 address, similarly to a router ID). The most important area is the
2411 backbone (ID 0) to which every other area must be connected.
2414 This option configures the area to be a stub area. External routes are
2415 not flooded into stub areas. Also summary LSAs can be limited in stub
2416 areas (see option <cf/summary/). By default, the area is not a stub
2420 This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA
2421 is a variant of a stub area which allows a limited way of external route
2422 propagation. Global external routes are not propagated into a NSSA, but
2423 an external route can be imported into NSSA as a (area-wide) NSSA-LSA
2424 (and possibly translated and/or aggregated on area boundary). By
2425 default, the area is not NSSA.
2427 <tag>summary <M>switch</M></tag>
2428 This option controls propagation of summary LSAs into stub or NSSA
2429 areas. If enabled, summary LSAs are propagated as usual, otherwise just
2430 the default summary route (0.0.0.0/0) is propagated (this is sometimes
2431 called totally stubby area). If a stub area has more area boundary
2432 routers, propagating summary LSAs could lead to more efficient routing
2433 at the cost of larger link state database. Default value is no.
2435 <tag>default nssa <M>switch</M></tag>
2436 When <cf/summary/ option is enabled, default summary route is no longer
2437 propagated to the NSSA. In that case, this option allows to originate
2438 default route as NSSA-LSA to the NSSA. Default value is no.
2440 <tag>default cost <M>num</M></tag>
2441 This option controls the cost of a default route propagated to stub and
2442 NSSA areas. Default value is 1000.
2444 <tag>default cost2 <M>num</M></tag>
2445 When a default route is originated as NSSA-LSA, its cost can use either
2446 type 1 or type 2 metric. This option allows to specify the cost of a
2447 default route in type 2 metric. By default, type 1 metric (option
2448 <cf/default cost/) is used.
2450 <tag>translator <M>switch</M></tag>
2451 This option controls translation of NSSA-LSAs into external LSAs. By
2452 default, one translator per NSSA is automatically elected from area
2453 boundary routers. If enabled, this area boundary router would
2454 unconditionally translate all NSSA-LSAs regardless of translator
2455 election. Default value is no.
2457 <tag>translator stability <M>num</M></tag>
2458 This option controls the translator stability interval (in seconds).
2459 When the new translator is elected, the old one keeps translating until
2460 the interval is over. Default value is 40.
2462 <tag>networks { <m/set/ }</tag>
2463 Definition of area IP ranges. This is used in summary LSA origination.
2464 Hidden networks are not propagated into other areas.
2466 <tag>external { <m/set/ }</tag>
2467 Definition of external area IP ranges for NSSAs. This is used for
2468 NSSA-LSA translation. Hidden networks are not translated into external
2469 LSAs. Networks can have configured route tag.
2471 <tag>stubnet <m/prefix/ { <m/options/ }</tag>
2472 Stub networks are networks that are not transit networks between OSPF
2473 routers. They are also propagated through an OSPF area as a part of a
2474 link state database. By default, BIRD generates a stub network record
2475 for each primary network address on each OSPF interface that does not
2476 have any OSPF neighbors, and also for each non-primary network address
2477 on each OSPF interface. This option allows to alter a set of stub
2478 networks propagated by this router.
2480 Each instance of this option adds a stub network with given network
2481 prefix to the set of propagated stub network, unless option <cf/hidden/
2482 is used. It also suppresses default stub networks for given network
2483 prefix. When option <cf/summary/ is used, also default stub networks
2484 that are subnetworks of given stub network are suppressed. This might be
2485 used, for example, to aggregate generated stub networks.
2487 <tag>interface <M>pattern</M> [instance <m/num/]</tag>
2488 Defines that the specified interfaces belong to the area being defined.
2489 See <ref id="dsc-iface" name="interface"> common option for detailed
2490 description. In OSPFv2, extended interface clauses are used, because
2491 OSPFv2 handles each network prefix as a separate virtual interface. In
2492 OSPFv3, you can specify instance ID for that interface description, so
2493 it is possible to have several instances of that interface with
2494 different options or even in different areas.
2496 <tag>virtual link <M>id</M> [instance <m/num/]</tag>
2497 Virtual link to router with the router id. Virtual link acts as a
2498 point-to-point interface belonging to backbone. The actual area is used
2499 as transport area. This item cannot be in the backbone. In OSPFv3, you
2500 could also use several virtual links to one destination with different
2503 <tag>cost <M>num</M></tag>
2504 Specifies output cost (metric) of an interface. Default value is 10.
2506 <tag>stub <M>switch</M></tag>
2507 If set to interface it does not listen to any packet and does not send
2508 any hello. Default value is no.
2510 <tag>hello <M>num</M></tag>
2511 Specifies interval in seconds between sending of Hello messages. Beware,
2512 all routers on the same network need to have the same hello interval.
2513 Default value is 10.
2515 <tag>poll <M>num</M></tag>
2516 Specifies interval in seconds between sending of Hello messages for some
2517 neighbors on NBMA network. Default value is 20.
2519 <tag>retransmit <M>num</M></tag>
2520 Specifies interval in seconds between retransmissions of unacknowledged
2521 updates. Default value is 5.
2523 <tag>priority <M>num</M></tag>
2524 On every multiple access network (e.g., the Ethernet) Designed Router
2525 and Backup Designed router are elected. These routers have some special
2526 functions in the flooding process. Higher priority increases preferences
2527 in this election. Routers with priority 0 are not eligible. Default
2530 <tag>wait <M>num</M></tag>
2531 After start, router waits for the specified number of seconds between
2532 starting election and building adjacency. Default value is 40.
2534 <tag>dead count <M>num</M></tag>
2535 When the router does not receive any messages from a neighbor in
2536 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
2538 <tag>dead <M>num</M></tag>
2539 When the router does not receive any messages from a neighbor in
2540 <m/dead/ seconds, it will consider the neighbor down. If both directives
2541 <cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precendence.
2543 <tag>secondary <M>switch</M></tag>
2544 On BSD systems, older versions of BIRD supported OSPFv2 only for the
2545 primary IP address of an interface, other IP ranges on the interface
2546 were handled as stub networks. Since v1.4.1, regular operation on
2547 secondary IP addresses is supported, but disabled by default for
2548 compatibility. This option allows to enable it. The option is a
2549 transitional measure, will be removed in the next major release as the
2550 behavior will be changed. On Linux systems, the option is irrelevant, as
2551 operation on non-primary addresses is already the regular behavior.
2553 <tag>rx buffer <M>num</M></tag>
2554 This option allows to specify the size of buffers used for packet
2555 processing. The buffer size should be bigger than maximal size of any
2556 packets. By default, buffers are dynamically resized as needed, but a
2557 fixed value could be specified. Value <cf/large/ means maximal allowed
2558 packet size - 65535.
2560 <tag>tx length <M>num</M></tag>
2561 Transmitted OSPF messages that contain large amount of information are
2562 segmented to separate OSPF packets to avoid IP fragmentation. This
2563 option specifies the soft ceiling for the length of generated OSPF
2564 packets. Default value is the MTU of the network interface. Note that
2565 larger OSPF packets may still be generated if underlying OSPF messages
2566 cannot be splitted (e.g. when one large LSA is propagated).
2568 <tag>type broadcast|bcast</tag>
2569 BIRD detects a type of a connected network automatically, but sometimes
2570 it's convenient to force use of a different type manually. On broadcast
2571 networks (like ethernet), flooding and Hello messages are sent using
2572 multicasts (a single packet for all the neighbors). A designated router
2573 is elected and it is responsible for synchronizing the link-state
2574 databases and originating network LSAs. This network type cannot be used
2575 on physically NBMA networks and on unnumbered networks (networks without
2578 <tag>type pointopoint|ptp</tag>
2579 Point-to-point networks connect just 2 routers together. No election is
2580 performed and no network LSA is originated, which makes it simpler and
2581 faster to establish. This network type is useful not only for physically
2582 PtP ifaces (like PPP or tunnels), but also for broadcast networks used
2583 as PtP links. This network type cannot be used on physically NBMA
2586 <tag>type nonbroadcast|nbma</tag>
2587 On NBMA networks, the packets are sent to each neighbor separately
2588 because of lack of multicast capabilities. Like on broadcast networks,
2589 a designated router is elected, which plays a central role in propagation
2590 of LSAs. This network type cannot be used on unnumbered networks.
2592 <tag>type pointomultipoint|ptmp</tag>
2593 This is another network type designed to handle NBMA networks. In this
2594 case the NBMA network is treated as a collection of PtP links. This is
2595 useful if not every pair of routers on the NBMA network has direct
2596 communication, or if the NBMA network is used as an (possibly
2597 unnumbered) PtP link.
2599 <tag>strict nonbroadcast <M>switch</M></tag>
2600 If set, don't send hello to any undefined neighbor. This switch is
2601 ignored on other than NBMA or PtMP networks. Default value is no.
2603 <tag>real broadcast <m/switch/</tag>
2604 In <cf/type broadcast/ or <cf/type ptp/ network configuration, OSPF
2605 packets are sent as IP multicast packets. This option changes the
2606 behavior to using old-fashioned IP broadcast packets. This may be useful
2607 as a workaround if IP multicast for some reason does not work or does
2608 not work reliably. This is a non-standard option and probably is not
2609 interoperable with other OSPF implementations. Default value is no.
2611 <tag>ptp netmask <m/switch/</tag>
2612 In <cf/type ptp/ network configurations, OSPFv2 implementations should
2613 ignore received netmask field in hello packets and should send hello
2614 packets with zero netmask field on unnumbered PtP links. But some OSPFv2
2615 implementations perform netmask checking even for PtP links. This option
2616 specifies whether real netmask will be used in hello packets on <cf/type
2617 ptp/ interfaces. You should ignore this option unless you meet some
2618 compatibility problems related to this issue. Default value is no for
2619 unnumbered PtP links, yes otherwise.
2621 <tag>check link <M>switch</M></tag>
2622 If set, a hardware link state (reported by OS) is taken into consideration.
2623 When a link disappears (e.g. an ethernet cable is unplugged), neighbors
2624 are immediately considered unreachable and only the address of the iface
2625 (instead of whole network prefix) is propagated. It is possible that
2626 some hardware drivers or platforms do not implement this feature.
2627 Default value is no.
2629 <tag>bfd <M>switch</M></tag>
2630 OSPF could use BFD protocol as an advisory mechanism for neighbor
2631 liveness and failure detection. If enabled, BIRD setups a BFD session
2632 for each OSPF neighbor and tracks its liveness by it. This has an
2633 advantage of an order of magnitude lower detection times in case of
2634 failure. Note that BFD protocol also has to be configured, see
2635 <ref id="sect-bfd" name="BFD"> section for details. Default value is no.
2637 <tag>ttl security [<m/switch/ | tx only]</tag>
2638 TTL security is a feature that protects routing protocols from remote
2639 spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
2640 destined to neighbors. Because TTL is decremented when packets are
2641 forwarded, it is non-trivial to spoof packets with TTL 255 from remote
2642 locations. Note that this option would interfere with OSPF virtual
2645 If this option is enabled, the router will send OSPF packets with TTL
2646 255 and drop received packets with TTL less than 255. If this option si
2647 set to <cf/tx only/, TTL 255 is used for sent packets, but is not
2648 checked for received packets. Default value is no.
2650 <tag>tx class|dscp|priority <m/num/</tag>
2651 These options specify the ToS/DiffServ/Traffic class/Priority of the
2652 outgoing OSPF packets. See <ref id="dsc-prio" name="tx class"> common
2653 option for detailed description.
2655 <tag>ecmp weight <M>num</M></tag>
2656 When ECMP (multipath) routes are allowed, this value specifies a
2657 relative weight used for nexthops going through the iface. Allowed
2658 values are 1-256. Default value is 1.
2660 <tag>authentication none</tag>
2661 No passwords are sent in OSPF packets. This is the default value.
2663 <tag>authentication simple</tag>
2664 Every packet carries 8 bytes of password. Received packets lacking this
2665 password are ignored. This authentication mechanism is very weak.
2667 <tag>authentication cryptographic</tag>
2668 16-byte long MD5 digest is appended to every packet. For the digest
2669 generation 16-byte long passwords are used. Those passwords are not sent
2670 via network, so this mechanism is quite secure. Packets can still be
2671 read by an attacker.
2673 <tag>password "<M>text</M>"</tag>
2674 An 8-byte or 16-byte password used for authentication. See
2675 <ref id="dsc-pass" name="password"> common option for detailed
2678 <tag>neighbors { <m/set/ } </tag>
2679 A set of neighbors to which Hello messages on NBMA or PtMP networks are
2680 to be sent. For NBMA networks, some of them could be marked as eligible.
2681 In OSPFv3, link-local addresses should be used, using global ones is
2682 possible, but it is nonstandard and might be problematic. And definitely,
2683 link-local and global addresses should not be mixed.
2688 <p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
2690 <p>Metric is ranging from 1 to infinity (65535). External routes use
2691 <cf/metric type 1/ or <cf/metric type 2/. A <cf/metric of type 1/ is comparable
2692 with internal <cf/metric/, a <cf/metric of type 2/ is always longer than any
2693 <cf/metric of type 1/ or any <cf/internal metric/. <cf/Internal metric/ or
2694 <cf/metric of type 1/ is stored in attribute <cf/ospf_metric1/, <cf/metric type
2695 2/ is stored in attribute <cf/ospf_metric2/. If you specify both metrics only
2698 <p>Each external route can also carry attribute <cf/ospf_tag/ which is a 32-bit
2699 integer which is used when exporting routes to other protocols; otherwise, it
2700 doesn't affect routing inside the OSPF domain at all. The fourth attribute
2701 <cf/ospf_router_id/ is a router ID of the router advertising that route /
2702 network. This attribute is read-only. Default is <cf/ospf_metric2 = 10000/ and
2708 protocol ospf MyOSPF {
2712 if source = RTS_BGP then {
2724 authentication simple;
2729 authentication cryptographic;
2732 generate to "22-04-2003 11:00:06";
2733 accept from "17-01-2001 12:01:05";
2737 generate to "22-07-2005 17:03:21";
2738 accept from "22-02-2001 11:34:06";
2751 172.16.2.0/24 hidden;
2753 interface "-arc0" , "arc*" {
2755 authentication none;
2756 strict nonbroadcast yes;
2761 192.168.120.1 eligible;
2775 <p>The Pipe protocol serves as a link between two routing tables, allowing
2776 routes to be passed from a table declared as primary (i.e., the one the pipe is
2777 connected to using the <cf/table/ configuration keyword) to the secondary one
2778 (declared using <cf/peer table/) and vice versa, depending on what's allowed by
2779 the filters. Export filters control export of routes from the primary table to
2780 the secondary one, import filters control the opposite direction.
2782 <p>The Pipe protocol may work in the transparent mode mode or in the opaque
2783 mode. In the transparent mode, the Pipe protocol retransmits all routes from
2784 one table to the other table, retaining their original source and attributes.
2785 If import and export filters are set to accept, then both tables would have
2786 the same content. The transparent mode is the default mode.
2788 <p>In the opaque mode, the Pipe protocol retransmits optimal route from one
2789 table to the other table in a similar way like other protocols send and receive
2790 routes. Retransmitted route will have the source set to the Pipe protocol, which
2791 may limit access to protocol specific route attributes. This mode is mainly for
2792 compatibility, it is not suggested for new configs. The mode can be changed by
2795 <p>The primary use of multiple routing tables and the Pipe protocol is for
2796 policy routing, where handling of a single packet doesn't depend only on its
2797 destination address, but also on its source address, source interface, protocol
2798 type and other similar parameters. In many systems (Linux being a good example),
2799 the kernel allows to enforce routing policies by defining routing rules which
2800 choose one of several routing tables to be used for a packet according to its
2801 parameters. Setting of these rules is outside the scope of BIRD's work (on
2802 Linux, you can use the <tt/ip/ command), but you can create several routing
2803 tables in BIRD, connect them to the kernel ones, use filters to control which
2804 routes appear in which tables and also you can employ the Pipe protocol for
2805 exporting a selected subset of one table to another one.
2807 <sect1>Configuration
2810 <tag>peer table <m/table/</tag>
2811 Defines secondary routing table to connect to. The primary one is
2812 selected by the <cf/table/ keyword.
2814 <tag>mode opaque|transparent</tag>
2815 Specifies the mode for the pipe to work in. Default is transparent.
2820 <p>The Pipe protocol doesn't define any route attributes.
2824 <p>Let's consider a router which serves as a boundary router of two different
2825 autonomous systems, each of them connected to a subset of interfaces of the
2826 router, having its own exterior connectivity and wishing to use the other AS as
2827 a backup connectivity in case of outage of its own exterior line.
2829 <p>Probably the simplest solution to this situation is to use two routing tables
2830 (we'll call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that
2831 packets having arrived from interfaces belonging to the first AS will be routed
2832 according to <cf/as1/ and similarly for the second AS. Thus we have split our
2833 router to two logical routers, each one acting on its own routing table, having
2834 its own routing protocols on its own interfaces. In order to use the other AS's
2835 routes for backup purposes, we can pass the routes between the tables through a
2836 Pipe protocol while decreasing their preferences and correcting their BGP paths
2837 to reflect the AS boundary crossing.
2840 table as1; # Define the tables
2843 protocol kernel kern1 { # Synchronize them with the kernel
2848 protocol kernel kern2 {
2853 protocol bgp bgp1 { # The outside connections
2856 neighbor 192.168.0.1 as 1001;
2864 neighbor 10.0.0.1 as 1002;
2869 protocol pipe { # The Pipe
2873 if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks
2874 if preference>10 then preference = preference-10;
2875 if source=RTS_BGP then bgp_path.prepend(1);
2881 if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks
2882 if preference>10 then preference = preference-10;
2883 if source=RTS_BGP then bgp_path.prepend(2);
2896 <p>The RAdv protocol is an implementation of Router Advertisements, which are
2897 used in the IPv6 stateless autoconfiguration. IPv6 routers send (in irregular
2898 time intervals or as an answer to a request) advertisement packets to connected
2899 networks. These packets contain basic information about a local network (e.g. a
2900 list of network prefixes), which allows network hosts to autoconfigure network
2901 addresses and choose a default route. BIRD implements router behavior as defined
2902 in RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">
2903 and also the DNS extensions from
2904 RFC 6106<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt">.
2906 <sect1>Configuration
2908 <p>There are several classes of definitions in RAdv configuration -- interface
2909 definitions, prefix definitions and DNS definitions:
2912 <tag>interface <m/pattern [, ...]/ { <m/options/ }</tag>
2913 Interface definitions specify a set of interfaces on which the
2914 protocol is activated and contain interface specific options.
2915 See <ref id="dsc-iface" name="interface"> common options for
2916 detailed description.
2918 <tag>prefix <m/prefix/ { <m/options/ }</tag>
2919 Prefix definitions allow to modify a list of advertised prefixes. By
2920 default, the advertised prefixes are the same as the network prefixes
2921 assigned to the interface. For each network prefix, the matching prefix
2922 definition is found and its options are used. If no matching prefix
2923 definition is found, the prefix is used with default options.
2925 Prefix definitions can be either global or interface-specific. The
2926 second ones are part of interface options. The prefix definition
2927 matching is done in the first-match style, when interface-specific
2928 definitions are processed before global definitions. As expected, the
2929 prefix definition is matching if the network prefix is a subnet of the
2930 prefix in prefix definition.
2932 <tag>rdnss { <m/options/ }</tag>
2933 RDNSS definitions allow to specify a list of advertised recursive DNS
2934 servers together with their options. As options are seldom necessary,
2935 there is also a short variant <cf>rdnss <m/address/</cf> that just
2936 specifies one DNS server. Multiple definitions are cumulative. RDNSS
2937 definitions may also be interface-specific when used inside interface
2938 options. By default, interface uses both global and interface-specific
2939 options, but that can be changed by <cf/rdnss local/ option.
2941 <tag>dnssl { <m/options/ }</tag>
2942 DNSSL definitions allow to specify a list of advertised DNS search
2943 domains together with their options. Like <cf/rdnss/ above, multiple
2944 definitions are cumulative, they can be used also as interface-specific
2945 options and there is a short variant <cf>dnssl <m/domain/</cf> that just
2946 specifies one DNS search domain.
2948 <label id="dsc-trigger"> <tag>trigger <m/prefix/</tag>
2949 RAdv protocol could be configured to change its behavior based on
2950 availability of routes. When this option is used, the protocol waits in
2951 suppressed state until a <it/trigger route/ (for the specified network)
2952 is exported to the protocol, the protocol also returnsd to suppressed
2953 state if the <it/trigger route/ disappears. Note that route export
2954 depends on specified export filter, as usual. This option could be used,
2955 e.g., for handling failover in multihoming scenarios.
2957 During suppressed state, router advertisements are generated, but with
2958 some fields zeroed. Exact behavior depends on which fields are zeroed,
2959 this can be configured by <cf/sensitive/ option for appropriate
2960 fields. By default, just <cf/default lifetime/ (also called <cf/router
2961 lifetime/) is zeroed, which means hosts cannot use the router as a
2962 default router. <cf/preferred lifetime/ and <cf/valid lifetime/ could
2963 also be configured as <cf/sensitive/ for a prefix, which would cause
2964 autoconfigured IPs to be deprecated or even removed.
2967 <p>Interface specific options:
2970 <tag>max ra interval <m/expr/</tag>
2971 Unsolicited router advertisements are sent in irregular time intervals.
2972 This option specifies the maximum length of these intervals, in seconds.
2973 Valid values are 4-1800. Default: 600
2975 <tag>min ra interval <m/expr/</tag>
2976 This option specifies the minimum length of that intervals, in seconds.
2977 Must be at least 3 and at most 3/4 * <cf/max ra interval/. Default:
2978 about 1/3 * <cf/max ra interval/.
2980 <tag>min delay <m/expr/</tag>
2981 The minimum delay between two consecutive router advertisements, in
2984 <tag>managed <m/switch/</tag>
2985 This option specifies whether hosts should use DHCPv6 for IP address
2986 configuration. Default: no
2988 <tag>other config <m/switch/</tag>
2989 This option specifies whether hosts should use DHCPv6 to receive other
2990 configuration information. Default: no
2992 <tag>link mtu <m/expr/</tag>
2993 This option specifies which value of MTU should be used by hosts. 0
2994 means unspecified. Default: 0
2996 <tag>reachable time <m/expr/</tag>
2997 This option specifies the time (in milliseconds) how long hosts should
2998 assume a neighbor is reachable (from the last confirmation). Maximum is
2999 3600000, 0 means unspecified. Default 0.
3001 <tag>retrans timer <m/expr/</tag>
3002 This option specifies the time (in milliseconds) how long hosts should
3003 wait before retransmitting Neighbor Solicitation messages. 0 means
3004 unspecified. Default 0.
3006 <tag>current hop limit <m/expr/</tag>
3007 This option specifies which value of Hop Limit should be used by
3008 hosts. Valid values are 0-255, 0 means unspecified. Default: 64
3010 <tag>default lifetime <m/expr/ [sensitive <m/switch/]</tag>
3011 This option specifies the time (in seconds) how long (after the receipt
3012 of RA) hosts may use the router as a default router. 0 means do not use
3013 as a default router. For <cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">.
3014 Default: 3 * <cf/max ra interval/, <cf/sensitive/ yes.
3016 <tag>rdnss local <m/switch/</tag>
3017 Use only local (interface-specific) RDNSS definitions for this
3018 interface. Otherwise, both global and local definitions are used. Could
3019 also be used to disable RDNSS for given interface if no local definitons
3020 are specified. Default: no.
3022 <tag>dnssl local <m/switch/</tag>
3023 Use only local DNSSL definitions for this interface. See <cf/rdnss local/
3024 option above. Default: no.
3028 <p>Prefix specific options:
3031 <tag>skip <m/switch/</tag>
3032 This option allows to specify that given prefix should not be
3033 advertised. This is useful for making exceptions from a default policy
3034 of advertising all prefixes. Note that for withdrawing an already
3035 advertised prefix it is more useful to advertise it with zero valid
3036 lifetime. Default: no
3038 <tag>onlink <m/switch/</tag>
3039 This option specifies whether hosts may use the advertised prefix for
3040 onlink determination. Default: yes
3042 <tag>autonomous <m/switch/</tag>
3043 This option specifies whether hosts may use the advertised prefix for
3044 stateless autoconfiguration. Default: yes
3046 <tag>valid lifetime <m/expr/ [sensitive <m/switch/]</tag>
3047 This option specifies the time (in seconds) how long (after the
3048 receipt of RA) the prefix information is valid, i.e., autoconfigured
3049 IP addresses can be assigned and hosts with that IP addresses are
3050 considered directly reachable. 0 means the prefix is no longer
3051 valid. For <cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">.
3052 Default: 86400 (1 day), <cf/sensitive/ no.
3054 <tag>preferred lifetime <m/expr/ [sensitive <m/switch/]</tag>
3055 This option specifies the time (in seconds) how long (after the
3056 receipt of RA) IP addresses generated from the prefix using stateless
3057 autoconfiguration remain preferred. For <cf/sensitive/ option,
3058 see <ref id="dsc-trigger" name="trigger">. Default: 14400 (4 hours),
3063 <p>RDNSS specific options:
3066 <tag>ns <m/address/</tag>
3067 This option specifies one recursive DNS server. Can be used multiple
3068 times for multiple servers. It is mandatory to have at least one
3069 <cf/ns/ option in <cf/rdnss/ definition.
3071 <tag>lifetime [mult] <m/expr/</tag>
3072 This option specifies the time how long the RDNSS information may be
3073 used by clients after the receipt of RA. It is expressed either in
3074 seconds or (when <cf/mult/ is used) in multiples of <cf/max ra
3075 interval/. Note that RDNSS information is also invalidated when
3076 <cf/default lifetime/ expires. 0 means these addresses are no longer
3077 valid DNS servers. Default: 3 * <cf/max ra interval/.
3081 <p>DNSSL specific options:
3084 <tag>domain <m/address/</tag>
3085 This option specifies one DNS search domain. Can be used multiple times
3086 for multiple domains. It is mandatory to have at least one <cf/domain/
3087 option in <cf/dnssl/ definition.
3089 <tag>lifetime [mult] <m/expr/</tag>
3090 This option specifies the time how long the DNSSL information may be
3091 used by clients after the receipt of RA. Details are the same as for
3092 RDNSS <cf/lifetime/ option above. Default: 3 * <cf/max ra interval/.
3101 max ra interval 5; # Fast failover with more routers
3102 managed yes; # Using DHCPv6 on eth2
3104 autonomous off; # So do not autoconfigure any IP
3108 interface "eth*"; # No need for any other options
3110 prefix 2001:0DB8:1234::/48 {
3111 preferred lifetime 0; # Deprecated address range
3114 prefix 2001:0DB8:2000::/48 {
3115 autonomous off; # Do not autoconfigure
3118 rdnss 2001:0DB8:1234::10; # Short form of RDNSS
3122 ns 2001:0DB8:1234::11;
3123 ns 2001:0DB8:1234::12;
3139 <p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol,
3140 where each router broadcasts (to all its neighbors) distances to all networks it
3141 can reach. When a router hears distance to another network, it increments it and
3142 broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some
3143 network goes unreachable, routers keep telling each other that its distance is
3144 the original distance plus 1 (actually, plus interface metric, which is usually
3145 one). After some time, the distance reaches infinity (that's 15 in RIP) and all
3146 routers know that network is unreachable. RIP tries to minimize situations where
3147 counting to infinity is necessary, because it is slow. Due to infinity being 16,
3148 you can't use RIP on networks where maximal distance is higher than 15
3149 hosts. You can read more about RIP at
3150 <HTMLURL URL="http://www.ietf.org/html.charters/rip-charter.html"
3151 name="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4
3152 (RFC 1723 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1723.txt">) and IPv6
3153 (RFC 2080 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2080.txt">) versions
3154 of RIP are supported by BIRD, historical RIPv1
3155 (RFC 1058 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1058.txt">) is not
3156 currently supported. RIPv4 MD5 authentication
3157 (RFC 2082 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2082.txt">) is
3160 <p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow
3161 convergence, big network load and inability to handle larger networks makes it
3162 pretty much obsolete. It is still usable on very small networks.
3164 <sect1>Configuration
3166 <p>In addition to options common for all to other protocols, RIP supports the
3170 <tag>authentication none|plaintext|md5</tag>
3171 Selects authentication method to be used. <cf/none/ means that packets
3172 are not authenticated at all, <cf/plaintext/ means that a plaintext
3173 password is embedded into each packet, and <cf/md5/ means that packets
3174 are authenticated using a MD5 cryptographic hash. If you set
3175 authentication to not-none, it is a good idea to add <cf>password</cf>
3176 section. Default: none.
3178 <tag>honor always|neighbor|never</tag>
3179 Specifies when should requests for dumping routing table be honored.
3180 (Always, when sent from a host on a directly connected network or
3181 never.) Routing table updates are honored only from neighbors, that is
3182 not configurable. Default: never.
3185 <p>There are some options that can be specified per-interface:
3188 <tag>metric <m/num/</tag>
3189 This option specifies the metric of the interface. Valid
3191 <tag>mode multicast|broadcast|quiet|nolisten|version1</tag>
3192 This option selects the mode for RIP to use on the interface. If nothing
3193 is specified, RIP runs in multicast mode. <cf/version1/ is currently
3194 equivalent to <cf/broadcast/, and it makes RIP talk to a broadcast
3195 address even through multicast mode is possible. <cf/quiet/ option means
3196 that RIP will not transmit any periodic messages to this interface and
3197 <cf/nolisten/ means that RIP will send to this interface butnot listen
3200 <tag>ttl security [<m/switch/ | tx only]</tag>
3201 TTL security is a feature that protects routing protocols from remote
3202 spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
3203 destined to neighbors. Because TTL is decremented when packets are
3204 forwarded, it is non-trivial to spoof packets with TTL 255 from remote
3207 If this option is enabled, the router will send RIP packets with TTL 255
3208 and drop received packets with TTL less than 255. If this option si set
3209 to <cf/tx only/, TTL 255 is used for sent packets, but is not checked
3210 for received packets. Such setting does not offer protection, but offers
3211 compatibility with neighbors regardless of whether they use ttl
3214 Note that for RIPng, TTL security is a standard behavior (required by
3215 RFC 2080), but BIRD uses <cf/tx only/ by default, for compatibility with
3216 older versions. For IPv4 RIP, default value is no.
3218 <tag>tx class|dscp|priority <m/num/</tag>
3219 These options specify the ToS/DiffServ/Traffic class/Priority of the
3220 outgoing RIP packets. See <ref id="dsc-prio" name="tx class"> common
3221 option for detailed description.
3224 <p>The following options generally override behavior specified in RFC. If you
3225 use any of these options, BIRD will no longer be RFC-compliant, which means it
3226 will not be able to talk to anything other than equally configured BIRD. I have
3230 <tag>port <M>number</M></tag>
3231 Selects IP port to operate on, default 520. (This is useful when testing
3232 BIRD, if you set this to an address >1024, you will not need to run
3235 <tag>infinity <M>number</M></tag>
3236 Selects the value of infinity, default is 16. Bigger values will make
3237 protocol convergence even slower.
3239 <tag>period <M>number</M></tag>
3240 Specifies the number of seconds between periodic updates. Default is 30
3241 seconds. A lower number will mean faster convergence but bigger network
3242 load. Do not use values lower than 12.
3244 <tag>timeout time <M>number</M></tag>
3245 Specifies how old route has to be to be considered unreachable.
3246 Default is 4*<cf/period/.
3248 <tag>garbage time <M>number</M></tag>
3249 Specifies how old route has to be to be discarded. Default is
3255 <p>RIP defines two route attributes:
3258 <tag>int <cf/rip_metric/</tag>
3259 RIP metric of the route (ranging from 0 to <cf/infinity/). When routes
3260 from different RIP instances are available and all of them have the same
3261 preference, BIRD prefers the route with lowest <cf/rip_metric/. When
3262 importing a non-RIP route, the metric defaults to 5.
3264 <tag>int <cf/rip_tag/</tag>
3265 RIP route tag: a 16-bit number which can be used to carry additional
3266 information with the route (for example, an originating AS number in
3267 case of external routes). When importing a non-RIP route, the tag
3274 protocol rip MyRIP_test {
3279 interface "eth0" { metric 3; mode multicast; };
3280 interface "eth*" { metric 2; mode broadcast; };
3282 authentication none;
3283 import filter { print "importing"; accept; };
3284 export filter { print "exporting"; accept; };
3291 <p>The Static protocol doesn't communicate with other routers in the network,
3292 but instead it allows you to define routes manually. This is often used for
3293 specifying how to forward packets to parts of the network which don't use
3294 dynamic routing at all and also for defining sink routes (i.e., those telling to
3295 return packets as undeliverable if they are in your IP block, you don't have any
3296 specific destination for them and you don't want to send them out through the
3297 default route to prevent routing loops).
3299 <p>There are five types of static routes: `classical' routes telling to forward
3300 packets to a neighboring router, multipath routes specifying several (possibly
3301 weighted) neighboring routers, device routes specifying forwarding to hosts on a
3302 directly connected network, recursive routes computing their nexthops by doing
3303 route table lookups for a given IP and special routes (sink, blackhole etc.)
3304 which specify a special action to be done instead of forwarding the packet.
3306 <p>When the particular destination is not available (the interface is down or
3307 the next hop of the route is not a neighbor at the moment), Static just
3308 uninstalls the route from the table it is connected to and adds it again as soon
3309 as the destination becomes adjacent again.
3311 <p>The Static protocol does not have many configuration options. The definition
3312 of the protocol contains mainly a list of static routes:
3315 <tag>route <m/prefix/ via <m/ip/</tag>
3316 Static route through a neighboring router.
3318 <tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [via ...]</tag>
3319 Static multipath route. Contains several nexthops (gateways), possibly
3322 <tag>route <m/prefix/ via <m/"interface"/</tag>
3323 Static device route through an interface to hosts on a directly
3326 <tag>route <m/prefix/ recursive <m/ip/</tag>
3327 Static recursive route, its nexthop depends on a route table lookup for
3330 <tag>route <m/prefix/ blackhole|unreachable|prohibit</tag>
3331 Special routes specifying to silently drop the packet, return it as
3332 unreachable or return it as administratively prohibited. First two
3333 targets are also known as <cf/drop/ and <cf/reject/.
3335 <tag>check link <m/switch/</tag>
3336 If set, hardware link states of network interfaces are taken into
3337 consideration. When link disappears (e.g. ethernet cable is unplugged),
3338 static routes directing to that interface are removed. It is possible
3339 that some hardware drivers or platforms do not implement this feature.
3342 <tag>igp table <m/name/</tag>
3343 Specifies a table that is used for route table lookups of recursive
3344 routes. Default: the same table as the protocol is connected to.
3347 <p>Static routes have no specific attributes.
3349 <p>Example static config might look like this:
3353 table testable; # Connect to a non-default routing table
3354 route 0.0.0.0/0 via 198.51.100.130; # Default route
3355 route 10.0.0.0/8 multipath # Multipath route
3356 via 198.51.100.10 weight 2
3359 route 203.0.113.0/24 unreachable; # Sink route
3360 route 10.2.0.0/24 via "arc0"; # Secondary network
3369 <p>Although BIRD supports all the commonly used routing protocols, there are
3370 still some features which would surely deserve to be implemented in future
3375 <item>Route aggregation and flap dampening
3376 <item>Multipath routes
3377 <item>Multicast routing protocols
3378 <item>Ports to other systems
3382 <sect>Getting more help
3384 <p>If you use BIRD, you're welcome to join the bird-users mailing list
3385 (<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
3386 where you can share your experiences with the other users and consult
3387 your problems with the authors. To subscribe to the list, just send a
3388 <tt/subscribe bird-users/ command in a body of a mail to
3389 (<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
3390 The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
3392 <p>BIRD is a relatively young system and it probably contains some bugs. You can
3393 report any problems to the bird-users list and the authors will be glad to solve
3394 them, but before you do so, please make sure you have read the available
3395 documentation and that you are running the latest version (available at
3396 <HTMLURL URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">).
3397 (Of course, a patch which fixes the bug is always welcome as an attachment.)
3399 <p>If you want to understand what is going inside, Internet standards are a good
3400 and interesting reading. You can get them from
3401 <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a
3402 nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc"
3403 name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
3410 LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
3411 LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps
3412 LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC
3413 LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth
3414 LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek
3415 LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC
3416 LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU
3417 LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc
3418 LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats
3419 LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt
3420 LocalWords: proto wildcard Ondrej Filip