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 look for a configuration file and a communication socket in the current
176 working directory instead of in default system locations. However, paths
177 specified by options <cf/-c/, <cf/-s/ have higher priority.
180 apply graceful restart recovery after start.
183 <p>BIRD writes messages about its work to log files or syslog (according to config).
188 <p>BIRD, as a routing daemon, uses several privileged operations (like setting
189 routing table and using raw sockets). Traditionally, BIRD is executed and runs
190 with root privileges, which may be prone to security problems. The recommended
191 way is to use a privilege restriction (options <cf/-u/, <cf/-g/). In that case
192 BIRD is executed with root privileges, but it changes its user and group ID to
193 an unprivileged ones, while using Linux capabilities to retain just required
194 privileges (capabilities CAP_NET_*). Note that the control socket is created
195 before the privileges are dropped, but the config file is read after that. The
196 privilege restriction is not implemented in BSD port of BIRD.
198 <p>An unprivileged user (as an argument to <cf/-u/ options) may be the user
199 <cf/nobody/, but it is suggested to use a new dedicated user account (like
200 <cf/bird/). The similar considerations apply for the group option, but there is
201 one more condition -- the users in the same group can use <file/birdc/ to
204 <p>Finally, there is a possibility to use external tools to run BIRD in an
205 environment with restricted privileges. This may need some configuration, but it
206 is generally easy -- BIRD needs just the standard library, privileges to read
207 the config file and create the control socket and the CAP_NET_* capabilities.
210 <chapt>About routing tables
212 <p>BIRD has one or more routing tables which may or may not be synchronized with
213 OS kernel and which may or may not be synchronized with each other (see the Pipe
214 protocol). Each routing table contains a list of known routes. Each route
218 <item>network prefix this route is for (network address and prefix
219 length -- the number of bits forming the network part of the
220 address; also known as a netmask)
221 <item>preference of this route
222 <item>IP address of router which told us about this route
223 <item>IP address of router we should forward the packets to using this
225 <item>other attributes common to all routes
226 <item>dynamic attributes defined by protocols which may or may not be
227 present (typically protocol metrics)
230 Routing table maintains multiple entries for a network, but at most one entry
231 for one network and one protocol. The entry with the highest preference is used
232 for routing (we will call such an entry the <it/selected route/). If there are
233 more entries with the same preference and they are from the same protocol, the
234 protocol decides (typically according to metrics). If they aren't, an internal
235 ordering is used to break the tie. You can get the list of route attributes in
236 the Route attributes section.
238 <p>Each protocol is connected to a routing table through two filters which can
239 accept, reject and modify the routes. An <it/export/ filter checks routes passed
240 from the routing table to the protocol, an <it/import/ filter checks routes in
241 the opposite direction. When the routing table gets a route from a protocol, it
242 recalculates the selected route and broadcasts it to all protocols connected to
243 the table. The protocols typically send the update to other routers in the
244 network. Note that although most protocols are interested in receiving just
245 selected routes, some protocols (e.g. the <cf/Pipe/ protocol) receive and
246 process all entries in routing tables (accepted by filters).
248 <p><label id="dsc-sorted">Usually, a routing table just chooses a selected route
249 from a list of entries for one network. But if the <cf/sorted/ option is
250 activated, these lists of entries are kept completely sorted (according to
251 preference or some protocol-dependent metric). This is needed for some features
252 of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to
253 accept not just a selected route, but the first route (in the sorted list) that
254 is accepted by filters), but it is incompatible with some other features (e.g.
255 <cf/deterministic med/ option of BGP protocol, which activates a way of choosing
256 selected route that cannot be described using comparison and ordering). Minor
257 advantage is that routes are shown sorted in <cf/show route/, minor disadvantage
258 is that it is slightly more computationally expensive.
261 <sect>Graceful restart
263 <p>When BIRD is started after restart or crash, it repopulates routing tables in
264 an uncoordinated manner, like after clean start. This may be impractical in some
265 cases, because if the forwarding plane (i.e. kernel routing tables) remains
266 intact, then its synchronization with BIRD would temporarily disrupt packet
267 forwarding until protocols converge. Graceful restart is a mechanism that could
268 help with this issue. Generally, it works by starting protocols and letting them
269 repopulate routing tables while deferring route propagation until protocols
270 acknowledge their convergence. Note that graceful restart behavior have to be
271 configured for all relevant protocols and requires protocol-specific support
272 (currently implemented for Kernel and BGP protocols), it is activated for
273 particular boot by option <cf/-R/.
280 <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads
281 <it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option
282 is given). Configuration may be changed at user's request: if you modify the
283 config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new
284 config. Then there's the client which allows you to talk with BIRD in an
287 <p>In the config, everything on a line after <cf/#/ or inside <cf>/* */</cf> is
288 a comment, whitespace characters are treated as a single space. If there's a
289 variable number of options, they are grouped using the <cf/{ }/ brackets. Each
290 option is terminated by a <cf/;/. Configuration is case sensitive. There are two
291 ways how to name symbols (like protocol names, filter names, constants etc.). You
292 can either use a simple string starting with a letter followed by any
293 combination of letters and numbers (e.g. "R123", "myfilter", "bgp5") or you can
294 enclose the name into apostrophes (<cf/'/) and than you can use any combination
295 of numbers, letters. hyphens, dots and colons (e.g. "'1:strange-name'",
296 "'-NAME-'", "'cool::name'").
298 <p>Here is an example of a simple config file. It enables synchronization of
299 routing tables with OS kernel, scans for new network interfaces every 10 seconds
300 and runs RIP on all network interfaces found.
304 persist; # Don't remove routes on BIRD shutdown
305 scan time 20; # Scan kernel routing table every 20 seconds
306 export all; # Default is export none
310 scan time 10; # Scan interfaces every 10 seconds
324 <tag>include "<m/filename/"</tag>
325 This statement causes inclusion of a new file. <m/Filename/ could also
326 be a wildcard, in that case matching files are included in alphabetic
327 order. The maximal depth is 8. Note that this statement could be used
328 anywhere in the config file, not just as a top-level option.
330 <tag><label id="dsc-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag>
331 Set logging of messages having the given class (either <cf/all/ or
332 <cf/{ error, trace }/ etc.) into selected destination (a file specified
333 as a filename string, syslog with optional name argument, or the stderr
334 output). Classes are:
335 <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
336 <cf/debug/ for debugging messages,
337 <cf/trace/ when you want to know what happens in the network,
338 <cf/remote/ for messages about misbehavior of remote machines,
339 <cf/auth/ about authentication failures,
340 <cf/bug/ for internal BIRD bugs.
341 You may specify more than one <cf/log/ line to establish logging to
342 multiple destinations. Default: log everything to the system log.
344 <tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
345 Set global defaults of protocol debugging options. See <cf/debug/ in the
346 following section. Default: off.
348 <tag>debug commands <m/number/</tag>
349 Control logging of client connections (0 for no logging, 1 for logging
350 of connects and disconnects, 2 and higher for logging of all client
351 commands). Default: 0.
353 <tag>debug latency <m/switch/</tag>
354 Activate tracking of elapsed time for internal events. Recent events
355 could be examined using <cf/dump events/ command. Default: off.
357 <tag>debug latency limit <m/time/</tag>
358 If <cf/debug latency/ is enabled, this option allows to specify a limit
359 for elapsed time. Events exceeding the limit are logged. Default: 1 s.
361 <tag>watchdog warning <m/time/</tag>
362 Set time limit for I/O loop cycle. If one iteration took more time to
363 complete, a warning is logged. Default: 5 s.
365 <tag>watchdog timeout <m/time/</tag>
366 Set time limit for I/O loop cycle. If the limit is breached, BIRD is
367 killed by abort signal. The timeout has effective granularity of
368 seconds, zero means disabled. Default: disabled (0).
370 <tag>mrtdump "<m/filename/"</tag>
371 Set MRTdump file name. This option must be specified to allow MRTdump
372 feature. Default: no dump file.
374 <tag>mrtdump protocols all|off|{ states, messages }</tag>
375 Set global defaults of MRTdump options. See <cf/mrtdump/ in the
376 following section. Default: off.
378 <tag>filter <m/name local variables/{ <m/commands/ }</tag>
379 Define a filter. You can learn more about filters in the following
382 <tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag>
383 Define a function. You can learn more about functions in the following chapter.
385 <tag>protocol rip|ospf|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
386 Define a protocol instance called <cf><m/name/</cf> (or with a name like
387 "rip5" generated automatically if you don't specify any
388 <cf><m/name/</cf>). You can learn more about configuring protocols in
389 their own chapters. When <cf>from <m/name2/</cf> expression is used,
390 initial protocol options are taken from protocol or template
391 <cf><m/name2/</cf> You can run more than one instance of most protocols
392 (like RIP or BGP). By default, no instances are configured.
394 <tag>template rip|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
395 Define a protocol template instance called <m/name/ (or with a name like
396 "bgp1" generated automatically if you don't specify any <m/name/).
397 Protocol templates can be used to group common options when many
398 similarly configured protocol instances are to be defined. Protocol
399 instances (and other templates) can use templates by using <cf/from/
400 expression and the name of the template. At the moment templates (and
401 <cf/from/ expression) are not implemented for OSPF protocol.
403 <tag>define <m/constant/ = <m/expression/</tag>
404 Define a constant. You can use it later in every place you could use a
405 value of the same type. Besides, there are some predefined numeric
406 constants based on /etc/iproute2/rt_* files. A list of defined constants
407 can be seen (together with other symbols) using 'show symbols' command.
409 <tag>router id <m/IPv4 address/</tag>
410 Set BIRD's router ID. It's a world-wide unique identification of your
411 router, usually one of router's IPv4 addresses. Default: in IPv4
412 version, the lowest IP address of a non-loopback interface. In IPv6
413 version, this option is mandatory.
415 <tag>router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...]</tag>
416 Set BIRD's router ID based on an IP address of an interface specified by
417 an interface pattern. The option is applicable for IPv4 version only.
418 See <ref id="dsc-iface" name="interface"> section for detailed
419 description of interface patterns with extended clauses.
421 <tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
422 This option allows to specify address and port where BGP protocol should
423 listen. It is global option as listening socket is common to all BGP
424 instances. Default is to listen on all addresses (0.0.0.0) and port 179.
425 In IPv6 mode, option <cf/dual/ can be used to specify that BGP socket
426 should accept both IPv4 and IPv6 connections (but even in that case,
427 BIRD would accept IPv6 routes only). Such behavior was default in older
430 <tag>graceful restart wait <m/number/</tag>
431 During graceful restart recovery, BIRD waits for convergence of routing
432 protocols. This option allows to specify a timeout for the recovery to
433 prevent waiting indefinitely if some protocols cannot converge. Default:
436 <tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
437 This option allows to specify a format of date/time used by BIRD. The
438 first argument specifies for which purpose such format is used.
439 <cf/route/ is a format used in 'show route' command output,
440 <cf/protocol/ is used in 'show protocols' command output, <cf/base/ is
441 used for other commands and <cf/log/ is used in a log file.
443 "<m/format1/" is a format string using <it/strftime(3)/ notation (see
444 <it/man strftime/ for details). <m/limit> and "<m/format2/" allow to
445 specify the second format string for times in past deeper than <m/limit/
446 seconds. There are few shorthands: <cf/iso long/ is a ISO 8601 date/time
447 format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F %T"/.
448 <cf/iso short/ is a variant of ISO 8601 that uses just the time format
449 (hh:mm:ss) for near times (up to 20 hours in the past) and the date
450 format (YYYY-MM-DD) for far times. This is a shorthand for
451 <cf/"%T" 72000 "%F"/.
453 By default, BIRD uses the <cf/iso short/ format for <cf/route/ and
454 <cf/protocol/ times, and the <cf/iso long/ format for <cf/base/ and
457 In pre-1.4.0 versions, BIRD used an short, ad-hoc format for <cf/route/
458 and <cf/protocol/ times, and a <cf/iso long/ similar format (DD-MM-YYYY
459 hh:mm:ss) for <cf/base/ and <cf/log/. These timeformats could be set by
460 <cf/old short/ and <cf/old long/ compatibility shorthands.
462 <tag>table <m/name/ [sorted]</tag>
463 Create a new routing table. The default routing table is created
464 implicitly, other routing tables have to be added by this command.
465 Option <cf/sorted/ can be used to enable sorting of routes, see
466 <ref id="dsc-sorted" name="sorted table"> description for details.
468 <tag>roa table <m/name/ [ { roa table options ... } ]</tag>
469 Create a new ROA (Route Origin Authorization) table. ROA tables can be
470 used to validate route origination of BGP routes. A ROA table contains
471 ROA entries, each consist of a network prefix, a max prefix length and
472 an AS number. A ROA entry specifies prefixes which could be originated
473 by that AS number. ROA tables could be filled with data from RPKI (RFC
474 6480) or from public databases like Whois. ROA tables are examined by
475 <cf/roa_check()/ operator in filters.
477 Currently, there is just one option, <cf>roa <m/prefix/ max <m/num/ as
478 <m/num/</cf>, which can be used to populate the ROA table with static
479 ROA entries. The option may be used multiple times. Other entries can be
480 added dynamically by <cf/add roa/ command.
482 <tag>eval <m/expr/</tag>
483 Evaluates given filter expression. It is used by us for testing of filters.
487 <sect>Protocol options
489 <p>For each protocol instance, you can configure a bunch of options. Some of
490 them (those described in this section) are generic, some are specific to the
491 protocol (see sections talking about the protocols).
493 <p>Several options use a <m/switch/ argument. It can be either <cf/on/,
494 <cf/yes/ or a numeric expression with a non-zero value for the option to be
495 enabled or <cf/off/, <cf/no/ or a numeric expression evaluating to zero to
496 disable it. An empty <m/switch/ is equivalent to <cf/on/ ("silence means
500 <tag>preference <m/expr/</tag>
501 Sets the preference of routes generated by this protocol. Default:
504 <tag>disabled <m/switch/</tag>
505 Disables the protocol. You can change the disable/enable status from the
506 command line interface without needing to touch the configuration.
507 Disabled protocols are not activated. Default: protocol is enabled.
509 <tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
510 Set protocol debugging options. If asked, each protocol is capable of
511 writing trace messages about its work to the log (with category
512 <cf/trace/). You can either request printing of <cf/all/ trace messages
513 or only of the types selected: <cf/states/ for protocol state changes
514 (protocol going up, down, starting, stopping etc.), <cf/routes/ for
515 routes exchanged with the routing table, <cf/filters/ for details on
516 route filtering, <cf/interfaces/ for interface change events sent to the
517 protocol, <cf/events/ for events internal to the protocol and <cf/packets/
518 for packets sent and received by the protocol. Default: off.
520 <tag>mrtdump all|off|{ states, messages }</tag>
521 Set protocol MRTdump flags. MRTdump is a standard binary format for
522 logging information from routing protocols and daemons. These flags
523 control what kind of information is logged from the protocol to the
524 MRTdump file (which must be specified by global <cf/mrtdump/ option, see
525 the previous section). Although these flags are similar to flags of
526 <cf/debug/ option, their meaning is different and protocol-specific. For
527 BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs
528 received BGP messages. Other protocols does not support MRTdump yet.
530 <tag>router id <m/IPv4 address/</tag>
531 This option can be used to override global router id for a given
532 protocol. Default: uses global router id.
534 <tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag>
535 Specify a filter to be used for filtering routes coming from the
536 protocol to the routing table. <cf/all/ is shorthand for <cf/where true/
537 and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/.
539 <tag>export <m/filter/</tag>
540 This is similar to the <cf>import</cf> keyword, except that it works in
541 the direction from the routing table to the protocol. Default: <cf/none/.
543 <tag>import keep filtered <m/switch/</tag>
544 Usually, if an import filter rejects a route, the route is forgotten.
545 When this option is active, these routes are kept in the routing table,
546 but they are hidden and not propagated to other protocols. But it is
547 possible to show them using <cf/show route filtered/. Note that this
548 option does not work for the pipe protocol. Default: off.
550 <tag><label id="import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
551 Specify an import route limit (a maximum number of routes imported from
552 the protocol) and optionally the action to be taken when the limit is
553 hit. Warn action just prints warning log message. Block action discards
554 new routes coming from the protocol. Restart and disable actions shut
555 the protocol down like appropriate commands. Disable is the default
556 action if an action is not explicitly specified. Note that limits are
557 reset during protocol reconfigure, reload or restart. Default: <cf/off/.
559 <tag>receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
560 Specify an receive route limit (a maximum number of routes received from
561 the protocol and remembered). It works almost identically to <cf>import
562 limit</cf> option, the only difference is that if <cf/import keep
563 filtered/ option is active, filtered routes are counted towards the
564 limit and blocked routes are forgotten, as the main purpose of the
565 receive limit is to protect routing tables from overflow. Import limit,
566 on the contrary, counts accepted routes only and routes blocked by the
567 limit are handled like filtered routes. Default: <cf/off/.
569 <tag>export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
570 Specify an export route limit, works similarly to the <cf>import
571 limit</cf> option, but for the routes exported to the protocol. This
572 option is experimental, there are some problems in details of its
573 behavior -- the number of exported routes can temporarily exceed the
574 limit without triggering it during protocol reload, exported routes
575 counter ignores route blocking and block action also blocks route
576 updates of already accepted routes -- and these details will probably
577 change in the future. Default: <cf/off/.
579 <tag>description "<m/text/"</tag>
580 This is an optional description of the protocol. It is displayed as a
581 part of the output of 'show route all' command.
583 <tag>table <m/name/</tag>
584 Connect this protocol to a non-default routing table.
587 <p>There are several options that give sense only with certain protocols:
590 <tag><label id="dsc-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...] [ { <m/option/ ; [...] } ]</tag>
591 Specifies a set of interfaces on which the protocol is activated with
592 given interface-specific options. A set of interfaces specified by one
593 interface option is described using an interface pattern. The interface
594 pattern consists of a sequence of clauses (separated by commas), each
595 clause is a mask specified as a shell-like pattern. Interfaces are
596 matched by their name.
598 An interface matches the pattern if it matches any of its clauses. If
599 the clause begins with <cf/-/, matching interfaces are excluded. Patterns
600 are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/
601 means eth0 and all non-ethernets.
603 Some protocols (namely OSPFv2 and Direct) support extended clauses that
604 may contain a mask, a prefix, or both of them. An interface matches such
605 clause if its name matches the mask (if specified) and its address
606 matches the prefix (if specified). Extended clauses are used when the
607 protocol handles multiple addresses on an interface independently.
609 An interface option can be used more times with different interface-specific
610 options, in that case for given interface the first matching interface
613 This option is allowed in Babel, BFD, Direct, OSPF, RAdv and RIP
614 protocols, but in OSPF protocol it is used in the <cf/area/ subsection.
620 <cf>interface "*" { type broadcast; };</cf> - start the protocol on all
621 interfaces with <cf>type broadcast</cf> option.
623 <cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the
624 protocol on enumerated interfaces with <cf>type ptp</cf> option.
626 <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
627 on all interfaces that have address from 192.168.0.0/16, but not from
630 <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
631 on all interfaces that have address from 192.168.0.0/16, but not from
634 <cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all
635 ethernet interfaces that have address from 192.168.1.0/24.
637 <tag><label id="dsc-prio">tx class|dscp <m/num/</tag>
638 This option specifies the value of ToS/DS/Class field in IP headers of
639 the outgoing protocol packets. This may affect how the protocol packets
640 are processed by the network relative to the other network traffic. With
641 <cf/class/ keyword, the value (0-255) is used for the whole ToS/Class
642 octet (but two bits reserved for ECN are ignored). With <cf/dscp/
643 keyword, the value (0-63) is used just for the DS field in the octet.
644 Default value is 0xc0 (DSCP 0x30 - CS6).
646 <tag>tx priority <m/num/</tag>
647 This option specifies the local packet priority. This may affect how the
648 protocol packets are processed in the local TX queues. This option is
649 Linux specific. Default value is 7 (highest priority, privileged traffic).
651 <tag><label id="dsc-pass">password "<m/password/" [ { id <m/num/; generate from <m/time/; generate to <m/time/; accept from <m/time/; accept to <m/time/; } ]</tag>
652 Specifies a password that can be used by the protocol. Password option
653 can be used more times to specify more passwords. If more passwords are
654 specified, it is a protocol-dependent decision which one is really
655 used. Specifying passwords does not mean that authentication is enabled,
656 authentication can be enabled by separate, protocol-dependent
657 <cf/authentication/ option.
659 This option is allowed in OSPF and RIP protocols. BGP has also
660 <cf/password/ option, but it is slightly different and described
666 <p>Password option can contain section with some (not necessary all) password sub-options:
669 <tag>id <M>num</M></tag>
670 ID of the password, (1-255). If it is not used, BIRD will choose ID based
671 on an order of the password item in the interface. For example, second
672 password item in one interface will have default ID 2. ID is used by
673 some routing protocols to identify which password was used to
674 authenticate protocol packets.
676 <tag>generate from "<m/time/"</tag>
677 The start time of the usage of the password for packet signing.
678 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
680 <tag>generate to "<m/time/"</tag>
681 The last time of the usage of the password for packet signing.
683 <tag>accept from "<m/time/"</tag>
684 The start time of the usage of the password for packet verification.
686 <tag>accept to "<m/time/"</tag>
687 The last time of the usage of the password for packet verification.
690 <chapt>Remote control
692 <p>You can use the command-line client <file>birdc</file> to talk with a running
693 BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless
694 changed with the <tt/-s/ option given to both the server and the client). The
695 commands can perform simple actions such as enabling/disabling of protocols,
696 telling BIRD to show various information, telling it to show routing table
697 filtered by filter, or asking BIRD to reconfigure. Press <tt/?/ at any time to
698 get online help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
699 client, which allows just read-only commands (<cf/show .../). Option <tt/-v/ can
700 be passed to the client, to make it dump numeric return codes along with the
701 messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your
702 own applications could do that, too -- the format of communication between BIRD
703 and <file/birdc/ is stable (see the programmer's documentation).
705 <p>There is also lightweight variant of BIRD client called <file/birdcl/, which
706 does not support command line editing and history and has minimal dependencies.
707 This is useful for running BIRD in resource constrained environments, where
708 Readline library (required for regular BIRD client) is not available.
710 <p>Many commands have the <m/name/ of the protocol instance as an argument.
711 This argument can be omitted if there exists only a single instance.
713 <p>Here is a brief list of supported functions:
716 <tag>show status</tag>
717 Show router status, that is BIRD version, uptime and time from last
720 <tag>show interfaces [summary]</tag>
721 Show the list of interfaces. For each interface, print its type, state,
722 MTU and addresses assigned.
724 <tag>show protocols [all]</tag>
725 Show list of protocol instances along with tables they are connected to
726 and protocol status, possibly giving verbose information, if <cf/all/ is
729 <tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
730 Show detailed information about OSPF interfaces.
732 <tag>show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
733 Show a list of OSPF neighbors and a state of adjacency to them.
735 <tag>show ospf state [all] [<m/name/]</tag>
736 Show detailed information about OSPF areas based on a content of the
737 link-state database. It shows network topology, stub networks,
738 aggregated networks and routers from other areas and external routes.
739 The command shows information about reachable network nodes, use option
740 <cf/all/ to show information about all network nodes in the link-state
743 <tag>show ospf topology [all] [<m/name/]</tag>
744 Show a topology of OSPF areas based on a content of the link-state
745 database. It is just a stripped-down version of 'show ospf state'.
747 <tag>show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag>
748 Show contents of an OSPF LSA database. Options could be used to filter
751 <tag>show rip interfaces [<m/name/] ["<m/interface/"]</tag>
752 Show detailed information about RIP interfaces.
754 <tag>show rip neighbors [<m/name/] ["<m/interface/"]</tag>
755 Show a list of RIP neighbors and associated state.
757 <tag>show static [<m/name/]</tag>
758 Show detailed information about static routes.
760 <tag>show bfd sessions [<m/name/]</tag>
761 Show information about BFD sessions.
763 <tag>show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
764 Show the list of symbols defined in the configuration (names of
765 protocols, routing tables etc.).
767 <tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [<m/options/]</tag>
768 Show contents of a routing table (by default of the main one or the
769 table attached to a respective protocol), that is routes, their metrics
770 and (in case the <cf/all/ switch is given) all their attributes.
772 <p>You can specify a <m/prefix/ if you want to print routes for a
773 specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get
774 the entry which will be used for forwarding of packets to the given
775 destination. By default, all routes for each network are printed with
776 the selected one at the top, unless <cf/primary/ is given in which case
777 only the selected route is shown.
779 <p>You can also ask for printing only routes processed and accepted by
780 a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
781 </cf> or matching a given condition (<cf>where <m/condition/</cf>).
783 The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for
784 printing of routes that are exported to the specified protocol.
785 With <cf/preexport/, the export filter of the protocol is skipped.
786 With <cf/noexport/, routes rejected by the export filter are printed
787 instead. Note that routes not exported to the protocol for other reasons
788 (e.g. secondary routes or routes imported from that protocol) are not
789 printed even with <cf/noexport/.
791 <p>You can also select just routes added by a specific protocol.
792 <cf>protocol <m/p/</cf>.
794 <p>If BIRD is configured to keep filtered routes (see <cf/import keep
795 filtered/ option), you can show them instead of routes by using
796 <cf/filtered/ switch.
798 <p>The <cf/stats/ switch requests showing of route statistics (the
799 number of networks, number of routes before and after filtering). If
800 you use <cf/count/ instead, only the statistics will be printed.
802 <tag>show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag>
803 Show contents of a ROA table (by default of the first one). You can
804 specify a <m/prefix/ to print ROA entries for a specific network. If you
805 use <cf>for <m/prefix/</cf>, you'll get all entries relevant for route
806 validation of the network prefix; i.e., ROA entries whose prefixes cover
807 the network prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA
808 entries covered by the network prefix. You could also use <cf/as/ option
809 to show just entries for given AS.
811 <tag>add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
812 Add a new ROA entry to a ROA table. Such entry is called <it/dynamic/
813 compared to <it/static/ entries specified in the config file. These
814 dynamic entries survive reconfiguration.
816 <tag>delete roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
817 Delete the specified ROA entry from a ROA table. Only dynamic ROA
818 entries (i.e., the ones added by <cf/add roa/ command) can be deleted.
820 <tag>flush roa [table <m/t/>]</tag>
821 Remove all dynamic ROA entries from a ROA table.
823 <tag>configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
824 Reload configuration from a given file. BIRD will smoothly switch itself
825 to the new configuration, protocols are reconfigured if possible,
826 restarted otherwise. Changes in filters usually lead to restart of
829 If <cf/soft/ option is used, changes in filters does not cause BIRD to
830 restart affected protocols, therefore already accepted routes (according
831 to old filters) would be still propagated, but new routes would be
832 processed according to the new filters.
834 If <cf/timeout/ option is used, config timer is activated. The new
835 configuration could be either confirmed using <cf/configure confirm/
836 command, or it will be reverted to the old one when the config timer
837 expires. This is useful for cases when reconfiguration breaks current
838 routing and a router becomes inaccessible for an administrator. The
839 config timeout expiration is equivalent to <cf/configure undo/
840 command. The timeout duration could be specified, default is 300 s.
842 <tag>configure confirm</tag>
843 Deactivate the config undo timer and therefore confirm the current
846 <tag>configure undo</tag>
847 Undo the last configuration change and smoothly switch back to the
848 previous (stored) configuration. If the last configuration change was
849 soft, the undo change is also soft. There is only one level of undo, but
850 in some specific cases when several reconfiguration requests are given
851 immediately in a row and the intermediate ones are skipped then the undo
852 also skips them back.
854 <tag>configure check ["<m/config file/"]</tag>
855 Read and parse given config file, but do not use it. useful for checking
856 syntactic and some semantic validity of an config file.
858 <tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
859 Enable, disable or restart a given protocol instance, instances matching
860 the <cf><m/pattern/</cf> or <cf/all/ instances.
862 <tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
863 Reload a given protocol instance, that means re-import routes from the
864 protocol instance and re-export preferred routes to the instance. If
865 <cf/in/ or <cf/out/ options are used, the command is restricted to one
866 direction (re-import or re-export).
868 This command is useful if appropriate filters have changed but the
869 protocol instance was not restarted (or reloaded), therefore it still
870 propagates the old set of routes. For example when <cf/configure soft/
871 command was used to change filters.
873 Re-export always succeeds, but re-import is protocol-dependent and might
874 fail (for example, if BGP neighbor does not support route-refresh
875 extension). In that case, re-export is also skipped. Note that for the
876 pipe protocol, both directions are always reloaded together (<cf/in/ or
877 <cf/out/ options are ignored in that case).
882 <tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
883 Control protocol debugging.
885 <tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
886 Dump contents of internal data structures to the debugging output.
888 <tag>echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
889 Control echoing of log messages to the command-line output.
890 See <ref id="dsc-log" name="log option"> for a list of log classes.
892 <tag>eval <m/expr/</tag>
893 Evaluate given expression.
901 <p>BIRD contains a simple programming language. (No, it can't yet read mail :-).
902 There are two objects in this language: filters and functions. Filters are
903 interpreted by BIRD core when a route is being passed between protocols and
904 routing tables. The filter language contains control structures such as if's and
905 switches, but it allows no loops. An example of a filter using many features can
906 be found in <file>filter/test.conf</file>.
908 <p>Filter gets the route, looks at its attributes and modifies some of them if
909 it wishes. At the end, it decides whether to pass the changed route through
910 (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks like
917 if defined( rip_metric ) then
923 if rip_metric > 10 then
924 reject "RIP metric is too big";
930 <p>As you can see, a filter has a header, a list of local variables, and a body.
931 The header consists of the <cf/filter/ keyword followed by a (unique) name of
932 filter. The list of local variables consists of <cf><M>type name</M>;</cf>
933 pairs where each pair defines one local variable. The body consists of <cf>
934 { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You
935 can group several statements to a single compound statement by using braces
936 (<cf>{ <M>statements</M> }</cf>) which is useful if you want to make a bigger
937 block of code conditional.
939 <p>BIRD supports functions, so that you don't have to repeat the same blocks of
940 code over and over. Functions can have zero or more parameters and they can have
941 local variables. Recursion is not allowed. Function definitions look like this:
950 function with_parameters (int parameter)
956 <p>Unlike in C, variables are declared after the <cf/function/ line, but before
957 the first <cf/{/. You can't declare variables in nested blocks. Functions are
958 called like in C: <cf>name(); with_parameters(5);</cf>. Function may return
959 values using the <cf>return <m/[expr]/</cf> command. Returning a value exits
960 from current function (this is similar to C).
962 <p>Filters are declared in a way similar to functions except they can't have
963 explicit parameters. They get a route table entry as an implicit parameter, it
964 is also passed automatically to any functions called. The filter must terminate
965 with either <cf/accept/ or <cf/reject/ statement. If there's a runtime error in
966 filter, the route is rejected.
968 <p>A nice trick to debug filters is to use <cf>show route filter <m/name/</cf>
969 from the command line client. An example session might look like:
972 pavel@bug:~/bird$ ./birdc -s bird.ctl
975 10.0.0.0/8 dev eth0 [direct1 23:21] (240)
976 195.113.30.2/32 dev tunl1 [direct1 23:21] (240)
977 127.0.0.0/8 dev lo [direct1 23:21] (240)
979 show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
980 bird> show route filter { if 127.0.0.5 ˜ net then accept; }
981 127.0.0.0/8 dev lo [direct1 23:21] (240)
988 <p>Each variable and each value has certain type. Booleans, integers and enums
989 are incompatible with each other (that is to prevent you from shooting in the
994 This is a boolean type, it can have only two values, <cf/true/ and
995 <cf/false/. Boolean is the only type you can use in <cf/if/ statements.
998 This is a general integer type. It is an unsigned 32bit type; i.e., you
999 can expect it to store values from 0 to 4294967295. Overflows are not
1000 checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
1003 This is a pair of two short integers. Each component can have values
1004 from 0 to 65535. Literals of this type are written as <cf/(1234,5678)/.
1005 The same syntax can also be used to construct a pair from two arbitrary
1006 integer expressions (for example <cf/(1+2,a)/).
1009 This is a dotted quad of numbers used to represent router IDs (and
1010 others). Each component can have a value from 0 to 255. Literals of
1011 this type are written like IPv4 addresses.
1014 This is a string of characters. There are no ways to modify strings in
1015 filters. You can pass them between functions, assign them to variables
1016 of type <cf/string/, print such variables, use standard string
1017 comparison operations (e.g. <cf/=, !=, <, >, <=, >=/), but
1018 you can't concatenate two strings. String literals are written as
1019 <cf/"This is a string constant"/. Additionally matching (<cf/˜,
1020 !˜/) operators could be used to match a string value against
1021 a shell pattern (represented also as a string).
1024 This type can hold a single IP address. Depending on the compile-time
1025 configuration of BIRD you are using, it is either an IPv4 or IPv6
1026 address. IP addresses are written in the standard notation
1027 (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator
1028 <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out all but
1029 first <cf><M>num</M></cf> bits from the IP address. So
1030 <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
1033 This type can hold a network prefix consisting of IP address and prefix
1034 length. Prefix literals are written as <cf><m/ipaddress//<m/pxlen/</cf>,
1035 or <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
1036 operators on prefixes: <cf/.ip/ which extracts the IP address from the
1037 pair, and <cf/.len/, which separates prefix length from the pair.
1038 So <cf>1.2.0.0/16.len = 16</cf> is true.
1041 This is a specialized type used to represent BGP extended community
1042 values. It is essentially a 64bit value, literals of this type are
1043 usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>, where
1044 <cf/kind/ is a kind of extended community (e.g. <cf/rt/ / <cf/ro/ for a
1045 route target / route origin communities), the format and possible values
1046 of <cf/key/ and <cf/value/ are usually integers, but it depends on the
1047 used kind. Similarly to pairs, ECs can be constructed using expressions
1048 for <cf/key/ and <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
1049 <cf/myas/ is an integer variable).
1051 <tag/int|pair|quad|ip|prefix|ec|enum set/
1052 Filters recognize four types of sets. Sets are similar to strings: you
1053 can pass them around but you can't modify them. Literals of type <cf>int
1054 set</cf> look like <cf> [ 1, 2, 5..7 ]</cf>. As you can see, both simple
1055 values and ranges are permitted in sets.
1057 For pair sets, expressions like <cf/(123,*)/ can be used to denote
1058 ranges (in that case <cf/(123,0)..(123,65535)/). You can also use
1059 <cf/(123,5..100)/ for range <cf/(123,5)..(123,100)/. You can also use
1060 <cf/*/ and <cf/a..b/ expressions in the first part of a pair, note that
1061 such expressions are translated to a set of intervals, which may be
1062 memory intensive. E.g. <cf/(*,4..20)/ is translated to <cf/(0,4..20),
1063 (1,4..20), (2,4..20), ... (65535, 4..20)/.
1065 EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123,
1066 10..20)/ or <cf/(ro, 123, *)/. Expressions requiring the translation
1067 (like <cf/(rt, *, 3)/) are not allowed (as they usually have 4B range
1070 You can also use expressions for int, pair and EC set values. However it
1071 must be possible to evaluate these expressions before daemon boots. So
1072 you can use only constants inside them. E.g.
1081 odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
1082 ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
1083 es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
1086 Sets of prefixes are special: their literals does not allow ranges, but
1087 allows prefix patterns that are written
1088 as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
1089 Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix
1090 pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if the
1091 first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are
1092 identical and <cf>len1 <= ip1 <= len2</cf>. A valid prefix pattern
1093 has to satisfy <cf>low <= high</cf>, but <cf/pxlen/ is not
1094 constrained by <cf/low/ or <cf/high/. Obviously, a prefix matches a
1095 prefix set literal if it matches any prefix pattern in the prefix set
1098 There are also two shorthands for prefix patterns: <cf><m/address//<m/len/+</cf>
1099 is a shorthand for <cf><m/address//<m/len/{<m/len/,<m/maxlen/}</cf>
1100 (where <cf><m/maxlen/</cf> is 32 for IPv4 and 128 for IPv6), that means
1101 network prefix <cf><m/address//<m/len/</cf> and all its subnets.
1102 <cf><m/address//<m/len/-</cf> is a shorthand for
1103 <cf><m/address//<m/len/{0,<m/len/}</cf>, that means network prefix
1104 <cf><m/address//<m/len/</cf> and all its supernets (network prefixes
1107 For example, <cf>[ 1.0.0.0/8, 2.0.0.0/8+, 3.0.0.0/8-, 4.0.0.0/8{16,24}
1108 ]</cf> matches prefix <cf>1.0.0.0/8</cf>, all subprefixes of
1109 <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes
1110 <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf>
1111 matches all prefixes (regardless of IP address) whose prefix length is
1112 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP
1113 address <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 ˜ [ 1.0.0.0/8{15,17} ]</cf>
1114 is true, but <cf>1.0.0.0/16 ˜ [ 1.0.0.0/8- ]</cf> is false.
1116 Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
1117 in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as
1118 <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
1119 <cf>192.168.0.0/16{24,32}</cf>.
1122 Enumeration types are fixed sets of possibilities. You can't define your
1123 own variables of such type, but some route attributes are of enumeration
1124 type. Enumeration types are incompatible with each other.
1127 BGP path is a list of autonomous system numbers. You can't write
1128 literals of this type. There are several special operators on bgppaths:
1130 <cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/.
1132 <cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/.
1134 <cf><m/P/.last_nonaggregated</cf> returns the last ASN in the non-aggregated part of the path <m/P/.
1136 Both <cf/first/ and <cf/last/ return zero if there is no appropriate
1137 ASN, for example if the path contains an AS set element as the first (or
1138 the last) part. If the path ends with an AS set, <cf/last_nonaggregated/
1139 may be used to get last ASN before any AS set.
1141 <cf><m/P/.len</cf> returns the length of path <m/P/.
1143 <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and
1146 <cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN <m/A/ from
1147 from path <m/P/ and returns the result. <m/A/ may also be an integer
1148 set, in that case the operator deletes all ASNs from path <m/P/ that are
1149 also members of set <m/A/.
1151 <cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path <m/P/ that are
1152 not members of integer set <m/A/. I.e., <cf/filter/ do the same as
1153 <cf/delete/ with inverted set <m/A/.
1155 Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
1156 <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
1157 (for example <cf/bgp_path/). Similarly for <cf/delete/ and <cf/filter/.
1160 BGP masks are patterns used for BGP path matching (using <cf>path
1161 ˜ [= 2 3 5 * =]</cf> syntax). The masks resemble wildcard patterns
1162 as used by UNIX shells. Autonomous system numbers match themselves,
1163 <cf/*/ matches any (even empty) sequence of arbitrary AS numbers and
1164 <cf/?/ matches one arbitrary AS number. For example, if <cf>bgp_path</cf>
1165 is 4 3 2 1, then: <tt>bgp_path ˜ [= * 4 3 * =]</tt> is true,
1166 but <tt>bgp_path ˜ [= * 4 5 * =]</tt> is false. BGP mask
1167 expressions can also contain integer expressions enclosed in parenthesis
1168 and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. You can
1169 also use ranges, for example <tt>[= * 3..5 2 100..200 * =]</tt>.
1170 There is also old (deprecated) syntax that uses / .. / instead of [= .. =]
1174 Clist is similar to a set, except that unlike other sets, it can be
1175 modified. The type is used for community list (a set of pairs) and for
1176 cluster list (a set of quads). There exist no literals of this type.
1177 There are three special operators on clists:
1179 <cf><m/C/.len</cf> returns the length of clist <m/C/.
1181 <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and
1182 returns the result. If item <m/P/ is already in clist <m/C/, it does
1183 nothing. <m/P/ may also be a clist, in that case all its members are
1184 added; i.e., it works as clist union.
1186 <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad) <m/P/ from clist
1187 <m/C/ and returns the result. If clist <m/C/ does not contain item
1188 <m/P/, it does nothing. <m/P/ may also be a pair (or quad) set, in that
1189 case the operator deletes all items from clist <m/C/ that are also
1190 members of set <m/P/. Moreover, <m/P/ may also be a clist, which works
1191 analogously; i.e., it works as clist difference.
1193 <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist <m/C/ that are
1194 not members of pair (or quad) set <m/P/. I.e., <cf/filter/ do the same
1195 as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which
1196 works analogously; i.e., it works as clist intersection.
1198 Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
1199 <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute (for
1200 example <cf/bgp_community/). Similarly for <cf/delete/ and <cf/filter/.
1203 Eclist is a data type used for BGP extended community lists. Eclists
1204 are very similar to clists, but they are sets of ECs instead of pairs.
1205 The same operations (like <cf/add/, <cf/delete/ or <cf/˜/ and
1206 <cf/!˜/ membership operators) can be used to modify or test
1207 eclists, with ECs instead of pairs as arguments.
1213 <p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>,
1214 parentheses <cf/(a*(b+c))/, comparison <cf/(a=b, a!=b, a<b, a>=b)/.
1215 Logical operations include unary not (<cf/!/), and (<cf/&&/) and or
1216 (<cf/||/). Special operators include (<cf/˜/,
1217 <cf/!˜/) for "is (not) element of a set" operation - it can be used on
1218 element and set of elements of the same type (returning true if element is
1219 contained in the given set), or on two strings (returning true if first string
1220 matches a shell-like pattern stored in second string) or on IP and prefix
1221 (returning true if IP is within the range defined by that prefix), or on prefix
1222 and prefix (returning true if first prefix is more specific than second one) or
1223 on bgppath and bgpmask (returning true if the path matches the mask) or on
1224 number and bgppath (returning true if the number is in the path) or on bgppath
1225 and int (number) set (returning true if any ASN from the path is in the set) or
1226 on pair/quad and clist (returning true if the pair/quad is element of the
1227 clist) or on clist and pair/quad set (returning true if there is an element of
1228 the clist that is also a member of the pair/quad set).
1230 <p>There is one operator related to ROA infrastructure - <cf/roa_check()/. It
1231 examines a ROA table and does RFC 6483 route origin validation for a given
1232 network prefix. The basic usage is <cf>roa_check(<m/table/)</cf>, which checks
1233 current route (which should be from BGP to have AS_PATH argument) in the
1234 specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA,
1235 ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant
1236 ROAs but none of them match. There is also an extended variant
1237 <cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to specify a
1238 prefix and an ASN as arguments.
1241 <sect>Control structures
1243 <p>Filters support two control structures: conditions and case switches.
1245 <p>Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/command1/;
1246 else <m/command2/;</cf> and you can use <cf>{ <m/command_1/; <m/command_2/;
1247 <M>...</M> }</cf> instead of either command. The <cf>else</cf> clause may be
1248 omitted. If the <cf><m>boolean expression</m></cf> is true, <m/command1/ is
1249 executed, otherwise <m/command2/ is executed.
1251 <p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case
1252 <m/expr/ { else: | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [
1253 ... ] }</cf>. The expression after <cf>case</cf> can be of any type which can be
1254 on the left side of the ˜ operator and anything that could be a member of
1255 a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/
1256 grouping. If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements
1257 between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches
1258 neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed.
1260 <p>Here is example that uses <cf/if/ and <cf/case/ structures:
1264 2: print "two"; print "I can do more commands without {}";
1265 3 .. 5: print "three to five";
1266 else: print "something else";
1269 if 1234 = i then printn "."; else {
1271 print "You need {} around multiple commands";
1276 <sect>Route attributes
1278 <p>A filter is implicitly passed a route, and it can access its attributes just
1279 like it accesses variables. Attempts to access undefined attribute result in a
1280 runtime error; you can check if an attribute is defined by using the
1281 <cf>defined( <m>attribute</m> )</cf> operator. One notable exception to this
1282 rule are attributes of clist type, where undefined value is regarded as empty
1283 clist for most purposes.
1286 <tag><m/prefix/ net</tag>
1287 Network the route is talking about. Read-only. (See the chapter about
1290 <tag><m/enum/ scope</tag>
1291 The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes
1292 local to this host, <cf/SCOPE_LINK/ for those specific for a physical
1293 link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private routes and
1294 <cf/SCOPE_UNIVERSE/ for globally visible routes. This attribute is not
1295 interpreted by BIRD and can be used to mark routes in filters. The
1296 default value for new routes is <cf/SCOPE_UNIVERSE/.
1298 <tag><m/int/ preference</tag>
1299 Preference of the route. Valid values are 0-65535. (See the chapter
1300 about routing tables.)
1302 <tag><m/ip/ from</tag>
1303 The router which the route has originated from.
1305 <tag><m/ip/ gw</tag>
1306 Next hop packets routed using this route should be forwarded to.
1308 <tag><m/string/ proto</tag>
1309 The name of the protocol which the route has been imported from.
1312 <tag><m/enum/ source</tag>
1313 what protocol has told me about this route. Possible values:
1314 <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/,
1315 <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/,
1316 <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/,
1317 <cf/RTS_PIPE/, <cf/RTS_BABEL/.
1319 <tag><m/enum/ cast</tag>
1320 Route type (Currently <cf/RTC_UNICAST/ for normal routes,
1321 <cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will be used in
1322 the future for broadcast, multicast and anycast routes). Read-only.
1324 <tag><m/enum/ dest</tag>
1325 Type of destination the packets should be sent to
1326 (<cf/RTD_ROUTER/ for forwarding to a neighboring router,
1327 <cf/RTD_DEVICE/ for routing to a directly-connected network,
1328 <cf/RTD_MULTIPATH/ for multipath destinations,
1329 <cf/RTD_BLACKHOLE/ for packets to be silently discarded,
1330 <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be
1331 returned with ICMP host unreachable / ICMP administratively prohibited
1332 messages). Can be changed, but only to <cf/RTD_BLACKHOLE/,
1333 <cf/RTD_UNREACHABLE/ or <cf/RTD_PROHIBIT/.
1335 <tag><m/string/ ifname</tag>
1336 Name of the outgoing interface. Sink routes (like blackhole, unreachable
1337 or prohibit) and multipath routes have no interface associated with
1338 them, so <cf/ifname/ returns an empty string for such routes. Read-only.
1340 <tag><m/int/ ifindex</tag>
1341 Index of the outgoing interface. System wide index of the interface. May
1342 be used for interface matching, however indexes might change on interface
1343 creation/removal. Zero is returned for routes with undefined outgoing
1344 interfaces. Read-only.
1346 <tag><m/int/ igp_metric</tag>
1347 The optional attribute that can be used to specify a distance to the
1348 network for routes that do not have a native protocol metric attribute
1349 (like <cf/ospf_metric1/ for OSPF routes). It is used mainly by BGP to
1350 compare internal distances to boundary routers (see below). It is also
1351 used when the route is exported to OSPF as a default value for OSPF type
1355 <p>There also exist some protocol-specific attributes which are described in the
1356 corresponding protocol sections.
1359 <sect>Other statements
1361 <p>The following statements are available:
1364 <tag><m/variable/ = <m/expr/</tag>
1365 Set variable to a given value.
1367 <tag>accept|reject [ <m/expr/ ]</tag>
1368 Accept or reject the route, possibly printing <cf><m>expr</m></cf>.
1370 <tag>return <m/expr/</tag>
1371 Return <cf><m>expr</m></cf> from the current function, the function ends
1374 <tag>print|printn <m/expr/ [<m/, expr.../]</tag>
1375 Prints given expressions; useful mainly while debugging filters. The
1376 <cf/printn/ variant does not terminate the line.
1379 Terminates BIRD. Useful when debugging the filter interpreter.
1389 <p>The Babel protocol (RFC6126) is a loop-avoiding distance-vector routing
1390 protocol that is robust and efficient both in ordinary wired networks and in
1391 wireless mesh networks. Babel is conceptually very simple in its operation and
1392 "just works" in its default configuration, though some configuration is possible
1393 and in some cases desirable.
1395 <p>While the Babel protocol is dual stack (i.e., can carry both IPv4 and IPv6
1396 routes over the same IPv6 transport), BIRD presently implements only the IPv6
1397 subset of the protocol. No Babel extensions are implemented, but the BIRD
1398 implementation can coexist with implementations using the extensions (and will
1399 just ignore extension messages).
1401 <p>The Babel protocol implementation in BIRD is currently in alpha stage.
1403 <sect1>Configuration
1405 <p>Babel supports no global configuration options apart from those common to all
1406 other protocols, but supports the following per-interface configuration options:
1409 protocol babel [<name>] {
1410 interface <interface pattern> {
1411 type <wired|wireless>;
1413 hello interval <number>;
1414 update interval <number>;
1416 tx class|dscp <number>;
1417 tx priority <number>;
1420 check link <switch>;
1426 <tag>type wired|wireless </tag>
1427 This option specifies the interface type: Wired or wireless. Wired
1428 interfaces are considered more reliable, and so the default hello
1429 interval is higher, and a neighbour is considered unreachable after only
1430 a small number of "hello" packets are lost. On wireless interfaces,
1431 hello packets are sent more often, and the ETX link quality estimation
1432 technique is used to compute the metrics of routes discovered over this
1433 interface. This technique will gradually degrade the metric of routes
1434 when packets are lost rather than the more binary up/down mechanism of
1435 wired type links. Default: <cf/wired/.
1437 <tag>rxcost <m/num/</tag>
1438 This specifies the RX cost of the interface. The route metrics will be
1439 computed from this value with a mechanism determined by the interface
1440 <cf/type/. Default: 96 for wired interfaces, 256 for wireless.
1442 <tag>hello interval <m/num/</tag>
1443 Interval at which periodic "hello" messages are sent on this interface,
1444 in seconds. Default: 4 seconds.
1446 <tag>update interval <m/num/</tag>
1447 Interval at which periodic (full) updates are sent. Default: 4 times the
1450 <tag>port <m/number/</tag>
1451 This option selects an UDP port to operate on. The default is to operate
1452 on port 6696 as specified in the Babel RFC.
1454 <tag>tx class|dscp|priority <m/number/</tag>
1455 These options specify the ToS/DiffServ/Traffic class/Priority of the
1456 outgoing Babel packets. See <ref id="dsc-prio" name="tx class"> common
1457 option for detailed description.
1459 <tag>rx buffer <m/number/</tag>
1460 This option specifies the size of buffers used for packet processing.
1461 The buffer size should be bigger than maximal size of received packets.
1462 The default value is the interface MTU, and the value will be clamped to a
1463 minimum of 512 bytes + IP packet overhead.
1465 <tag>tx length <m/number/</tag>
1466 This option specifies the maximum length of generated Babel packets. To
1467 avoid IP fragmentation, it should not exceed the interface MTU value.
1468 The default value is the interface MTU value, and the value will be
1469 clamped to a minimum of 512 bytes + IP packet overhead.
1471 <tag>check link <m/switch/</tag>
1472 If set, the hardware link state (as reported by OS) is taken into
1473 consideration. When the link disappears (e.g. an ethernet cable is
1474 unplugged), neighbors are immediately considered unreachable and all
1475 routes received from them are withdrawn. It is possible that some
1476 hardware drivers or platforms do not implement this feature. Default:
1482 <p>Babel defines just one attribute: the internal babel metric of the route. It
1483 is exposed as the <cf/babel_metric/ attribute and has range from 1 to infinity
1493 interface "wlan0", "wlan1" {
1500 # This matches the default of babeld: redistribute all addresses
1501 # configured on local interfaces, plus re-distribute all routes received
1502 # from other babel peers.
1504 export where (source = RTS_DEVICE) || (source = RTS_BABEL);
1510 <label id="sect-bfd">
1514 <p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it
1515 is an independent tool providing liveness and failure detection. Routing
1516 protocols like OSPF and BGP use integrated periodic "hello" messages to monitor
1517 liveness of neighbors, but detection times of these mechanisms are high (e.g. 40
1518 seconds by default in OSPF, could be set down to several seconds). BFD offers
1519 universal, fast and low-overhead mechanism for failure detection, which could be
1520 attached to any routing protocol in an advisory role.
1522 <p>BFD consists of mostly independent BFD sessions. Each session monitors an
1523 unicast bidirectional path between two BFD-enabled routers. This is done by
1524 periodically sending control packets in both directions. BFD does not handle
1525 neighbor discovery, BFD sessions are created on demand by request of other
1526 protocols (like OSPF or BGP), which supply appropriate information like IP
1527 addresses and associated interfaces. When a session changes its state, these
1528 protocols are notified and act accordingly (e.g. break an OSPF adjacency when
1529 the BFD session went down).
1531 <p>BIRD implements basic BFD behavior as defined in
1532 RFC 5880<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5880.txt">
1533 (some advanced features like the echo mode or authentication are not implemented),
1534 IP transport for BFD as defined in
1535 RFC 5881<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5881.txt"> and
1536 RFC 5883<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5883.txt">
1537 and interaction with client protocols as defined in
1538 RFC 5882<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5882.txt">.
1540 <p>Note that BFD implementation in BIRD is currently a new feature in
1541 development, expect some rough edges and possible UI and configuration changes
1542 in the future. Also note that we currently support at most one protocol instance.
1544 <p>BFD packets are sent with a dynamic source port number. Linux systems use by
1545 default a bit different dynamic port range than the IANA approved one
1546 (49152-65535). If you experience problems with compatibility, please adjust
1547 <cf>/proc/sys/net/ipv4/ip_local_port_range</cf>
1549 <sect1>Configuration
1551 <p>BFD configuration consists mainly of multiple definitions of interfaces.
1552 Most BFD config options are session specific. When a new session is requested
1553 and dynamically created, it is configured from one of these definitions. For
1554 sessions to directly connected neighbors, <cf/interface/ definitions are chosen
1555 based on the interface associated with the session, while <cf/multihop/
1556 definition is used for multihop sessions. If no definition is relevant, the
1557 session is just created with the default configuration. Therefore, an empty BFD
1558 configuration is often sufficient.
1560 <p>Note that to use BFD for other protocols like OSPF or BGP, these protocols
1561 also have to be configured to request BFD sessions, usually by <cf/bfd/ option.
1563 <p>Some of BFD session options require <m/time/ value, which has to be specified
1564 with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds
1565 are allowed as units, practical minimum values are usually in order of tens of
1569 protocol bfd [<name>] {
1570 interface <interface pattern> {
1571 interval <time>;
1572 min rx interval <time>;
1573 min tx interval <time>;
1574 idle tx interval <time>;
1575 multiplier <num>;
1576 passive <switch>;
1579 interval <time>;
1580 min rx interval <time>;
1581 min tx interval <time>;
1582 idle tx interval <time>;
1583 multiplier <num>;
1584 passive <switch>;
1586 neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>];
1591 <tag>interface <m/pattern [, ...]/ { <m/options/ }</tag>
1592 Interface definitions allow to specify options for sessions associated
1593 with such interfaces and also may contain interface specific options.
1594 See <ref id="dsc-iface" name="interface"> common option for a detailed
1595 description of interface patterns. Note that contrary to the behavior of
1596 <cf/interface/ definitions of other protocols, BFD protocol would accept
1597 sessions (in default configuration) even on interfaces not covered by
1600 <tag>multihop { <m/options/ }</tag>
1601 Multihop definitions allow to specify options for multihop BFD sessions,
1602 in the same manner as <cf/interface/ definitions are used for directly
1603 connected sessions. Currently only one such definition (for all multihop
1604 sessions) could be used.
1606 <tag>neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag>
1607 BFD sessions are usually created on demand as requested by other
1608 protocols (like OSPF or BGP). This option allows to explicitly add
1609 a BFD session to the specified neighbor regardless of such requests.
1611 The session is identified by the IP address of the neighbor, with
1612 optional specification of used interface and local IP. By default
1613 the neighbor must be directly connected, unless the session is
1614 configured as multihop. Note that local IP must be specified for
1618 <p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions):
1621 <tag>interval <m/time/</tag>
1622 BFD ensures availability of the forwarding path associated with the
1623 session by periodically sending BFD control packets in both
1624 directions. The rate of such packets is controlled by two options,
1625 <cf/min rx interval/ and <cf/min tx interval/ (see below). This option
1626 is just a shorthand to set both of these options together.
1628 <tag>min rx interval <m/time/</tag>
1629 This option specifies the minimum RX interval, which is announced to the
1630 neighbor and used there to limit the neighbor's rate of generated BFD
1631 control packets. Default: 10 ms.
1633 <tag>min tx interval <m/time/</tag>
1634 This option specifies the desired TX interval, which controls the rate
1635 of generated BFD control packets (together with <cf/min rx interval/
1636 announced by the neighbor). Note that this value is used only if the BFD
1637 session is up, otherwise the value of <cf/idle tx interval/ is used
1638 instead. Default: 100 ms.
1640 <tag>idle tx interval <m/time/</tag>
1641 In order to limit unnecessary traffic in cases where a neighbor is not
1642 available or not running BFD, the rate of generated BFD control packets
1643 is lower when the BFD session is not up. This option specifies the
1644 desired TX interval in such cases instead of <cf/min tx interval/.
1647 <tag>multiplier <m/num/</tag>
1648 Failure detection time for BFD sessions is based on established rate of
1649 BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this
1650 multiplier, which is essentially (ignoring jitter) a number of missed
1651 packets after which the session is declared down. Note that rates and
1652 multipliers could be different in each direction of a BFD session.
1655 <tag>passive <m/switch/</tag>
1656 Generally, both BFD session endpoints try to establish the session by
1657 sending control packets to the other side. This option allows to enable
1658 passive mode, which means that the router does not send BFD packets
1659 until it has received one from the other side. Default: disabled.
1667 min rx interval 20 ms;
1668 min tx interval 50 ms;
1669 idle tx interval 300 ms;
1681 neighbor 192.168.1.10;
1682 neighbor 192.168.2.2 dev "eth2";
1683 neighbor 192.168.10.1 local 192.168.1.1 multihop;
1690 <p>The Border Gateway Protocol is the routing protocol used for backbone level
1691 routing in the today's Internet. Contrary to other protocols, its convergence
1692 does not rely on all routers following the same rules for route selection,
1693 making it possible to implement any routing policy at any router in the network,
1694 the only restriction being that if a router advertises a route, it must accept
1695 and forward packets according to it.
1697 <p>BGP works in terms of autonomous systems (often abbreviated as AS). Each AS
1698 is a part of the network with common management and common routing policy. It is
1699 identified by a unique 16-bit number (ASN). Routers within each AS usually
1700 exchange AS-internal routing information with each other using an interior
1701 gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of
1702 the AS communicate global (inter-AS) network reachability information with their
1703 neighbors in the neighboring AS'es via exterior BGP (eBGP) and redistribute
1704 received information to other routers in the AS via interior BGP (iBGP).
1706 <p>Each BGP router sends to its neighbors updates of the parts of its routing
1707 table it wishes to export along with complete path information (a list of AS'es
1708 the packet will travel through if it uses the particular route) in order to
1709 avoid routing loops.
1711 <p>BIRD supports all requirements of the BGP4 standard as defined in
1712 RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
1713 It also supports the community attributes
1714 (RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
1715 capability negotiation
1716 (RFC 5492<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5492.txt">),
1717 MD5 password authentication
1718 (RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
1719 extended communities
1720 (RFC 4360<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt">),
1722 (RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
1724 (RFC 4724<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4724.txt">),
1725 multiprotocol extensions
1726 (RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
1728 (RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">),
1729 and 4B AS numbers in extended communities
1730 (RFC 5668<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt">).
1733 For IPv6, it uses the standard multiprotocol extensions defined in
1734 RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">
1735 and applied to IPv6 according to
1736 RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
1738 <sect1>Route selection rules
1740 <p>BGP doesn't have any simple metric, so the rules for selection of an optimal
1741 route among multiple BGP routes with the same preference are a bit more complex
1742 and they are implemented according to the following algorithm. It starts the
1743 first rule, if there are more "best" routes, then it uses the second rule to
1744 choose among them and so on.
1747 <item>Prefer route with the highest Local Preference attribute.
1748 <item>Prefer route with the shortest AS path.
1749 <item>Prefer IGP origin over EGP and EGP origin over incomplete.
1750 <item>Prefer the lowest value of the Multiple Exit Discriminator.
1751 <item>Prefer routes received via eBGP over ones received via iBGP.
1752 <item>Prefer routes with lower internal distance to a boundary router.
1753 <item>Prefer the route with the lowest value of router ID of the
1757 <sect1>IGP routing table
1759 <p>BGP is mainly concerned with global network reachability and with routes to
1760 other autonomous systems. When such routes are redistributed to routers in the
1761 AS via BGP, they contain IP addresses of a boundary routers (in route attribute
1762 NEXT_HOP). BGP depends on existing IGP routing table with AS-internal routes to
1763 determine immediate next hops for routes and to know their internal distances to
1764 boundary routers for the purpose of BGP route selection. In BIRD, there is
1765 usually one routing table used for both IGP routes and BGP routes.
1767 <sect1>Configuration
1769 <p>Each instance of the BGP corresponds to one neighboring router. This allows
1770 to set routing policy and all the other parameters differently for each neighbor
1771 using the following configuration parameters:
1774 <tag>local [<m/ip/] as <m/number/</tag>
1775 Define which AS we are part of. (Note that contrary to other IP routers,
1776 BIRD is able to act as a router located in multiple AS'es simultaneously,
1777 but in such cases you need to tweak the BGP paths manually in the filters
1778 to get consistent behavior.) Optional <cf/ip/ argument specifies a source
1779 address, equivalent to the <cf/source address/ option (see below). This
1780 parameter is mandatory.
1782 <tag>neighbor [<m/ip/] [port <m/number/] [as <m/number/]</tag>
1783 Define neighboring router this instance will be talking to and what AS
1784 it is located in. In case the neighbor is in the same AS as we are, we
1785 automatically switch to iBGP. Optionally, the remote port may also be
1786 specified. The parameter may be used multiple times with different
1787 sub-options (e.g., both <cf/neighbor 10.0.0.1 as 65000;/ and
1788 <cf/neighbor 10.0.0.1; neighbor as 65000;/ are valid). This parameter is
1791 <tag>interface <m/string/</tag>
1792 Define interface we should use for link-local BGP IPv6 sessions.
1793 Interface can also be specified as a part of <cf/neighbor address/
1794 (e.g., <cf/neighbor fe80::1234%eth0 as 65000;/). It is an error to use
1795 this parameter for non link-local sessions.
1798 Specify that the neighbor is directly connected. The IP address of the
1799 neighbor must be from a directly reachable IP range (i.e. associated
1800 with one of your router's interfaces), otherwise the BGP session
1801 wouldn't start but it would wait for such interface to appear. The
1802 alternative is the <cf/multihop/ option. Default: enabled for eBGP.
1804 <tag>multihop [<m/number/]</tag>
1805 Configure multihop BGP session to a neighbor that isn't directly
1806 connected. Accurately, this option should be used if the configured
1807 neighbor IP address does not match with any local network subnets. Such
1808 IP address have to be reachable through system routing table. The
1809 alternative is the <cf/direct/ option. For multihop BGP it is
1810 recommended to explicitly configure the source address to have it
1811 stable. Optional <cf/number/ argument can be used to specify the number
1812 of hops (used for TTL). Note that the number of networks (edges) in a
1813 path is counted; i.e., if two BGP speakers are separated by one router,
1814 the number of hops is 2. Default: enabled for iBGP.
1816 <tag>source address <m/ip/</tag>
1817 Define local address we should use for next hop calculation and as a
1818 source address for the BGP session. Default: the address of the local
1819 end of the interface our neighbor is connected to.
1821 <tag>next hop self</tag>
1822 Avoid calculation of the Next Hop attribute and always advertise our own
1823 source address as a next hop. This needs to be used only occasionally to
1824 circumvent misconfigurations of other routers. Default: disabled.
1826 <tag>next hop keep</tag>
1827 Forward the received Next Hop attribute even in situations where the
1828 local address should be used instead, like when the route is sent to an
1829 interface with a different subnet. Default: disabled.
1831 <tag>missing lladdr self|drop|ignore</tag>
1832 Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6
1833 address, but sometimes it has to contain both global and link-local IPv6
1834 addresses. This option specifies what to do if BIRD have to send both
1835 addresses but does not know link-local address. This situation might
1836 happen when routes from other protocols are exported to BGP, or when
1837 improper updates are received from BGP peers. <cf/self/ means that BIRD
1838 advertises its own local address instead. <cf/drop/ means that BIRD
1839 skips that prefixes and logs error. <cf/ignore/ means that BIRD ignores
1840 the problem and sends just the global address (and therefore forms
1841 improper BGP update). Default: <cf/self/, unless BIRD is configured as a
1842 route server (option <cf/rs client/), in that case default is <cf/ignore/,
1843 because route servers usually do not forward packets themselves.
1845 <tag>gateway direct|recursive</tag>
1846 For received routes, their <cf/gw/ (immediate next hop) attribute is
1847 computed from received <cf/bgp_next_hop/ attribute. This option
1848 specifies how it is computed. Direct mode means that the IP address from
1849 <cf/bgp_next_hop/ is used if it is directly reachable, otherwise the
1850 neighbor IP address is used. Recursive mode means that the gateway is
1851 computed by an IGP routing table lookup for the IP address from
1852 <cf/bgp_next_hop/. Note that there is just one level of indirection in
1853 recursive mode - the route obtained by the lookup must not be recursive
1854 itself, to prevent mutually recursive routes.
1856 Recursive mode is the behavior specified by the BGP
1857 standard. Direct mode is simpler, does not require any routes in a
1858 routing table, and was used in older versions of BIRD, but does not
1859 handle well nontrivial iBGP setups and multihop. Recursive mode is
1860 incompatible with <ref id="dsc-sorted" name="sorted tables">. Default:
1861 <cf/direct/ for direct sessions, <cf/recursive/ for multihop sessions.
1863 <tag>igp table <m/name/</tag>
1864 Specifies a table that is used as an IGP routing table. Default: the
1865 same as the table BGP is connected to.
1867 <tag>check link <M>switch</M></tag>
1868 BGP could use hardware link state into consideration. If enabled,
1869 BIRD tracks the link state of the associated interface and when link
1870 disappears (e.g. an ethernet cable is unplugged), the BGP session is
1871 immediately shut down. Note that this option cannot be used with
1872 multihop BGP. Default: disabled.
1874 <tag>bfd <M>switch</M></tag>
1875 BGP could use BFD protocol as an advisory mechanism for neighbor
1876 liveness and failure detection. If enabled, BIRD setups a BFD session
1877 for the BGP neighbor and tracks its liveness by it. This has an
1878 advantage of an order of magnitude lower detection times in case of
1879 failure. Note that BFD protocol also has to be configured, see
1880 <ref id="sect-bfd" name="BFD"> section for details. Default: disabled.
1882 <tag>ttl security <m/switch/</tag>
1883 Use GTSM (RFC 5082 - the generalized TTL security mechanism). GTSM
1884 protects against spoofed packets by ignoring received packets with a
1885 smaller than expected TTL. To work properly, GTSM have to be enabled on
1886 both sides of a BGP session. If both <cf/ttl security/ and <cf/multihop/
1887 options are enabled, <cf/multihop/ option should specify proper hop
1888 value to compute expected TTL. Kernel support required: Linux: 2.6.34+
1889 (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only. Note that full
1890 (ICMP protection, for example) RFC 5082 support is provided by Linux
1891 only. Default: disabled.
1893 <tag>password <m/string/</tag>
1894 Use this password for MD5 authentication of BGP sessions (RFC 2385).
1895 When used on BSD systems, see also <cf/setkey/ option below. Default:
1898 <tag>setkey <m/switch/</tag>
1899 On BSD systems, keys for TCP MD5 authentication are stored in the global
1900 SA/SP database, which can be accessed by external utilities (e.g.
1901 setkey(8)). BIRD configures security associations in the SA/SP database
1902 automatically based on <cf/password/ options (see above), this option
1903 allows to disable automatic updates by BIRD when manual configuration by
1904 external utilities is preferred. Note that automatic SA/SP database
1905 updates are currently implemented only for FreeBSD. Passwords have to be
1906 set manually by an external utility on NetBSD and OpenBSD. Default:
1907 enabled (ignored on non-FreeBSD).
1909 <tag>passive <m/switch/</tag>
1910 Standard BGP behavior is both initiating outgoing connections and
1911 accepting incoming connections. In passive mode, outgoing connections
1912 are not initiated. Default: off.
1914 <tag>rr client</tag>
1915 Be a route reflector and treat the neighbor as a route reflection
1916 client. Default: disabled.
1918 <tag>rr cluster id <m/IPv4 address/</tag>
1919 Route reflectors use cluster id to avoid route reflection loops. When
1920 there is one route reflector in a cluster it usually uses its router id
1921 as a cluster id, but when there are more route reflectors in a cluster,
1922 these need to be configured (using this option) to use a common cluster
1923 id. Clients in a cluster need not know their cluster id and this option
1924 is not allowed for them. Default: the same as router id.
1926 <tag>rs client</tag>
1927 Be a route server and treat the neighbor as a route server client.
1928 A route server is used as a replacement for full mesh EBGP routing in
1929 Internet exchange points in a similar way to route reflectors used in
1930 IBGP routing. BIRD does not implement obsoleted RFC 1863, but uses
1931 ad-hoc implementation, which behaves like plain EBGP but reduces
1932 modifications to advertised route attributes to be transparent (for
1933 example does not prepend its AS number to AS PATH attribute and keeps
1934 MED attribute). Default: disabled.
1936 <tag>secondary <m/switch/</tag>
1937 Usually, if an export filter rejects a selected route, no other route is
1938 propagated for that network. This option allows to try the next route in
1939 order until one that is accepted is found or all routes for that network
1940 are rejected. This can be used for route servers that need to propagate
1941 different tables to each client but do not want to have these tables
1942 explicitly (to conserve memory). This option requires that the connected
1943 routing table is <ref id="dsc-sorted" name="sorted">. Default: off.
1945 <tag>add paths <m/switch/|rx|tx</tag>
1946 Standard BGP can propagate only one path (route) per destination network
1947 (usually the selected one). This option controls the add-path protocol
1948 extension, which allows to advertise any number of paths to a
1949 destination. Note that to be active, add-path has to be enabled on both
1950 sides of the BGP session, but it could be enabled separately for RX and
1951 TX direction. When active, all available routes accepted by the export
1952 filter are advertised to the neighbor. Default: off.
1954 <tag>allow local as [<m/number/]</tag>
1955 BGP prevents routing loops by rejecting received routes with the local
1956 AS number in the AS path. This option allows to loose or disable the
1957 check. Optional <cf/number/ argument can be used to specify the maximum
1958 number of local ASNs in the AS path that is allowed for received
1959 routes. When the option is used without the argument, the check is
1960 completely disabled and you should ensure loop-free behavior by some
1961 other means. Default: 0 (no local AS number allowed).
1963 <tag>enable route refresh <m/switch/</tag>
1964 After the initial route exchange, BGP protocol uses incremental updates
1965 to keep BGP speakers synchronized. Sometimes (e.g., if BGP speaker
1966 changes its import filter, or if there is suspicion of inconsistency) it
1967 is necessary to do a new complete route exchange. BGP protocol extension
1968 Route Refresh (RFC 2918) allows BGP speaker to request re-advertisement
1969 of all routes from its neighbor. BGP protocol extension Enhanced Route
1970 Refresh (RFC 7313) specifies explicit begin and end for such exchanges,
1971 therefore the receiver can remove stale routes that were not advertised
1972 during the exchange. This option specifies whether BIRD advertises these
1973 capabilities and supports related procedures. Note that even when
1974 disabled, BIRD can send route refresh requests. Default: on.
1976 <tag>graceful restart <m/switch/|aware</tag>
1977 When a BGP speaker restarts or crashes, neighbors will discard all
1978 received paths from the speaker, which disrupts packet forwarding even
1979 when the forwarding plane of the speaker remains intact. RFC 4724
1980 specifies an optional graceful restart mechanism to alleviate this
1981 issue. This option controls the mechanism. It has three states:
1982 Disabled, when no support is provided. Aware, when the graceful restart
1983 support is announced and the support for restarting neighbors is
1984 provided, but no local graceful restart is allowed (i.e. receiving-only
1985 role). Enabled, when the full graceful restart support is provided
1986 (i.e. both restarting and receiving role). Note that proper support for
1987 local graceful restart requires also configuration of other protocols.
1990 <tag>graceful restart time <m/number/</tag>
1991 The restart time is announced in the BGP graceful restart capability
1992 and specifies how long the neighbor would wait for the BGP session to
1993 re-establish after a restart before deleting stale routes. Default:
1996 <tag>interpret communities <m/switch/</tag>
1997 RFC 1997 demands that BGP speaker should process well-known communities
1998 like no-export (65535, 65281) or no-advertise (65535, 65282). For
1999 example, received route carrying a no-adverise community should not be
2000 advertised to any of its neighbors. If this option is enabled (which is
2001 by default), BIRD has such behavior automatically (it is evaluated when
2002 a route is exported to the BGP protocol just before the export filter).
2003 Otherwise, this integrated processing of well-known communities is
2004 disabled. In that case, similar behavior can be implemented in the
2005 export filter. Default: on.
2007 <tag>enable as4 <m/switch/</tag>
2008 BGP protocol was designed to use 2B AS numbers and was extended later to
2009 allow 4B AS number. BIRD supports 4B AS extension, but by disabling this
2010 option it can be persuaded not to advertise it and to maintain old-style
2011 sessions with its neighbors. This might be useful for circumventing bugs
2012 in neighbor's implementation of 4B AS extension. Even when disabled
2013 (off), BIRD behaves internally as AS4-aware BGP router. Default: on.
2015 <tag>enable extended messages <m/switch/</tag>
2016 The BGP protocol uses maximum message length of 4096 bytes. This option
2017 provides an extension to allow extended messages with length up
2018 to 65535 bytes. Default: off.
2020 <tag>capabilities <m/switch/</tag>
2021 Use capability advertisement to advertise optional capabilities. This is
2022 standard behavior for newer BGP implementations, but there might be some
2023 older BGP implementations that reject such connection attempts. When
2024 disabled (off), features that request it (4B AS support) are also
2025 disabled. Default: on, with automatic fallback to off when received
2026 capability-related error.
2028 <tag>advertise ipv4 <m/switch/</tag>
2029 Advertise IPv4 multiprotocol capability. This is not a correct behavior
2030 according to the strict interpretation of RFC 4760, but it is widespread
2031 and required by some BGP implementations (Cisco and Quagga). This option
2032 is relevant to IPv4 mode with enabled capability advertisement
2035 <tag>route limit <m/number/</tag>
2036 The maximal number of routes that may be imported from the protocol. If
2037 the route limit is exceeded, the connection is closed with an error.
2038 Limit is currently implemented as <cf>import limit <m/number/ action
2039 restart</cf>. This option is obsolete and it is replaced by
2040 <ref id="import-limit" name="import limit option">. Default: no limit.
2042 <tag>disable after error <m/switch/</tag>
2043 When an error is encountered (either locally or by the other side),
2044 disable the instance automatically and wait for an administrator to fix
2045 the problem manually. Default: off.
2047 <tag>hold time <m/number/</tag>
2048 Time in seconds to wait for a Keepalive message from the other side
2049 before considering the connection stale. Default: depends on agreement
2050 with the neighboring router, we prefer 240 seconds if the other side is
2051 willing to accept it.
2053 <tag>startup hold time <m/number/</tag>
2054 Value of the hold timer used before the routers have a chance to exchange
2055 open messages and agree on the real value. Default: 240 seconds.
2057 <tag>keepalive time <m/number/</tag>
2058 Delay in seconds between sending of two consecutive Keepalive messages.
2059 Default: One third of the hold time.
2061 <tag>connect delay time <m/number/</tag>
2062 Delay in seconds between protocol startup and the first attempt to
2063 connect. Default: 5 seconds.
2065 <tag>connect retry time <m/number/</tag>
2066 Time in seconds to wait before retrying a failed attempt to connect.
2067 Default: 120 seconds.
2069 <tag>error wait time <m/number/,<m/number/</tag>
2070 Minimum and maximum delay in seconds between a protocol failure (either
2071 local or reported by the peer) and automatic restart. Doesn't apply
2072 when <cf/disable after error/ is configured. If consecutive errors
2073 happen, the delay is increased exponentially until it reaches the
2074 maximum. Default: 60, 300.
2076 <tag>error forget time <m/number/</tag>
2077 Maximum time in seconds between two protocol failures to treat them as a
2078 error sequence which makes <cf/error wait time/ increase exponentially.
2079 Default: 300 seconds.
2081 <tag>path metric <m/switch/</tag>
2082 Enable comparison of path lengths when deciding which BGP route is the
2083 best one. Default: on.
2085 <tag>med metric <m/switch/</tag>
2086 Enable comparison of MED attributes (during best route selection) even
2087 between routes received from different ASes. This may be useful if all
2088 MED attributes contain some consistent metric, perhaps enforced in
2089 import filters of AS boundary routers. If this option is disabled, MED
2090 attributes are compared only if routes are received from the same AS
2091 (which is the standard behavior). Default: off.
2093 <tag>deterministic med <m/switch/</tag>
2094 BGP route selection algorithm is often viewed as a comparison between
2095 individual routes (e.g. if a new route appears and is better than the
2096 current best one, it is chosen as the new best one). But the proper
2097 route selection, as specified by RFC 4271, cannot be fully implemented
2098 in that way. The problem is mainly in handling the MED attribute. BIRD,
2099 by default, uses an simplification based on individual route comparison,
2100 which in some cases may lead to temporally dependent behavior (i.e. the
2101 selection is dependent on the order in which routes appeared). This
2102 option enables a different (and slower) algorithm implementing proper
2103 RFC 4271 route selection, which is deterministic. Alternative way how to
2104 get deterministic behavior is to use <cf/med metric/ option. This option
2105 is incompatible with <ref id="dsc-sorted" name="sorted tables">.
2108 <tag>igp metric <m/switch/</tag>
2109 Enable comparison of internal distances to boundary routers during best
2110 route selection. Default: on.
2112 <tag>prefer older <m/switch/</tag>
2113 Standard route selection algorithm breaks ties by comparing router IDs.
2114 This changes the behavior to prefer older routes (when both are external
2115 and from different peer). For details, see RFC 5004. Default: off.
2117 <tag>default bgp_med <m/number/</tag>
2118 Value of the Multiple Exit Discriminator to be used during route
2119 selection when the MED attribute is missing. Default: 0.
2121 <tag>default bgp_local_pref <m/number/</tag>
2122 A default value for the Local Preference attribute. It is used when
2123 a new Local Preference attribute is attached to a route by the BGP
2124 protocol itself (for example, if a route is received through eBGP and
2125 therefore does not have such attribute). Default: 100 (0 in pre-1.2.0
2131 <p>BGP defines several route attributes. Some of them (those marked with
2132 `<tt/I/' in the table below) are available on internal BGP connections only,
2133 some of them (marked with `<tt/O/') are optional.
2136 <tag>bgppath <cf/bgp_path/</tag>
2137 Sequence of AS numbers describing the AS path the packet will travel
2138 through when forwarded according to the particular route. In case of
2139 internal BGP it doesn't contain the number of the local AS.
2141 <tag>int <cf/bgp_local_pref/ [I]</tag>
2142 Local preference value used for selection among multiple BGP routes (see
2143 the selection rules above). It's used as an additional metric which is
2144 propagated through the whole local AS.
2146 <tag>int <cf/bgp_med/ [O]</tag>
2147 The Multiple Exit Discriminator of the route is an optional attribute
2148 which is used on external (inter-AS) links to convey to an adjacent AS
2149 the optimal entry point into the local AS. The received attribute is
2150 also propagated over internal BGP links. The attribute value is zeroed
2151 when a route is exported to an external BGP instance to ensure that the
2152 attribute received from a neighboring AS is not propagated to other
2153 neighboring ASes. A new value might be set in the export filter of an
2154 external BGP instance. See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
2155 for further discussion of BGP MED attribute.
2157 <tag>enum <cf/bgp_origin/</tag>
2158 Origin of the route: either <cf/ORIGIN_IGP/ if the route has originated
2159 in an interior routing protocol or <cf/ORIGIN_EGP/ if it's been imported
2160 from the <tt>EGP</tt> protocol (nowadays it seems to be obsolete) or
2161 <cf/ORIGIN_INCOMPLETE/ if the origin is unknown.
2163 <tag>ip <cf/bgp_next_hop/</tag>
2164 Next hop to be used for forwarding of packets to this destination. On
2165 internal BGP connections, it's an address of the originating router if
2166 it's inside the local AS or a boundary router the packet will leave the
2167 AS through if it's an exterior route, so each BGP speaker within the AS
2168 has a chance to use the shortest interior path possible to this point.
2170 <tag>void <cf/bgp_atomic_aggr/ [O]</tag>
2171 This is an optional attribute which carries no value, but the sole
2172 presence of which indicates that the route has been aggregated from
2173 multiple routes by some router on the path from the originator.
2175 <!-- we don't handle aggregators right since they are of a very obscure type
2176 <tag>bgp_aggregator</tag>
2178 <tag>clist <cf/bgp_community/ [O]</tag>
2179 List of community values associated with the route. Each such value is a
2180 pair (represented as a <cf/pair/ data type inside the filters) of 16-bit
2181 integers, the first of them containing the number of the AS which
2182 defines the community and the second one being a per-AS identifier.
2183 There are lots of uses of the community mechanism, but generally they
2184 are used to carry policy information like "don't export to USA peers".
2185 As each AS can define its own routing policy, it also has a complete
2186 freedom about which community attributes it defines and what will their
2189 <tag>eclist <cf/bgp_ext_community/ [O]</tag>
2190 List of extended community values associated with the route. Extended
2191 communities have similar usage as plain communities, but they have an
2192 extended range (to allow 4B ASNs) and a nontrivial structure with a type
2193 field. Individual community values are represented using an <cf/ec/ data
2194 type inside the filters.
2196 <tag>quad <cf/bgp_originator_id/ [I, O]</tag>
2197 This attribute is created by the route reflector when reflecting the
2198 route and contains the router ID of the originator of the route in the
2201 <tag>clist <cf/bgp_cluster_list/ [I, O]</tag>
2202 This attribute contains a list of cluster IDs of route reflectors. Each
2203 route reflector prepends its cluster ID when reflecting the route.
2210 local as 65000; # Use a private AS number
2211 neighbor 198.51.100.130 as 64496; # Our neighbor ...
2212 multihop; # ... which is connected indirectly
2213 export filter { # We use non-trivial export rules
2214 if source = RTS_STATIC then { # Export only static routes
2215 # Assign our community
2216 bgp_community.add((65000,64501));
2217 # Artificially increase path length
2218 # by advertising local AS number twice
2219 if bgp_path ~ [= 65000 =] then
2220 bgp_path.prepend(65000);
2226 source address 198.51.100.14; # Use a non-standard source address
2233 <p>The Device protocol is not a real routing protocol. It doesn't generate any
2234 routes and it only serves as a module for getting information about network
2235 interfaces from the kernel.
2237 <p>Except for very unusual circumstances, you probably should include this
2238 protocol in the configuration since almost all other protocols require network
2239 interfaces to be defined for them to work with.
2241 <sect1>Configuration
2245 <tag>scan time <m/number/</tag>
2246 Time in seconds between two scans of the network interface list. On
2247 systems where we are notified about interface status changes
2248 asynchronously (such as newer versions of Linux), we need to scan the
2249 list only in order to avoid confusion by lost notification messages,
2250 so the default time is set to a large value.
2252 <tag>primary [ "<m/mask/" ] <m/prefix/</tag>
2253 If a network interface has more than one network address, BIRD has to
2254 choose one of them as a primary one. By default, BIRD chooses the
2255 lexicographically smallest address as the primary one.
2257 This option allows to specify which network address should be chosen as
2258 a primary one. Network addresses that match <m/prefix/ are preferred to
2259 non-matching addresses. If more <cf/primary/ options are used, the first
2260 one has the highest preference. If "<m/mask/" is specified, then such
2261 <cf/primary/ option is relevant only to matching network interfaces.
2263 In all cases, an address marked by operating system as secondary cannot
2264 be chosen as the primary one.
2267 <p>As the Device protocol doesn't generate any routes, it cannot have
2268 any attributes. Example configuration looks like this:
2272 scan time 10; # Scan the interfaces often
2273 primary "eth0" 192.168.1.1;
2274 primary 192.168.0.0/16;
2281 <p>The Direct protocol is a simple generator of device routes for all the
2282 directly connected networks according to the list of interfaces provided by the
2283 kernel via the Device protocol.
2285 <p>The question is whether it is a good idea to have such device routes in BIRD
2286 routing table. OS kernel usually handles device routes for directly connected
2287 networks by itself so we don't need (and don't want) to export these routes to
2288 the kernel protocol. OSPF protocol creates device routes for its interfaces
2289 itself and BGP protocol is usually used for exporting aggregate routes. Although
2290 there are some use cases that use the direct protocol (like abusing eBGP as an
2291 IGP routing protocol), in most cases it is not needed to have these device
2292 routes in BIRD routing table and to use the direct protocol.
2294 <p>There is one notable case when you definitely want to use the direct protocol
2295 -- running BIRD on BSD systems. Having high priority device routes for directly
2296 connected networks from the direct protocol protects kernel device routes from
2297 being overwritten or removed by IGP routes during some transient network
2298 conditions, because a lower priority IGP route for the same network is not
2299 exported to the kernel routing table. This is an issue on BSD systems only, as
2300 on Linux systems BIRD cannot change non-BIRD route in the kernel routing table.
2302 <p>There are just few configuration options for the Direct protocol:
2305 <tag>interface <m/pattern [, ...]/</tag>
2306 By default, the Direct protocol will generate device routes for all the
2307 interfaces available. If you want to restrict it to some subset of
2308 interfaces or addresses (e.g. if you're using multiple routing tables
2309 for policy routing and some of the policy domains don't contain all
2310 interfaces), just use this clause. See <ref id="dsc-iface" name="interface">
2311 common option for detailed description. The Direct protocol uses
2312 extended interface clauses.
2314 <tag>check link <m/switch/</tag>
2315 If enabled, a hardware link state (reported by OS) is taken into
2316 consideration. Routes for directly connected networks are generated only
2317 if link up is reported and they are withdrawn when link disappears
2318 (e.g., an ethernet cable is unplugged). Default value is no.
2321 <p>Direct device routes don't contain any specific attributes.
2323 <p>Example config might look like this:
2327 interface "-arc*", "*"; # Exclude the ARCnets
2334 <p>The Kernel protocol is not a real routing protocol. Instead of communicating
2335 with other routers in the network, it performs synchronization of BIRD's routing
2336 tables with the OS kernel. Basically, it sends all routing table updates to the
2337 kernel and from time to time it scans the kernel tables to see whether some
2338 routes have disappeared (for example due to unnoticed up/down transition of an
2339 interface) or whether an `alien' route has been added by someone else (depending
2340 on the <cf/learn/ switch, such routes are either ignored or accepted to our
2343 <p>Unfortunately, there is one thing that makes the routing table synchronization
2344 a bit more complicated. In the kernel routing table there are also device routes
2345 for directly connected networks. These routes are usually managed by OS itself
2346 (as a part of IP address configuration) and we don't want to touch that. They
2347 are completely ignored during the scan of the kernel tables and also the export
2348 of device routes from BIRD tables to kernel routing tables is restricted to
2349 prevent accidental interference. This restriction can be disabled using
2350 <cf/device routes/ switch.
2352 <p>If your OS supports only a single routing table, you can configure only one
2353 instance of the Kernel protocol. If it supports multiple tables (in order to
2354 allow policy routing; such an OS is for example Linux), you can run as many
2355 instances as you want, but each of them must be connected to a different BIRD
2356 routing table and to a different kernel table.
2358 <p>Because the kernel protocol is partially integrated with the connected
2359 routing table, there are two limitations - it is not possible to connect more
2360 kernel protocols to the same routing table and changing route destination
2361 (gateway) in an export filter of a kernel protocol does not work. Both
2362 limitations can be overcome using another routing table and the pipe protocol.
2364 <sect1>Configuration
2367 <tag>persist <m/switch/</tag>
2368 Tell BIRD to leave all its routes in the routing tables when it exits
2369 (instead of cleaning them up).
2371 <tag>scan time <m/number/</tag>
2372 Time in seconds between two consecutive scans of the kernel routing
2375 <tag>learn <m/switch/</tag>
2376 Enable learning of routes added to the kernel routing tables by other
2377 routing daemons or by the system administrator. This is possible only on
2378 systems which support identification of route authorship.
2380 <tag>device routes <m/switch/</tag>
2381 Enable export of device routes to the kernel routing table. By default,
2382 such routes are rejected (with the exception of explicitly configured
2383 device routes from the static protocol) regardless of the export filter
2384 to protect device routes in kernel routing table (managed by OS itself)
2385 from accidental overwriting or erasing.
2387 <tag>kernel table <m/number/</tag>
2388 Select which kernel table should this particular instance of the Kernel
2389 protocol work with. Available only on systems supporting multiple
2392 <tag>metric <m/number/</tag> (Linux)
2393 Use specified value as a kernel metric (priority) for all routes sent to
2394 the kernel. When multiple routes for the same network are in the kernel
2395 routing table, the Linux kernel chooses one with lower metric. Also,
2396 routes with different metrics do not clash with each other, therefore
2397 using dedicated metric value is a reliable way to avoid overwriting
2398 routes from other sources (e.g. kernel device routes). Metric 0 has a
2399 special meaning of undefined metric, in which either OS default is used,
2400 or per-route metric can be set using <cf/krt_metric/ attribute. Default:
2403 <tag>graceful restart <m/switch/</tag>
2404 Participate in graceful restart recovery. If this option is enabled and
2405 a graceful restart recovery is active, the Kernel protocol will defer
2406 synchronization of routing tables until the end of the recovery. Note
2407 that import of kernel routes to BIRD is not affected.
2409 <tag>merge paths <M>switch</M> [limit <M>number</M>]</tag>
2410 Usually, only best routes are exported to the kernel protocol. With path
2411 merging enabled, both best routes and equivalent non-best routes are
2412 merged during export to generate one ECMP (equal-cost multipath) route
2413 for each network. This is useful e.g. for BGP multipath. Note that best
2414 routes are still pivotal for route export (responsible for most
2415 properties of resulting ECMP routes), while exported non-best routes are
2416 responsible just for additional multipath next hops. This option also
2417 allows to specify a limit on maximal number of nexthops in one route. By
2418 default, multipath merging is disabled. If enabled, default value of the
2424 <p>The Kernel protocol defines several attributes. These attributes are
2425 translated to appropriate system (and OS-specific) route attributes. We support
2429 <tag>int <cf/krt_source/</tag>
2430 The original source of the imported kernel route. The value is
2431 system-dependent. On Linux, it is a value of the protocol field of the
2432 route. See /etc/iproute2/rt_protos for common values. On BSD, it is
2433 based on STATIC and PROTOx flags. The attribute is read-only.
2435 <tag>int <cf/krt_metric/</tag> (Linux)
2436 The kernel metric of the route. When multiple same routes are in a
2437 kernel routing table, the Linux kernel chooses one with lower metric.
2438 Note that preferred way to set kernel metric is to use protocol option
2439 <cf/metric/, unless per-route metric values are needed.
2441 <tag>ip <cf/krt_prefsrc/</tag> (Linux)
2442 The preferred source address. Used in source address selection for
2443 outgoing packets. Has to be one of the IP addresses of the router.
2445 <tag>int <cf/krt_realm/</tag> (Linux)
2446 The realm of the route. Can be used for traffic classification.
2448 <tag>int <cf/krt_scope/</tag> (Linux IPv4)
2449 The scope of the route. Valid values are 0-254, although Linux kernel
2450 may reject some values depending on route type and nexthop. It is
2451 supposed to represent `indirectness' of the route, where nexthops of
2452 routes are resolved through routes with a higher scope, but in current
2453 kernels anything below <it/link/ (253) is treated as <it/global/ (0).
2454 When not present, global scope is implied for all routes except device
2455 routes, where link scope is used by default.
2458 <p>In Linux, there is also a plenty of obscure route attributes mostly focused
2459 on tuning TCP performance of local connections. BIRD supports most of these
2460 attributes, see Linux or iproute2 documentation for their meaning. Attributes
2461 <cf/krt_lock_*/ and <cf/krt_feature_*/ have type bool, others have type int.
2462 Supported attributes are:
2464 <cf/krt_mtu/, <cf/krt_lock_mtu/, <cf/krt_window/, <cf/krt_lock_window/,
2465 <cf/krt_rtt/, <cf/krt_lock_rtt/, <cf/krt_rttvar/, <cf/krt_lock_rttvar/,
2466 <cf/krt_sstresh/, <cf/krt_lock_sstresh/, <cf/krt_cwnd/, <cf/krt_lock_cwnd/,
2467 <cf/krt_advmss/, <cf/krt_lock_advmss/, <cf/krt_reordering/, <cf/krt_lock_reordering/,
2468 <cf/krt_hoplimit/, <cf/krt_lock_hoplimit/, <cf/krt_rto_min/, <cf/krt_lock_rto_min/,
2469 <cf/krt_initcwnd/, <cf/krt_initrwnd/, <cf/krt_quickack/,
2470 <cf/krt_feature_ecn/, <cf/krt_feature_allfrag/
2474 <p>A simple configuration can look this way:
2482 <p>Or for a system with two routing tables:
2485 protocol kernel { # Primary routing table
2486 learn; # Learn alien routes from the kernel
2487 persist; # Don't remove routes on bird shutdown
2488 scan time 10; # Scan kernel routing table every 10 seconds
2493 protocol kernel { # Secondary routing table
2505 <p>Open Shortest Path First (OSPF) is a quite complex interior gateway
2506 protocol. The current IPv4 version (OSPFv2) is defined in RFC 2328
2507 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt">
2508 and the current IPv6 version (OSPFv3) is defined in RFC 5340
2509 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt">
2510 It's a link state (a.k.a. shortest path first) protocol -- each router maintains
2511 a database describing the autonomous system's topology. Each participating
2512 router has an identical copy of the database and all routers run the same
2513 algorithm calculating a shortest path tree with themselves as a root. OSPF
2514 chooses the least cost path as the best path.
2516 <p>In OSPF, the autonomous system can be split to several areas in order to
2517 reduce the amount of resources consumed for exchanging the routing information
2518 and to protect the other areas from incorrect routing data. Topology of the area
2519 is hidden to the rest of the autonomous system.
2521 <p>Another very important feature of OSPF is that it can keep routing information
2522 from other protocols (like Static or BGP) in its link state database as external
2523 routes. Each external route can be tagged by the advertising router, making it
2524 possible to pass additional information between routers on the boundary of the
2527 <p>OSPF quickly detects topological changes in the autonomous system (such as
2528 router interface failures) and calculates new loop-free routes after a short
2529 period of convergence. Only a minimal amount of routing traffic is involved.
2531 <p>Each router participating in OSPF routing periodically sends Hello messages
2532 to all its interfaces. This allows neighbors to be discovered dynamically. Then
2533 the neighbors exchange theirs parts of the link state database and keep it
2534 identical by flooding updates. The flooding process is reliable and ensures that
2535 each router detects all changes.
2537 <sect1>Configuration
2539 <p>In the main part of configuration, there can be multiple definitions of OSPF
2540 areas, each with a different id. These definitions includes many other switches
2541 and multiple definitions of interfaces. Definition of interface may contain many
2542 switches and constant definitions and list of neighbors on nonbroadcast
2546 protocol ospf <name> {
2547 rfc1583compat <switch>;
2548 instance id <num>;
2549 stub router <switch>;
2551 ecmp <switch> [limit <num>];
2552 merge external <switch>;
2556 summary <switch>;
2557 default nssa <switch>;
2558 default cost <num>;
2559 default cost2 <num>;
2560 translator <switch>;
2561 translator stability <num>;
2565 <prefix> hidden;
2569 <prefix> hidden;
2570 <prefix> tag <num>;
2572 stubnet <prefix>;
2573 stubnet <prefix> {
2574 hidden <switch>;
2575 summary <switch>;
2578 interface <interface pattern> [instance <num>] {
2580 stub <switch>;
2583 retransmit <num>;
2584 priority <num>;
2586 dead count <num>;
2588 secondary <switch>;
2589 rx buffer [normal|large|<num>];
2590 tx length <num>;
2591 type [broadcast|bcast|pointopoint|ptp|
2592 nonbroadcast|nbma|pointomultipoint|ptmp];
2593 link lsa suppression <switch>;
2594 strict nonbroadcast <switch>;
2595 real broadcast <switch>;
2596 ptp netmask <switch>;
2597 check link <switch>;
2599 ecmp weight <num>;
2600 ttl security [<switch>; | tx only]
2601 tx class|dscp <num>;
2602 tx priority <num>;
2603 authentication [none|simple|cryptographic];
2604 password "<text>";
2605 password "<text>" {
2607 generate from "<date>";
2608 generate to "<date>";
2609 accept from "<date>";
2610 accept to "<date>";
2614 <ip> eligible;
2617 virtual link <id> [instance <num>] {
2619 retransmit <num>;
2621 dead count <num>;
2623 authentication [none|simple|cryptographic];
2624 password "<text>";
2631 <tag>rfc1583compat <M>switch</M></tag>
2632 This option controls compatibility of routing table calculation with
2633 RFC 1583 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">.
2634 Default value is no.
2636 <tag>instance id <m/num/</tag>
2637 When multiple OSPF protocol instances are active on the same links, they
2638 should use different instance IDs to distinguish their packets. Although
2639 it could be done on per-interface basis, it is often preferred to set
2640 one instance ID to whole OSPF domain/topology (e.g., when multiple
2641 instances are used to represent separate logical topologies on the same
2642 physical network). This option specifies the default instance ID for all
2643 interfaces of the OSPF instance. Note that this option, if used, must
2644 precede interface definitions. Default value is 0.
2646 <tag>stub router <M>switch</M></tag>
2647 This option configures the router to be a stub router, i.e., a router
2648 that participates in the OSPF topology but does not allow transit
2649 traffic. In OSPFv2, this is implemented by advertising maximum metric
2650 for outgoing links. In OSPFv3, the stub router behavior is announced by
2651 clearing the R-bit in the router LSA. See RFC 6987
2652 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6987.txt"> for
2653 details. Default value is no.
2655 <tag>tick <M>num</M></tag>
2656 The routing table calculation and clean-up of areas' databases is not
2657 performed when a single link state change arrives. To lower the CPU
2658 utilization, it's processed later at periodical intervals of <m/num/
2659 seconds. The default value is 1.
2661 <tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
2662 This option specifies whether OSPF is allowed to generate ECMP
2663 (equal-cost multipath) routes. Such routes are used when there are
2664 several directions to the destination, each with the same (computed)
2665 cost. This option also allows to specify a limit on maximum number of
2666 nexthops in one route. By default, ECMP is disabled. If enabled,
2667 default value of the limit is 16.
2669 <tag>merge external <M>switch</M></tag>
2670 This option specifies whether OSPF should merge external routes from
2671 different routers/LSAs for the same destination. When enabled together
2672 with <cf/ecmp/, equal-cost external routes will be combined to multipath
2673 routes in the same way as regular routes. When disabled, external routes
2674 from different LSAs are treated as separate even if they represents the
2675 same destination. Default value is no.
2677 <tag>area <M>id</M></tag>
2678 This defines an OSPF area with given area ID (an integer or an IPv4
2679 address, similarly to a router ID). The most important area is the
2680 backbone (ID 0) to which every other area must be connected.
2683 This option configures the area to be a stub area. External routes are
2684 not flooded into stub areas. Also summary LSAs can be limited in stub
2685 areas (see option <cf/summary/). By default, the area is not a stub
2689 This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA
2690 is a variant of a stub area which allows a limited way of external route
2691 propagation. Global external routes are not propagated into a NSSA, but
2692 an external route can be imported into NSSA as a (area-wide) NSSA-LSA
2693 (and possibly translated and/or aggregated on area boundary). By
2694 default, the area is not NSSA.
2696 <tag>summary <M>switch</M></tag>
2697 This option controls propagation of summary LSAs into stub or NSSA
2698 areas. If enabled, summary LSAs are propagated as usual, otherwise just
2699 the default summary route (0.0.0.0/0) is propagated (this is sometimes
2700 called totally stubby area). If a stub area has more area boundary
2701 routers, propagating summary LSAs could lead to more efficient routing
2702 at the cost of larger link state database. Default value is no.
2704 <tag>default nssa <M>switch</M></tag>
2705 When <cf/summary/ option is enabled, default summary route is no longer
2706 propagated to the NSSA. In that case, this option allows to originate
2707 default route as NSSA-LSA to the NSSA. Default value is no.
2709 <tag>default cost <M>num</M></tag>
2710 This option controls the cost of a default route propagated to stub and
2711 NSSA areas. Default value is 1000.
2713 <tag>default cost2 <M>num</M></tag>
2714 When a default route is originated as NSSA-LSA, its cost can use either
2715 type 1 or type 2 metric. This option allows to specify the cost of a
2716 default route in type 2 metric. By default, type 1 metric (option
2717 <cf/default cost/) is used.
2719 <tag>translator <M>switch</M></tag>
2720 This option controls translation of NSSA-LSAs into external LSAs. By
2721 default, one translator per NSSA is automatically elected from area
2722 boundary routers. If enabled, this area boundary router would
2723 unconditionally translate all NSSA-LSAs regardless of translator
2724 election. Default value is no.
2726 <tag>translator stability <M>num</M></tag>
2727 This option controls the translator stability interval (in seconds).
2728 When the new translator is elected, the old one keeps translating until
2729 the interval is over. Default value is 40.
2731 <tag>networks { <m/set/ }</tag>
2732 Definition of area IP ranges. This is used in summary LSA origination.
2733 Hidden networks are not propagated into other areas.
2735 <tag>external { <m/set/ }</tag>
2736 Definition of external area IP ranges for NSSAs. This is used for
2737 NSSA-LSA translation. Hidden networks are not translated into external
2738 LSAs. Networks can have configured route tag.
2740 <tag>stubnet <m/prefix/ { <m/options/ }</tag>
2741 Stub networks are networks that are not transit networks between OSPF
2742 routers. They are also propagated through an OSPF area as a part of a
2743 link state database. By default, BIRD generates a stub network record
2744 for each primary network address on each OSPF interface that does not
2745 have any OSPF neighbors, and also for each non-primary network address
2746 on each OSPF interface. This option allows to alter a set of stub
2747 networks propagated by this router.
2749 Each instance of this option adds a stub network with given network
2750 prefix to the set of propagated stub network, unless option <cf/hidden/
2751 is used. It also suppresses default stub networks for given network
2752 prefix. When option <cf/summary/ is used, also default stub networks
2753 that are subnetworks of given stub network are suppressed. This might be
2754 used, for example, to aggregate generated stub networks.
2756 <tag>interface <M>pattern</M> [instance <m/num/]</tag>
2757 Defines that the specified interfaces belong to the area being defined.
2758 See <ref id="dsc-iface" name="interface"> common option for detailed
2759 description. In OSPFv2, extended interface clauses are used, because
2760 each network prefix is handled as a separate virtual interface.
2762 You can specify alternative instance ID for the interface definition,
2763 therefore it is possible to have several instances of that interface
2764 with different options or even in different areas. For OSPFv2,
2765 instance ID support is an extension (RFC 6549
2766 <htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6549.txt">) and is
2767 supposed to be set per-protocol. For OSPFv3, it is an integral feature.
2769 <tag>virtual link <M>id</M> [instance <m/num/]</tag>
2770 Virtual link to router with the router id. Virtual link acts as a
2771 point-to-point interface belonging to backbone. The actual area is used
2772 as a transport area. This item cannot be in the backbone. Like with
2773 <cf/interface/ option, you could also use several virtual links to one
2774 destination with different instance IDs.
2776 <tag>cost <M>num</M></tag>
2777 Specifies output cost (metric) of an interface. Default value is 10.
2779 <tag>stub <M>switch</M></tag>
2780 If set to interface it does not listen to any packet and does not send
2781 any hello. Default value is no.
2783 <tag>hello <M>num</M></tag>
2784 Specifies interval in seconds between sending of Hello messages. Beware,
2785 all routers on the same network need to have the same hello interval.
2786 Default value is 10.
2788 <tag>poll <M>num</M></tag>
2789 Specifies interval in seconds between sending of Hello messages for some
2790 neighbors on NBMA network. Default value is 20.
2792 <tag>retransmit <M>num</M></tag>
2793 Specifies interval in seconds between retransmissions of unacknowledged
2794 updates. Default value is 5.
2796 <tag>priority <M>num</M></tag>
2797 On every multiple access network (e.g., the Ethernet) Designated Router
2798 and Backup Designated router are elected. These routers have some special
2799 functions in the flooding process. Higher priority increases preferences
2800 in this election. Routers with priority 0 are not eligible. Default
2803 <tag>wait <M>num</M></tag>
2804 After start, router waits for the specified number of seconds between
2805 starting election and building adjacency. Default value is 4*<m/hello/.
2807 <tag>dead count <M>num</M></tag>
2808 When the router does not receive any messages from a neighbor in
2809 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
2811 <tag>dead <M>num</M></tag>
2812 When the router does not receive any messages from a neighbor in
2813 <m/dead/ seconds, it will consider the neighbor down. If both directives
2814 <cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precedence.
2816 <tag>secondary <M>switch</M></tag>
2817 On BSD systems, older versions of BIRD supported OSPFv2 only for the
2818 primary IP address of an interface, other IP ranges on the interface
2819 were handled as stub networks. Since v1.4.1, regular operation on
2820 secondary IP addresses is supported, but disabled by default for
2821 compatibility. This option allows to enable it. The option is a
2822 transitional measure, will be removed in the next major release as the
2823 behavior will be changed. On Linux systems, the option is irrelevant, as
2824 operation on non-primary addresses is already the regular behavior.
2826 <tag>rx buffer <M>num</M></tag>
2827 This option allows to specify the size of buffers used for packet
2828 processing. The buffer size should be bigger than maximal size of any
2829 packets. By default, buffers are dynamically resized as needed, but a
2830 fixed value could be specified. Value <cf/large/ means maximal allowed
2831 packet size - 65535.
2833 <tag>tx length <M>num</M></tag>
2834 Transmitted OSPF messages that contain large amount of information are
2835 segmented to separate OSPF packets to avoid IP fragmentation. This
2836 option specifies the soft ceiling for the length of generated OSPF
2837 packets. Default value is the MTU of the network interface. Note that
2838 larger OSPF packets may still be generated if underlying OSPF messages
2839 cannot be splitted (e.g. when one large LSA is propagated).
2841 <tag>type broadcast|bcast</tag>
2842 BIRD detects a type of a connected network automatically, but sometimes
2843 it's convenient to force use of a different type manually. On broadcast
2844 networks (like ethernet), flooding and Hello messages are sent using
2845 multicasts (a single packet for all the neighbors). A designated router
2846 is elected and it is responsible for synchronizing the link-state
2847 databases and originating network LSAs. This network type cannot be used
2848 on physically NBMA networks and on unnumbered networks (networks without
2851 <tag>type pointopoint|ptp</tag>
2852 Point-to-point networks connect just 2 routers together. No election is
2853 performed and no network LSA is originated, which makes it simpler and
2854 faster to establish. This network type is useful not only for physically
2855 PtP ifaces (like PPP or tunnels), but also for broadcast networks used
2856 as PtP links. This network type cannot be used on physically NBMA
2859 <tag>type nonbroadcast|nbma</tag>
2860 On NBMA networks, the packets are sent to each neighbor separately
2861 because of lack of multicast capabilities. Like on broadcast networks,
2862 a designated router is elected, which plays a central role in propagation
2863 of LSAs. This network type cannot be used on unnumbered networks.
2865 <tag>type pointomultipoint|ptmp</tag>
2866 This is another network type designed to handle NBMA networks. In this
2867 case the NBMA network is treated as a collection of PtP links. This is
2868 useful if not every pair of routers on the NBMA network has direct
2869 communication, or if the NBMA network is used as an (possibly
2870 unnumbered) PtP link.
2872 <tag>link lsa suppression <m/switch/</tag>
2873 In OSPFv3, link LSAs are generated for each link, announcing link-local
2874 IPv6 address of the router to its local neighbors. These are useless on
2875 PtP or PtMP networks and this option allows to suppress the link LSA
2876 origination for such interfaces. The option is ignored on other than PtP
2877 or PtMP interfaces. Default value is no.
2879 <tag>strict nonbroadcast <m/switch/</tag>
2880 If set, don't send hello to any undefined neighbor. This switch is
2881 ignored on other than NBMA or PtMP interfaces. Default value is no.
2883 <tag>real broadcast <m/switch/</tag>
2884 In <cf/type broadcast/ or <cf/type ptp/ network configuration, OSPF
2885 packets are sent as IP multicast packets. This option changes the
2886 behavior to using old-fashioned IP broadcast packets. This may be useful
2887 as a workaround if IP multicast for some reason does not work or does
2888 not work reliably. This is a non-standard option and probably is not
2889 interoperable with other OSPF implementations. Default value is no.
2891 <tag>ptp netmask <m/switch/</tag>
2892 In <cf/type ptp/ network configurations, OSPFv2 implementations should
2893 ignore received netmask field in hello packets and should send hello
2894 packets with zero netmask field on unnumbered PtP links. But some OSPFv2
2895 implementations perform netmask checking even for PtP links. This option
2896 specifies whether real netmask will be used in hello packets on <cf/type
2897 ptp/ interfaces. You should ignore this option unless you meet some
2898 compatibility problems related to this issue. Default value is no for
2899 unnumbered PtP links, yes otherwise.
2901 <tag>check link <M>switch</M></tag>
2902 If set, a hardware link state (reported by OS) is taken into consideration.
2903 When a link disappears (e.g. an ethernet cable is unplugged), neighbors
2904 are immediately considered unreachable and only the address of the iface
2905 (instead of whole network prefix) is propagated. It is possible that
2906 some hardware drivers or platforms do not implement this feature.
2907 Default value is no.
2909 <tag>bfd <M>switch</M></tag>
2910 OSPF could use BFD protocol as an advisory mechanism for neighbor
2911 liveness and failure detection. If enabled, BIRD setups a BFD session
2912 for each OSPF neighbor and tracks its liveness by it. This has an
2913 advantage of an order of magnitude lower detection times in case of
2914 failure. Note that BFD protocol also has to be configured, see
2915 <ref id="sect-bfd" name="BFD"> section for details. Default value is no.
2917 <tag>ttl security [<m/switch/ | tx only]</tag>
2918 TTL security is a feature that protects routing protocols from remote
2919 spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
2920 destined to neighbors. Because TTL is decremented when packets are
2921 forwarded, it is non-trivial to spoof packets with TTL 255 from remote
2922 locations. Note that this option would interfere with OSPF virtual
2925 If this option is enabled, the router will send OSPF packets with TTL
2926 255 and drop received packets with TTL less than 255. If this option si
2927 set to <cf/tx only/, TTL 255 is used for sent packets, but is not
2928 checked for received packets. Default value is no.
2930 <tag>tx class|dscp|priority <m/num/</tag>
2931 These options specify the ToS/DiffServ/Traffic class/Priority of the
2932 outgoing OSPF packets. See <ref id="dsc-prio" name="tx class"> common
2933 option for detailed description.
2935 <tag>ecmp weight <M>num</M></tag>
2936 When ECMP (multipath) routes are allowed, this value specifies a
2937 relative weight used for nexthops going through the iface. Allowed
2938 values are 1-256. Default value is 1.
2940 <tag>authentication none</tag>
2941 No passwords are sent in OSPF packets. This is the default value.
2943 <tag>authentication simple</tag>
2944 Every packet carries 8 bytes of password. Received packets lacking this
2945 password are ignored. This authentication mechanism is very weak.
2947 <tag>authentication cryptographic</tag>
2948 16-byte long MD5 digest is appended to every packet. For the digest
2949 generation 16-byte long passwords are used. Those passwords are not sent
2950 via network, so this mechanism is quite secure. Packets can still be
2951 read by an attacker.
2953 <tag>password "<M>text</M>"</tag>
2954 An 8-byte or 16-byte password used for authentication. See
2955 <ref id="dsc-pass" name="password"> common option for detailed
2958 <tag>neighbors { <m/set/ } </tag>
2959 A set of neighbors to which Hello messages on NBMA or PtMP networks are
2960 to be sent. For NBMA networks, some of them could be marked as eligible.
2961 In OSPFv3, link-local addresses should be used, using global ones is
2962 possible, but it is nonstandard and might be problematic. And definitely,
2963 link-local and global addresses should not be mixed.
2968 <p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
2970 <p>Metric is ranging from 1 to infinity (65535). External routes use
2971 <cf/metric type 1/ or <cf/metric type 2/. A <cf/metric of type 1/ is comparable
2972 with internal <cf/metric/, a <cf/metric of type 2/ is always longer than any
2973 <cf/metric of type 1/ or any <cf/internal metric/. <cf/Internal metric/ or
2974 <cf/metric of type 1/ is stored in attribute <cf/ospf_metric1/, <cf/metric type
2975 2/ is stored in attribute <cf/ospf_metric2/. If you specify both metrics only
2978 <p>Each external route can also carry attribute <cf/ospf_tag/ which is a 32-bit
2979 integer which is used when exporting routes to other protocols; otherwise, it
2980 doesn't affect routing inside the OSPF domain at all. The fourth attribute
2981 <cf/ospf_router_id/ is a router ID of the router advertising that route /
2982 network. This attribute is read-only. Default is <cf/ospf_metric2 = 10000/ and
2988 protocol ospf MyOSPF {
2992 if source = RTS_BGP then {
3004 authentication simple;
3009 authentication cryptographic;
3012 generate to "22-04-2003 11:00:06";
3013 accept from "17-01-2001 12:01:05";
3017 generate to "22-07-2005 17:03:21";
3018 accept from "22-02-2001 11:34:06";
3031 172.16.2.0/24 hidden;
3033 interface "-arc0" , "arc*" {
3035 authentication none;
3036 strict nonbroadcast yes;
3041 192.168.120.1 eligible;
3055 <p>The Pipe protocol serves as a link between two routing tables, allowing
3056 routes to be passed from a table declared as primary (i.e., the one the pipe is
3057 connected to using the <cf/table/ configuration keyword) to the secondary one
3058 (declared using <cf/peer table/) and vice versa, depending on what's allowed by
3059 the filters. Export filters control export of routes from the primary table to
3060 the secondary one, import filters control the opposite direction.
3062 <p>The Pipe protocol may work in the transparent mode mode or in the opaque
3063 mode. In the transparent mode, the Pipe protocol retransmits all routes from
3064 one table to the other table, retaining their original source and attributes.
3065 If import and export filters are set to accept, then both tables would have
3066 the same content. The transparent mode is the default mode.
3068 <p>In the opaque mode, the Pipe protocol retransmits optimal route from one
3069 table to the other table in a similar way like other protocols send and receive
3070 routes. Retransmitted route will have the source set to the Pipe protocol, which
3071 may limit access to protocol specific route attributes. This mode is mainly for
3072 compatibility, it is not suggested for new configs. The mode can be changed by
3075 <p>The primary use of multiple routing tables and the Pipe protocol is for
3076 policy routing, where handling of a single packet doesn't depend only on its
3077 destination address, but also on its source address, source interface, protocol
3078 type and other similar parameters. In many systems (Linux being a good example),
3079 the kernel allows to enforce routing policies by defining routing rules which
3080 choose one of several routing tables to be used for a packet according to its
3081 parameters. Setting of these rules is outside the scope of BIRD's work (on
3082 Linux, you can use the <tt/ip/ command), but you can create several routing
3083 tables in BIRD, connect them to the kernel ones, use filters to control which
3084 routes appear in which tables and also you can employ the Pipe protocol for
3085 exporting a selected subset of one table to another one.
3087 <sect1>Configuration
3090 <tag>peer table <m/table/</tag>
3091 Defines secondary routing table to connect to. The primary one is
3092 selected by the <cf/table/ keyword.
3094 <tag>mode opaque|transparent</tag>
3095 Specifies the mode for the pipe to work in. Default is transparent.
3100 <p>The Pipe protocol doesn't define any route attributes.
3104 <p>Let's consider a router which serves as a boundary router of two different
3105 autonomous systems, each of them connected to a subset of interfaces of the
3106 router, having its own exterior connectivity and wishing to use the other AS as
3107 a backup connectivity in case of outage of its own exterior line.
3109 <p>Probably the simplest solution to this situation is to use two routing tables
3110 (we'll call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that
3111 packets having arrived from interfaces belonging to the first AS will be routed
3112 according to <cf/as1/ and similarly for the second AS. Thus we have split our
3113 router to two logical routers, each one acting on its own routing table, having
3114 its own routing protocols on its own interfaces. In order to use the other AS's
3115 routes for backup purposes, we can pass the routes between the tables through a
3116 Pipe protocol while decreasing their preferences and correcting their BGP paths
3117 to reflect the AS boundary crossing.
3120 table as1; # Define the tables
3123 protocol kernel kern1 { # Synchronize them with the kernel
3128 protocol kernel kern2 {
3133 protocol bgp bgp1 { # The outside connections
3136 neighbor 192.168.0.1 as 1001;
3144 neighbor 10.0.0.1 as 1002;
3149 protocol pipe { # The Pipe
3153 if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks
3154 if preference>10 then preference = preference-10;
3155 if source=RTS_BGP then bgp_path.prepend(1);
3161 if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks
3162 if preference>10 then preference = preference-10;
3163 if source=RTS_BGP then bgp_path.prepend(2);
3176 <p>The RAdv protocol is an implementation of Router Advertisements, which are
3177 used in the IPv6 stateless autoconfiguration. IPv6 routers send (in irregular
3178 time intervals or as an answer to a request) advertisement packets to connected
3179 networks. These packets contain basic information about a local network (e.g. a
3180 list of network prefixes), which allows network hosts to autoconfigure network
3181 addresses and choose a default route. BIRD implements router behavior as defined
3182 in RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">
3183 and also the DNS extensions from
3184 RFC 6106<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt">.
3186 <sect1>Configuration
3188 <p>There are several classes of definitions in RAdv configuration -- interface
3189 definitions, prefix definitions and DNS definitions:
3192 <tag>interface <m/pattern [, ...]/ { <m/options/ }</tag>
3193 Interface definitions specify a set of interfaces on which the
3194 protocol is activated and contain interface specific options.
3195 See <ref id="dsc-iface" name="interface"> common options for
3196 detailed description.
3198 <tag>prefix <m/prefix/ { <m/options/ }</tag>
3199 Prefix definitions allow to modify a list of advertised prefixes. By
3200 default, the advertised prefixes are the same as the network prefixes
3201 assigned to the interface. For each network prefix, the matching prefix
3202 definition is found and its options are used. If no matching prefix
3203 definition is found, the prefix is used with default options.
3205 Prefix definitions can be either global or interface-specific. The
3206 second ones are part of interface options. The prefix definition
3207 matching is done in the first-match style, when interface-specific
3208 definitions are processed before global definitions. As expected, the
3209 prefix definition is matching if the network prefix is a subnet of the
3210 prefix in prefix definition.
3212 <tag>rdnss { <m/options/ }</tag>
3213 RDNSS definitions allow to specify a list of advertised recursive DNS
3214 servers together with their options. As options are seldom necessary,
3215 there is also a short variant <cf>rdnss <m/address/</cf> that just
3216 specifies one DNS server. Multiple definitions are cumulative. RDNSS
3217 definitions may also be interface-specific when used inside interface
3218 options. By default, interface uses both global and interface-specific
3219 options, but that can be changed by <cf/rdnss local/ option.
3221 <tag>dnssl { <m/options/ }</tag>
3222 DNSSL definitions allow to specify a list of advertised DNS search
3223 domains together with their options. Like <cf/rdnss/ above, multiple
3224 definitions are cumulative, they can be used also as interface-specific
3225 options and there is a short variant <cf>dnssl <m/domain/</cf> that just
3226 specifies one DNS search domain.
3228 <label id="dsc-trigger"> <tag>trigger <m/prefix/</tag>
3229 RAdv protocol could be configured to change its behavior based on
3230 availability of routes. When this option is used, the protocol waits in
3231 suppressed state until a <it/trigger route/ (for the specified network)
3232 is exported to the protocol, the protocol also returnsd to suppressed
3233 state if the <it/trigger route/ disappears. Note that route export
3234 depends on specified export filter, as usual. This option could be used,
3235 e.g., for handling failover in multihoming scenarios.
3237 During suppressed state, router advertisements are generated, but with
3238 some fields zeroed. Exact behavior depends on which fields are zeroed,
3239 this can be configured by <cf/sensitive/ option for appropriate
3240 fields. By default, just <cf/default lifetime/ (also called <cf/router
3241 lifetime/) is zeroed, which means hosts cannot use the router as a
3242 default router. <cf/preferred lifetime/ and <cf/valid lifetime/ could
3243 also be configured as <cf/sensitive/ for a prefix, which would cause
3244 autoconfigured IPs to be deprecated or even removed.
3247 <p>Interface specific options:
3250 <tag>max ra interval <m/expr/</tag>
3251 Unsolicited router advertisements are sent in irregular time intervals.
3252 This option specifies the maximum length of these intervals, in seconds.
3253 Valid values are 4-1800. Default: 600
3255 <tag>min ra interval <m/expr/</tag>
3256 This option specifies the minimum length of that intervals, in seconds.
3257 Must be at least 3 and at most 3/4 * <cf/max ra interval/. Default:
3258 about 1/3 * <cf/max ra interval/.
3260 <tag>min delay <m/expr/</tag>
3261 The minimum delay between two consecutive router advertisements, in
3264 <tag>managed <m/switch/</tag>
3265 This option specifies whether hosts should use DHCPv6 for IP address
3266 configuration. Default: no
3268 <tag>other config <m/switch/</tag>
3269 This option specifies whether hosts should use DHCPv6 to receive other
3270 configuration information. Default: no
3272 <tag>link mtu <m/expr/</tag>
3273 This option specifies which value of MTU should be used by hosts. 0
3274 means unspecified. Default: 0
3276 <tag>reachable time <m/expr/</tag>
3277 This option specifies the time (in milliseconds) how long hosts should
3278 assume a neighbor is reachable (from the last confirmation). Maximum is
3279 3600000, 0 means unspecified. Default 0.
3281 <tag>retrans timer <m/expr/</tag>
3282 This option specifies the time (in milliseconds) how long hosts should
3283 wait before retransmitting Neighbor Solicitation messages. 0 means
3284 unspecified. Default 0.
3286 <tag>current hop limit <m/expr/</tag>
3287 This option specifies which value of Hop Limit should be used by
3288 hosts. Valid values are 0-255, 0 means unspecified. Default: 64
3290 <tag>default lifetime <m/expr/ [sensitive <m/switch/]</tag>
3291 This option specifies the time (in seconds) how long (after the receipt
3292 of RA) hosts may use the router as a default router. 0 means do not use
3293 as a default router. For <cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">.
3294 Default: 3 * <cf/max ra interval/, <cf/sensitive/ yes.
3296 <tag>default preference low|medium|high</tag>
3297 This option specifies the Default Router Preference value to advertise
3298 to hosts. Default: medium.
3300 <tag>rdnss local <m/switch/</tag>
3301 Use only local (interface-specific) RDNSS definitions for this
3302 interface. Otherwise, both global and local definitions are used. Could
3303 also be used to disable RDNSS for given interface if no local definitons
3304 are specified. Default: no.
3306 <tag>dnssl local <m/switch/</tag>
3307 Use only local DNSSL definitions for this interface. See <cf/rdnss local/
3308 option above. Default: no.
3312 <p>Prefix specific options:
3315 <tag>skip <m/switch/</tag>
3316 This option allows to specify that given prefix should not be
3317 advertised. This is useful for making exceptions from a default policy
3318 of advertising all prefixes. Note that for withdrawing an already
3319 advertised prefix it is more useful to advertise it with zero valid
3320 lifetime. Default: no
3322 <tag>onlink <m/switch/</tag>
3323 This option specifies whether hosts may use the advertised prefix for
3324 onlink determination. Default: yes
3326 <tag>autonomous <m/switch/</tag>
3327 This option specifies whether hosts may use the advertised prefix for
3328 stateless autoconfiguration. Default: yes
3330 <tag>valid lifetime <m/expr/ [sensitive <m/switch/]</tag>
3331 This option specifies the time (in seconds) how long (after the
3332 receipt of RA) the prefix information is valid, i.e., autoconfigured
3333 IP addresses can be assigned and hosts with that IP addresses are
3334 considered directly reachable. 0 means the prefix is no longer
3335 valid. For <cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">.
3336 Default: 86400 (1 day), <cf/sensitive/ no.
3338 <tag>preferred lifetime <m/expr/ [sensitive <m/switch/]</tag>
3339 This option specifies the time (in seconds) how long (after the
3340 receipt of RA) IP addresses generated from the prefix using stateless
3341 autoconfiguration remain preferred. For <cf/sensitive/ option,
3342 see <ref id="dsc-trigger" name="trigger">. Default: 14400 (4 hours),
3347 <p>RDNSS specific options:
3350 <tag>ns <m/address/</tag>
3351 This option specifies one recursive DNS server. Can be used multiple
3352 times for multiple servers. It is mandatory to have at least one
3353 <cf/ns/ option in <cf/rdnss/ definition.
3355 <tag>lifetime [mult] <m/expr/</tag>
3356 This option specifies the time how long the RDNSS information may be
3357 used by clients after the receipt of RA. It is expressed either in
3358 seconds or (when <cf/mult/ is used) in multiples of <cf/max ra
3359 interval/. Note that RDNSS information is also invalidated when
3360 <cf/default lifetime/ expires. 0 means these addresses are no longer
3361 valid DNS servers. Default: 3 * <cf/max ra interval/.
3365 <p>DNSSL specific options:
3368 <tag>domain <m/address/</tag>
3369 This option specifies one DNS search domain. Can be used multiple times
3370 for multiple domains. It is mandatory to have at least one <cf/domain/
3371 option in <cf/dnssl/ definition.
3373 <tag>lifetime [mult] <m/expr/</tag>
3374 This option specifies the time how long the DNSSL information may be
3375 used by clients after the receipt of RA. Details are the same as for
3376 RDNSS <cf/lifetime/ option above. Default: 3 * <cf/max ra interval/.
3385 max ra interval 5; # Fast failover with more routers
3386 managed yes; # Using DHCPv6 on eth2
3388 autonomous off; # So do not autoconfigure any IP
3392 interface "eth*"; # No need for any other options
3394 prefix 2001:0DB8:1234::/48 {
3395 preferred lifetime 0; # Deprecated address range
3398 prefix 2001:0DB8:2000::/48 {
3399 autonomous off; # Do not autoconfigure
3402 rdnss 2001:0DB8:1234::10; # Short form of RDNSS
3406 ns 2001:0DB8:1234::11;
3407 ns 2001:0DB8:1234::12;
3423 <p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol,
3424 where each router broadcasts (to all its neighbors) distances to all networks it
3425 can reach. When a router hears distance to another network, it increments it and
3426 broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some
3427 network goes unreachable, routers keep telling each other that its distance is
3428 the original distance plus 1 (actually, plus interface metric, which is usually
3429 one). After some time, the distance reaches infinity (that's 15 in RIP) and all
3430 routers know that network is unreachable. RIP tries to minimize situations where
3431 counting to infinity is necessary, because it is slow. Due to infinity being 16,
3432 you can't use RIP on networks where maximal distance is higher than 15
3435 <p>BIRD supports RIPv1
3436 (RFC 1058<htmlurl url="http://www.rfc-editor.org/rfc/rfc1058.txt">),
3437 RIPv2 (RFC 2453<htmlurl url="http://www.rfc-editor.org/rfc/rfc2453.txt">),
3438 RIPng (RFC 2080<htmlurl url="http://www.rfc-editor.org/rfc/rfc2080.txt">),
3439 and RIP cryptographic authentication (SHA-1 not implemented)
3440 (RFC 4822<htmlurl url="http://www.rfc-editor.org/rfc/rfc4822.txt">).
3442 <p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow
3443 convergence, big network load and inability to handle larger networks makes it
3444 pretty much obsolete. It is still usable on very small networks.
3446 <sect1>Configuration
3448 <p>RIP configuration consists mainly of common protocol options and interface
3449 definitions, most RIP options are interface specific.
3452 protocol rip [<name>] {
3453 infinity <number>;
3454 ecmp <switch> [limit <number>];
3455 interface <interface pattern> {
3456 metric <number>;
3457 mode multicast|broadcast;
3458 passive <switch>;
3460 port <number>;
3462 split horizon <switch>;
3463 poison reverse <switch>;
3464 check zero <switch>;
3465 update time <number>;
3466 timeout time <number>;
3467 garbage time <number>;
3468 ecmp weight <number>;
3469 ttl security <switch>; | tx only;
3470 tx class|dscp <number>;
3471 tx priority <number>;
3472 rx buffer <number>;
3473 tx length <number>;
3474 check link <switch>;
3475 authentication none|plaintext|cryptographic;
3476 password "<text>";
3477 password "<text>" {
3479 generate from "<date>";
3480 generate to "<date>";
3481 accept from "<date>";
3482 accept to "<date>";
3489 <tag>infinity <M>number</M></tag>
3490 Selects the distance of infinity. Bigger values will make
3491 protocol convergence even slower. The default value is 16.
3493 <tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
3494 This option specifies whether RIP is allowed to generate ECMP
3495 (equal-cost multipath) routes. Such routes are used when there are
3496 several directions to the destination, each with the same (computed)
3497 cost. This option also allows to specify a limit on maximum number of
3498 nexthops in one route. By default, ECMP is disabled. If enabled,
3499 default value of the limit is 16.
3501 <tag>interface <m/pattern [, ...]/ { <m/options/ }</tag>
3502 Interface definitions specify a set of interfaces on which the
3503 protocol is activated and contain interface specific options.
3504 See <ref id="dsc-iface" name="interface"> common options for
3505 detailed description.
3508 <p>Interface specific options:
3511 <tag>metric <m/num/</tag>
3512 This option specifies the metric of the interface. When a route is
3513 received from the interface, its metric is increased by this value
3514 before further processing. Valid values are 1-255, but values higher
3515 than infinity has no further meaning. Default: 1.
3517 <tag>mode multicast|broadcast</tag>
3518 This option selects the mode for RIP to use on the interface. The
3519 default is multicast mode for RIPv2 and broadcast mode for RIPv1.
3520 RIPng always uses the multicast mode.
3522 <tag>passive <m/switch/</tag>
3523 Passive interfaces receive routing updates but do not transmit any
3524 messages. Default: no.
3526 <tag>address <m/ip/</tag>
3527 This option specifies a destination address used for multicast or
3528 broadcast messages, the default is the official RIP (224.0.0.9) or RIPng
3529 (ff02::9) multicast address, or an appropriate broadcast address in the
3532 <tag>port <m/number/</tag>
3533 This option selects an UDP port to operate on, the default is the
3534 official RIP (520) or RIPng (521) port.
3536 <tag>version 1|2</tag>
3537 This option selects the version of RIP used on the interface. For RIPv1,
3538 automatic subnet aggregation is not implemented, only classful network
3539 routes and host routes are propagated. Note that BIRD allows RIPv1 to be
3540 configured with features that are defined for RIPv2 only, like
3541 authentication or using multicast sockets. The default is RIPv2 for IPv4
3542 RIP, the option is not supported for RIPng, as no further versions are
3545 <tag>version only <m/switch/</tag>
3546 Regardless of RIP version configured for the interface, BIRD accepts
3547 incoming packets of any RIP version. This option restrict accepted
3548 packets to the configured version. Default: no.
3550 <tag>split horizon <m/switch/</tag>
3551 Split horizon is a scheme for preventing routing loops. When split
3552 horizon is active, routes are not regularly propagated back to the
3553 interface from which they were received. They are either not propagated
3554 back at all (plain split horizon) or propagated back with an infinity
3555 metric (split horizon with poisoned reverse). Therefore, other routers
3556 on the interface will not consider the router as a part of an
3557 independent path to the destination of the route. Default: yes.
3559 <tag>poison reverse <m/switch/</tag>
3560 When split horizon is active, this option specifies whether the poisoned
3561 reverse variant (propagating routes back with an infinity metric) is
3562 used. The poisoned reverse has some advantages in faster convergence,
3563 but uses more network traffic. Default: yes.
3565 <tag>check zero <m/switch/</tag>
3566 Received RIPv1 packets with non-zero values in reserved fields should
3567 be discarded. This option specifies whether the check is performed or
3568 such packets are just processed as usual. Default: yes.
3570 <tag>update time <m/number/</tag>
3571 Specifies the number of seconds between periodic updates. A lower number
3572 will mean faster convergence but bigger network load. Default: 30.
3574 <tag>timeout time <m/number/</tag>
3575 Specifies the time interval (in seconds) between the last received route
3576 announcement and the route expiration. After that, the network is
3577 considered unreachable, but still is propagated with infinity distance.
3580 <tag>garbage time <m/number/</tag>
3581 Specifies the time interval (in seconds) between the route expiration
3582 and the removal of the unreachable network entry. The garbage interval,
3583 when a route with infinity metric is propagated, is used for both
3584 internal (after expiration) and external (after withdrawal) routes.
3587 <tag>ecmp weight <m/number/</tag>
3588 When ECMP (multipath) routes are allowed, this value specifies a
3589 relative weight used for nexthops going through the iface. Valid
3590 values are 1-256. Default value is 1.
3592 <tag>authentication none|plaintext|cryptographic</tag>
3593 Selects authentication method to be used. <cf/none/ means that packets
3594 are not authenticated at all, <cf/plaintext/ means that a plaintext
3595 password is embedded into each packet, and <cf/cryptographic/ means that
3596 packets are authenticated using a MD5 cryptographic hash. If you set
3597 authentication to not-none, it is a good idea to add <cf>password</cf>
3598 section. Default: none.
3600 <tag>password "<m/text/"</tag>
3601 Specifies a password used for authentication. See <ref id="dsc-pass"
3602 name="password"> common option for detailed description.
3604 <tag>ttl security [<m/switch/ | tx only]</tag>
3605 TTL security is a feature that protects routing protocols from remote
3606 spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
3607 destined to neighbors. Because TTL is decremented when packets are
3608 forwarded, it is non-trivial to spoof packets with TTL 255 from remote
3611 If this option is enabled, the router will send RIP packets with TTL 255
3612 and drop received packets with TTL less than 255. If this option si set
3613 to <cf/tx only/, TTL 255 is used for sent packets, but is not checked
3614 for received packets. Such setting does not offer protection, but offers
3615 compatibility with neighbors regardless of whether they use ttl
3618 For RIPng, TTL security is a standard behavior (required by RFC 2080)
3619 and therefore default value is yes. For IPv4 RIP, default value is no.
3621 <tag>tx class|dscp|priority <m/number/</tag>
3622 These options specify the ToS/DiffServ/Traffic class/Priority of the
3623 outgoing RIP packets. See <ref id="dsc-prio" name="tx class"> common
3624 option for detailed description.
3626 <tag>rx buffer <m/number/</tag>
3627 This option specifies the size of buffers used for packet processing.
3628 The buffer size should be bigger than maximal size of received packets.
3629 The default value is 532 for IPv4 RIP and interface MTU value for RIPng.
3631 <tag>tx length <m/number/</tag>
3632 This option specifies the maximum length of generated RIP packets. To
3633 avoid IP fragmentation, it should not exceed the interface MTU value.
3634 The default value is 532 for IPv4 RIP and interface MTU value for RIPng.
3636 <tag>check link <m/switch/</tag>
3637 If set, the hardware link state (as reported by OS) is taken into
3638 consideration. When the link disappears (e.g. an ethernet cable is
3639 unplugged), neighbors are immediately considered unreachable and all
3640 routes received from them are withdrawn. It is possible that some
3641 hardware drivers or platforms do not implement this feature. Default:
3647 <p>RIP defines two route attributes:
3650 <tag>int <cf/rip_metric/</tag>
3651 RIP metric of the route (ranging from 0 to <cf/infinity/). When routes
3652 from different RIP instances are available and all of them have the same
3653 preference, BIRD prefers the route with lowest <cf/rip_metric/. When a
3654 non-RIP route is exported to RIP, the default metric is 1.
3656 <tag>int <cf/rip_tag/</tag>
3657 RIP route tag: a 16-bit number which can be used to carry additional
3658 information with the route (for example, an originating AS number in
3659 case of external routes). When a non-RIP route is exported to RIP, the
3671 interface "eth0" { metric 3; mode multicast; };
3672 interface "eth*" { metric 2; mode broadcast; };
3673 authentication none;
3674 import filter { print "importing"; accept; };
3675 export filter { print "exporting"; accept; };
3682 <p>The Static protocol doesn't communicate with other routers in the network,
3683 but instead it allows you to define routes manually. This is often used for
3684 specifying how to forward packets to parts of the network which don't use
3685 dynamic routing at all and also for defining sink routes (i.e., those telling to
3686 return packets as undeliverable if they are in your IP block, you don't have any
3687 specific destination for them and you don't want to send them out through the
3688 default route to prevent routing loops).
3690 <p>There are five types of static routes: `classical' routes telling to forward
3691 packets to a neighboring router, multipath routes specifying several (possibly
3692 weighted) neighboring routers, device routes specifying forwarding to hosts on a
3693 directly connected network, recursive routes computing their nexthops by doing
3694 route table lookups for a given IP, and special routes (sink, blackhole etc.)
3695 which specify a special action to be done instead of forwarding the packet.
3697 <p>When the particular destination is not available (the interface is down or
3698 the next hop of the route is not a neighbor at the moment), Static just
3699 uninstalls the route from the table it is connected to and adds it again as soon
3700 as the destination becomes adjacent again.
3702 <p>There are three classes of definitions in Static protocol configuration --
3703 global options, static route definitions, and per-route options. Usually, the
3704 definition of the protocol contains mainly a list of static routes.
3709 <tag>check link <m/switch/</tag>
3710 If set, hardware link states of network interfaces are taken into
3711 consideration. When link disappears (e.g. ethernet cable is unplugged),
3712 static routes directing to that interface are removed. It is possible
3713 that some hardware drivers or platforms do not implement this feature.
3716 <tag>igp table <m/name/</tag>
3717 Specifies a table that is used for route table lookups of recursive
3718 routes. Default: the same table as the protocol is connected to.
3721 <p>Route definitions (each may also contain a block of per-route options):
3724 <tag>route <m/prefix/ via <m/ip/</tag>
3725 Static route through a neighboring router. For link-local next hops,
3726 interface can be specified as a part of the address (e.g.,
3727 <cf/via fe80::1234%eth0/).
3729 <tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [bfd <m/switch/] [via ...]</tag>
3730 Static multipath route. Contains several nexthops (gateways), possibly
3733 <tag>route <m/prefix/ via <m/"interface"/</tag>
3734 Static device route through an interface to hosts on a directly
3737 <tag>route <m/prefix/ recursive <m/ip/</tag>
3738 Static recursive route, its nexthop depends on a route table lookup for
3741 <tag>route <m/prefix/ blackhole|unreachable|prohibit</tag>
3742 Special routes specifying to silently drop the packet, return it as
3743 unreachable or return it as administratively prohibited. First two
3744 targets are also known as <cf/drop/ and <cf/reject/.
3747 <p>Per-route options:
3750 <tag>bfd <m/switch/</tag>
3751 The Static protocol could use BFD protocol for next hop liveness
3752 detection. If enabled, a BFD session to the route next hop is created
3753 and the static route is BFD-controlled -- the static route is announced
3754 only if the next hop liveness is confirmed by BFD. If the BFD session
3755 fails, the static route is removed. Note that this is a bit different
3756 compared to other protocols, which may use BFD as an advisory mechanism
3757 for fast failure detection but ignores it if a BFD session is not even
3760 This option can be used for static routes with a direct next hop, or
3761 also for for individual next hops in a static multipath route (see
3762 above). Note that BFD protocol also has to be configured, see
3763 <ref id="sect-bfd" name="BFD"> section for details. Default value is no.
3765 <tag><m/filter expression/</tag>
3766 This is a special option that allows filter expressions to be configured
3767 on per-route basis. Can be used multiple times. These expressions are
3768 evaluated when the route is originated, similarly to the import filter
3769 of the static protocol. This is especially useful for configuring route
3770 attributes, e.g., <cf/ospf_metric1 = 100;/ for a route that will be
3771 exported to the OSPF protocol.
3774 <p>Static routes have no specific attributes.
3776 <p>Example static config might look like this:
3780 table testable; # Connect to a non-default routing table
3781 check link; # Advertise routes only if link is up
3782 route 0.0.0.0/0 via 198.51.100.130; # Default route
3783 route 10.0.0.0/8 multipath # Multipath route
3784 via 198.51.100.10 weight 2
3785 via 198.51.100.20 bfd # BFD-controlled next hop
3787 route 203.0.113.0/24 unreachable; # Sink route
3788 route 10.2.0.0/24 via "arc0"; # Secondary network
3789 route 192.168.10.0/24 via 198.51.100.100 {
3790 ospf_metric1 = 20; # Set extended attribute
3792 route 192.168.10.0/24 via 198.51.100.100 {
3793 ospf_metric2 = 100; # Set extended attribute
3794 ospf_tag = 2; # Set extended attribute
3795 bfd; # BFD-controlled route
3805 <p>Although BIRD supports all the commonly used routing protocols, there are
3806 still some features which would surely deserve to be implemented in future
3811 <item>Route aggregation and flap dampening
3812 <item>Multipath routes
3813 <item>Multicast routing protocols
3814 <item>Ports to other systems
3818 <sect>Getting more help
3820 <p>If you use BIRD, you're welcome to join the bird-users mailing list
3821 (<HTMLURL URL="mailto:bird-users@network.cz" name="bird-users@network.cz">)
3822 where you can share your experiences with the other users and consult
3823 your problems with the authors. To subscribe to the list, visit
3824 <HTMLURL URL="http://bird.network.cz/?m_list" name="http://bird.network.cz/?m_list">.
3825 The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
3827 <p>BIRD is a relatively young system and it probably contains some bugs. You can
3828 report any problems to the bird-users list and the authors will be glad to solve
3829 them, but before you do so, please make sure you have read the available
3830 documentation and that you are running the latest version (available at
3831 <HTMLURL URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">).
3832 (Of course, a patch which fixes the bug is always welcome as an attachment.)
3834 <p>If you want to understand what is going inside, Internet standards are a good
3835 and interesting reading. You can get them from
3836 <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a
3837 nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc"
3838 name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
3845 LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
3846 LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps
3847 LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC
3848 LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth
3849 LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek
3850 LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC
3851 LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU
3852 LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc
3853 LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats
3854 LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt
3855 LocalWords: proto wildcard Ondrej Filip