Bird
Bird
0 User’s Guide
Ondrej Filip <[email protected]>, Pavel Machek <[email protected]>, Martin Mares <[email protected]>, Maria
Matejka <[email protected]>, Ondrej Zajicek <[email protected]>
This document contains user documentation for the BIRD Internet Routing Daemon project.
Contents
1 Introduction 3
1.1 What is BIRD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Installing BIRD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Running BIRD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Architecture 6
2.1 Routing tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 Routes and network types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3 Protocols and channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4 Graceful restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3 Configuration 9
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Global options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 Protocol options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4 Channel options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4 Remote control 16
5 Filters 19
5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2 Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.3 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.4 Control structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.5 Route attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.6 Other statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6 Protocols 26
6.1 Babel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.2 BFD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.3 BGP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.4 Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.5 Direct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.6 Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.7 MRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.8 OSPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.9 Perf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.10 Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.11 RAdv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.12 RIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.13 RPKI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.14 Static . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
7 Conclusions 74
7.1 Future work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.2 Getting more help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
2
Chapter 1: Introduction
1.1 What is BIRD
The name ‘BIRD’ is actually an acronym standing for ‘BIRD Internet Routing Daemon’. Let’s take a closer
look at the meaning of the name:
BIRD: Well, we think we have already explained that. It’s an acronym standing for ‘BIRD Internet Routing
Daemon’, you remember, don’t you? :-)
Internet Routing: It’s a program (well, a daemon, as you are going to discover in a moment) which works
as a dynamic router in an Internet type network (that is, in a network running either the IPv4 or the IPv6
protocol). Routers are devices which forward packets between interconnected networks in order to allow
hosts not connected directly to the same local area network to communicate with each other. They also
communicate with the other routers in the Internet to discover the topology of the network which allows
them to find optimal (in terms of some metric) rules for forwarding of packets (which are called routing
tables) and to adapt themselves to the changing conditions such as outages of network links, building of new
connections and so on. Most of these routers are costly dedicated devices running obscure firmware which
is hard to configure and not open to any changes (on the other hand, their special hardware design allows
them to keep up with lots of high-speed network interfaces, better than general-purpose computer does).
Fortunately, most operating systems of the UNIX family allow an ordinary computer to act as a router and
forward packets belonging to the other hosts, but only according to a statically configured table.
A Routing Daemon is in UNIX terminology a non-interactive program running on background which does
the dynamic part of Internet routing, that is it communicates with the other routers, calculates routing
tables and sends them to the OS kernel which does the actual packet forwarding. There already exist other
such routing daemons: routed (RIP only), GateD (non-free), Zebra and MRTD, but their capabilities are
limited and they are relatively hard to configure and maintain.
BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings, to support all the routing
technology used in the today’s Internet or planned to be used in near future and to have a clean extensible
architecture allowing new routing protocols to be incorporated easily. Among other features, BIRD supports:
BIRD has been developed at the Faculty of Math and Physics, Charles University, Prague, Czech Republic
as a student project. It can be freely distributed under the terms of the GNU General Public License.
BIRD has been designed to work on all UNIX-like systems. It has been developed and tested under Linux
2.0 to 2.6, and then ported to FreeBSD, NetBSD and OpenBSD, porting to other systems (even non-UNIX
ones) should be relatively easy due to its highly modular architecture.
BIRD 1.x supported either IPv4 or IPv6 protocol, but had to be compiled separately for each one. BIRD 2
3
1.2. Installing BIRD 4
supports both of them with a possibility of further extension. BIRD 2 supports Linux at least 3.16, FreeBSD
10, NetBSD 7.0, and OpenBSD 5.8. Anyway, it will probably work well also on older systems.
./configure
make
make install
vi /usr/local/etc/bird.conf
bird
You can use ./configure --help to get a list of configure options. The most important ones are:
--with-protocols= to produce a slightly smaller BIRD executable by configuring out routing protocols
you don’t use, and --prefix= to install BIRD to a place different from /usr/local.
-c config name
use given configuration file instead of prefix /etc/bird.conf.
-d
enable debug messages to stderr, and run bird in foreground.
-D filename of debug log
enable debug messages to given file.
-f
run bird in foreground.
-g group
use that group ID, see the next section for details.
-h, --help
display command-line options to bird.
-l
look for a configuration file and a communication socket in the current working directory instead of in
default system locations. However, paths specified by options -c, -s have higher priority.
-p
just parse the config file and exit. Return value is zero if the config file is valid, nonzero if there are
some errors.
--version
display bird version.
BIRD writes messages about its work to log files or syslog (according to config).
1.4 Privileges
BIRD, as a routing daemon, uses several privileged operations (like setting routing table and using raw
sockets). Traditionally, BIRD is executed and runs with root privileges, which may be prone to security
problems. The recommended way is to use a privilege restriction (options -u, -g). In that case BIRD is
executed with root privileges, but it changes its user and group ID to an unprivileged ones, while using
Linux capabilities to retain just required privileges (capabilities CAP NET *). Note that the control socket
is created before the privileges are dropped, but the config file is read after that. The privilege restriction is
not implemented in BSD port of BIRD.
An unprivileged user (as an argument to -u options) may be the user nobody, but it is suggested to use a
new dedicated user account (like bird). The similar considerations apply for the group option, but there is
one more condition – the users in the same group can use birdc to control BIRD.
Finally, there is a possibility to use external tools to run BIRD in an environment with restricted privileges.
This may need some configuration, but it is generally easy – BIRD needs just the standard library, privileges
to read the config file and create the control socket and the CAP NET * capabilities.
Chapter 2: Architecture
2.1 Routing tables
The heart of BIRD is a routing table. BIRD has several independent routing tables; each of them contains
routes of exactly one nettype (see below). There are two default tables – master4 for IPv4 routes and
master6 for IPv6 routes. Other tables must be explicitly configured.
These routing tables are not kernel forwarding tables. No forwarding is done by BIRD. If you want to forward
packets using the routes in BIRD tables, you may use the Kernel protocol (see below) to synchronize them
with kernel FIBs.
Every nettype defines a (kind of) primary key on routes. Every route source can supply one route for every
possible primary key; new route announcement replaces the old route from the same source, keeping other
routes intact. BIRD always chooses the best route for each primary key among the known routes and keeps
the others as suboptimal. When the best route is retracted, BIRD re-runs the best route selection algorithm
to find the current best route.
The global best route selection algorithm is (roughly) as follows:
Usually, a routing table just chooses a selected route from a list of entries for one network. But if the
sorted option is activated, these lists of entries are kept completely sorted (according to preference or some
protocol-dependent metric). This is needed for some features of some protocols (e.g. secondary option of
BGP protocol, which allows to accept not just a selected route, but the first route (in the sorted list) that
is accepted by filters), but it is incompatible with some other features (e.g. deterministic med option of
BGP protocol, which activates a way of choosing selected route that cannot be described using comparison
and ordering). Minor advantage is that routes are shown sorted in show route, minor disadvantage is that
it is slightly more computationally expensive.
Other attributes depend on nettypes. Some of them are part of the primary key, these are marked (PK).
6
2.2. Routes and network types 7
• (PK) AS number
protocol kernel {
ipv4 {
export all; # Default is export none
};
persist; # Don’t remove routes on BIRD shutdown
}
protocol device {
}
protocol rip {
ipv4 {
import all;
export all;
};
interface "*";
}
ipv6 table
include "tablename.conf";;
log "filename" [limit "backup"] | syslog [name name] | stderr all|{ list of classes }
Set logging of messages having the given class (either all or { error|trace [, ...] } etc.) into
selected destination - a file specified as a filename string (with optional log rotation information),
syslog (with optional name argument), or the stderr output.
Classes are: info, warning, error and fatal for messages about local problems, debug for debugging
messages, trace when you want to know what happens in the network, remote for messages about
9
3.2. Global options 10
misbehavior of remote machines, auth about authentication failures, bug for internal BIRD bugs.
Logging directly to file supports basic log rotation – there is an optional log file limit and a backup
filename, when log file reaches the limit, the current log file is renamed to the backup filename and a
new log file is created.
You may specify more than one log line to establish logging to multiple destinations. Default: log
everything to the system log, or to the debug output if debugging is enabled by -d/-D command-line
option.
debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, ...] }
Set global defaults of protocol debugging options. See debug (p. 12) in the following section. Default:
off.
debug channels all|off|{ states|routes|filters|events [, ...] }
Set global defaults of channel debugging options. See debug (p. 14) in the channel section. Default:
off.
debug commands number
Control logging of client connections (0 for no logging, 1 for logging of connects and disconnects, 2 and
higher for logging of all client commands). Default: 0.
debug latency switch
Activate tracking of elapsed time for internal events. Recent events could be examined using dump
events command. Default: off.
debug latency limit time
If debug latency is enabled, this option allows to specify a limit for elapsed time. Events exceeding
the limit are logged. Default: 1 s.
watchdog warning time
Set time limit for I/O loop cycle. If one iteration took more time to complete, a warning is logged.
Default: 5 s.
watchdog timeout time
Set time limit for I/O loop cycle. If the limit is breached, BIRD is killed by abort signal. The timeout
has effective granularity of seconds, zero means disabled. Default: disabled (0).
mrtdump "filename"
Set MRTdump file name. This option must be specified to allow MRTdump feature. Default: no dump
file.
mrtdump protocols all|off|{ states|messages [, ...] }
Set global defaults of MRTdump options. See mrtdump in the following section. Default: off.
filter name local variables{ commands }
Define a filter. You can learn more about filters in the following chapter.
function name (parameters) local variables { commands }
Define a function. You can learn more about functions in the following chapter.
protocol rip|ospf|bgp|... [name [from name2 ]] { protocol options }
Define a protocol instance called name (or with a name like ”rip5” generated automatically if you
don’t specify any name). You can learn more about configuring protocols in their own chapters. When
from name2 expression is used, initial protocol options are taken from protocol or template name2
You can run more than one instance of most protocols (like RIP or BGP). By default, no instances are
configured.
template rip|ospf|bgp|... [name [from name2 ]] { protocol options }
Define a protocol template instance called name (or with a name like ”bgp1” generated automatically
if you don’t specify any name). Protocol templates can be used to group common options when many
similarly configured protocol instances are to be defined. Protocol instances (and other templates) can
use templates by using from expression and the name of the template. At the moment templates (and
from expression) are not implemented for OSPF protocol.
3.3. Protocol options 11
disabled switch
Disables the protocol. You can change the disable/enable status from the command line interface
without needing to touch the configuration. Disabled protocols are not activated. Default: protocol is
enabled.
debug all|off|{ states|routes|filters|interfaces|events|packets [, ...] }
Set protocol debugging options. If asked, each protocol is capable of writing trace messages about its
work to the log (with category trace). You can either request printing of all trace messages or only of
the selected types: states for protocol state changes (protocol going up, down, starting, stopping etc.),
routes for routes exchanged with the routing table, filters for details on route filtering, interfaces
for interface change events sent to the protocol, events for events internal to the protocol and packets
for packets sent and received by the protocol. Classes routes and filters can be also set per-channel
using channel debugging option (p. 14)) Default: off.
mrtdump all|off|{ states|messages [, ...] }
Set protocol MRTdump flags. MRTdump is a standard binary format for logging information from
routing protocols and daemons. These flags control what kind of information is logged from the protocol
to the MRTdump file (which must be specified by global mrtdump option, see the previous section).
Although these flags are similar to flags of debug option, their meaning is different and protocol-specific.
For BGP protocol, states logs BGP state changes and messages logs received BGP messages. Other
protocols does not support MRTdump yet.
There are several options that give sense only with certain protocols:
and its address matches the prefix (if specified). Extended clauses are used when the protocol handles
multiple addresses on an interface independently.
An interface option can be used more times with different interface-specific options, in that case for
given interface the first matching interface option is used.
This option is allowed in Babel, BFD, Device, Direct, OSPF, RAdv and RIP protocols. In OSPF
protocol it is used in the area subsection.
Default: none.
Examples:
interface "*" { type broadcast; }; - start the protocol on all interfaces with type broadcast
option.
interface "eth1", "eth4", "eth5" { type ptp; }; - start the protocol on enumerated interfaces
with type ptp option.
interface -192.168.1.0/24, 192.168.0.0/16; - start the protocol on all interfaces that have ad-
dress from 192.168.0.0/16, but not from 192.168.1.0/24.
interface "eth*" 192.168.1.0/24; - start the protocol on all ethernet interfaces that have address
from 192.168.1.0/24.
tx class|dscp num
This option specifies the value of ToS/DS/Class field in IP headers of the outgoing protocol packets.
This may affect how the protocol packets are processed by the network relative to the other network
traffic. With class keyword, the value (0-255) is used for the whole ToS/Class octet (but two bits
reserved for ECN are ignored). With dscp keyword, the value (0-63) is used just for the DS field in
the octet. Default value is 0xc0 (DSCP 0x30 - CS6).
tx priority num
This option specifies the local packet priority. This may affect how the protocol packets are processed
in the local TX queues. This option is Linux specific. Default value is 7 (highest priority, privileged
traffic).
password "password " [ { password options } ]
Specifies a password that can be used by the protocol as a shared secret key. Password option can be
used more times to specify more passwords. If more passwords are specified, it is a protocol-dependent
decision which one is really used. Specifying passwords does not mean that authentication is enabled,
authentication can be enabled by separate, protocol-dependent authentication option.
This option is allowed in BFD, OSPF and RIP protocols. BGP has also password option, but it is
slightly different and described separately. Default: none.
Password option can contain section with some (not necessary all) password sub-options:
id num
ID of the password, (0-255). If it is not specified, BIRD will choose ID based on an order of the
password item in the interface, starting from 1. For example, second password item in one interface
will have default ID 2. ID 0 is allowed by BIRD, but some other implementations may not allow it.
ID is used by some routing protocols to identify which password was used to authenticate protocol
packets.
generate from "time"
The start time of the usage of the password for packet signing. The format of time is dd-mm-yyyy
HH:MM:SS.
generate to "time"
The last time of the usage of the password for packet signing.
accept from "time"
The start time of the usage of the password for packet verification.
accept to "time"
The last time of the usage of the password for packet verification.
3.4. Channel options 14
from "time"
Shorthand for setting both generate from and accept from.
to "time"
Shorthand for setting both generate to and accept to.
algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 )
The message authentication algorithm for the password when cryptographic authentication is enabled.
The default value depends on the protocol. For RIP and OSPFv2 it is Keyed-MD5 (for compatibility),
for OSPFv3 protocol it is HMAC-SHA-256.
ipv4 {
table mytable4;
import filter { ... };
export none;
};
ipv6 {
table mytable6;
import filter { ... };
export none;
};
}
show status
Show router status, that is BIRD version, uptime and time from last reconfiguration.
show interfaces [summary]
Show the list of interfaces. For each interface, print its type, state, MTU and addresses assigned.
show protocols [all]
Show list of protocol instances along with tables they are connected to and protocol status, possibly
giving verbose information, if all is specified.
show ospf interface [name] ["interface"]
Show detailed information about OSPF interfaces.
show ospf neighbors [name] ["interface"]
Show a list of OSPF neighbors and a state of adjacency to them.
show ospf state [all] [name]
Show detailed information about OSPF areas based on a content of the link-state database. It shows
network topology, stub networks, aggregated networks and routers from other areas and external routes.
The command shows information about reachable network nodes, use option all to show information
about all network nodes in the link-state database.
show ospf topology [all] [name]
Show a topology of OSPF areas based on a content of the link-state database. It is just a stripped-down
version of ’show ospf state’.
show ospf lsadb [global | area id | link] [type num] [lsid id ] [self | router id ] [name]
Show contents of an OSPF LSA database. Options could be used to filter entries.
show rip interfaces [name] ["interface"]
Show detailed information about RIP interfaces.
show rip neighbors [name] ["interface"]
Show a list of RIP neighbors and associated state.
show static [name]
Show detailed information about static routes.
show bfd sessions [name]
Show information about BFD sessions.
show symbols [table|filter|function|protocol|template|roa|symbol ]
Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
16
17
show route [[for] prefix |IP ] [table (t | all)] [filter f |where c] [(export|preexport|noexport)
p] [protocol p] [(stats|count)] [options]
Show contents of specified routing tables, that is routes, their metrics and (in case the all switch is
given) all their attributes.
You can specify a prefix if you want to print routes for a specific network. If you use for prefix or IP ,
you’ll get the entry which will be used for forwarding of packets to the given destination. By default,
all routes for each network are printed with the selected one at the top, unless primary is given in
which case only the selected route is shown.
The show route command can process one or multiple routing tables. The set of selected tables is
determined on three levels: First, tables can be explicitly selected by table switch, which could be
used multiple times, all tables are specified by table all. Second, tables can be implicitly selected
by channels or protocols that are arguments of several other switches (e.g., export, protocol). Last,
the set of default tables is used: master4, master6 and each first table of any other network type.
You can also ask for printing only routes processed and accepted by a given filter (filter name or
filter { filter } or matching a given condition (where condition).
The export, preexport and noexport switches ask for printing of routes that are exported to the
specified protocol or channel. With preexport, the export filter of the channel is skipped. With
noexport, routes rejected by the export filter are printed instead. Note that routes not exported for
other reasons (e.g. secondary routes or routes imported from that protocol) are not printed even with
noexport. These switches also imply that associated routing tables are selected instead of default ones.
You can also select just routes added by a specific protocol. protocol p. This switch also implies that
associated routing tables are selected instead of default ones.
If BIRD is configured to keep filtered routes (see import keep filtered option), you can show them
instead of routes by using filtered switch.
The stats switch requests showing of route statistics (the number of networks, number of routes before
and after filtering). If you use count instead, only the statistics will be printed.
mrt dump table name|"pattern" to "filename" [filter f |where c]
Dump content of a routing table to a specified file in MRT table dump format. See MRT protocol
(p. 46) for details.
enable|disable|restart name|"pattern"|all
Enable, disable or restart a given protocol instance, instances matching the pattern or all instances.
reload [in|out] name|"pattern"|all
Reload a given protocol instance, that means re-import routes from the protocol instance and re-
export preferred routes to the instance. If in or out options are used, the command is restricted to
one direction (re-import or re-export).
This command is useful if appropriate filters have changed but the protocol instance was not restarted
(or reloaded), therefore it still propagates the old set of routes. For example when configure soft
command was used to change filters.
Re-export always succeeds, but re-import is protocol-dependent and might fail (for example, if BGP
neighbor does not support route-refresh extension). In that case, re-export is also skipped. Note that
for the pipe protocol, both directions are always reloaded together (in or out options are ignored in
that case).
down
Shut BIRD down.
graceful restart
Shut BIRD down for graceful restart. See graceful restart (p. 8) section for details.
debug protocol |pattern|all all|off|{ states|routes|filters|events|packets [, ...] }
Control protocol debugging.
dump resources|sockets|interfaces|neighbors|attributes|routes|protocols
Dump contents of internal data structures to the debugging output.
echo all|off|{ list of log classes } [ buffer-size ]
Control echoing of log messages to the command-line output. See log option (p. 9) for a list of log
classes.
eval expr
Evaluate given expression.
Chapter 5: Filters
5.1 Introduction
BIRD contains a simple programming language. (No, it can’t yet read mail :-). There are two objects in this
language: filters and functions. Filters are interpreted by BIRD core when a route is being passed between
protocols and routing tables. The filter language contains control structures such as if’s and switches, but
it allows no loops. An example of a filter using many features can be found in filter/test.conf.
Filter gets the route, looks at its attributes and modifies some of them if it wishes. At the end, it decides
whether to pass the changed route through (using accept) or whether to reject it. A simple filter looks
like this:
filter not_too_far
int var;
{
if defined( rip_metric ) then
var = rip_metric;
else {
var = 1;
rip_metric = 1;
}
if rip_metric > 10 then
reject "RIP metric is too big";
else
accept "ok";
}
As you can see, a filter has a header, a list of local variables, and a body. The header consists of the filter
keyword followed by a (unique) name of filter. The list of local variables consists of type name; pairs where
each pair declares one local variable. The body consists of { statements }. Each statement is terminated
by a ;. You can group several statements to a single compound statement by using braces ({ statements })
which is useful if you want to make a bigger block of code conditional.
BIRD supports functions, so that you don’t have to repeat the same blocks of code over and over. Functions
can have zero or more parameters and they can have local variables. Recursion is not allowed. Function
definitions look like this:
function name ()
int local_variable;
{
local_variable = 5;
}
Unlike in C, variables are declared after the function line, but before the first {. You can’t declare variables
in nested blocks. Functions are called like in C: name(); with parameters(5);. Function may return values
using the return [expr] command. Returning a value exits from current function (this is similar to C).
Filters are defined in a way similar to functions except they can’t have explicit parameters. They get a route
table entry as an implicit parameter, it is also passed automatically to any functions called. The filter must
terminate with either accept or reject statement. If there’s a runtime error in filter, the route is rejected.
A nice trick to debug filters is to use show route filter name from the command line client. An example
session might look like:
19
5.2. Data types 20
bool
This is a boolean type, it can have only two values, true and false. Boolean is the only type you can
use in if statements.
int
This is a general integer type. It is an unsigned 32bit type; i.e., you can expect it to store values from
0 to 4294967295. Overflows are not checked. You can use 0x1234 syntax to write hexadecimal values.
pair
This is a pair of two short integers. Each component can have values from 0 to 65535. Literals of
this type are written as (1234,5678). The same syntax can also be used to construct a pair from two
arbitrary integer expressions (for example (1+2,a)).
quad
This is a dotted quad of numbers used to represent router IDs (and others). Each component can have
a value from 0 to 255. Literals of this type are written like IPv4 addresses.
string
This is a string of characters. There are no ways to modify strings in filters. You can pass them between
functions, assign them to variables of type string, print such variables, use standard string comparison
operations (e.g. =, !=, <, >, <=, >=), but you can’t concatenate two strings. String literals are
written as "This is a string constant". Additionally matching (~, !~) operators could be used
to match a string value against a shell pattern (represented also as a string).
ip
This type can hold a single IP address. The IPv4 addresses are stored as IPv4-Mapped IPv6 addresses
so one data type for both of them is used. Whether the address is IPv4 or not may be checked by
.is v4 which returns a bool. IP addresses are written in the standard notation (10.20.30.40 or
fec0:3:4::1). You can apply special operator .mask(num) on values of type ip. It masks out all but
first num bits from the IP address. So 1.2.3.4.mask(8) = 1.0.0.0 is true.
prefix
This type can hold a network prefix consisting of IP address, prefix length and several other values.
This is the key in route tables.
Prefixes may be of several types, which can be determined by the special operator .type. The type
may be:
NET IP4 and NET IP6 prefixes hold an IP prefix. The literals are written as ipaddress/pxlen. There
are two special operators on these: .ip which extracts the IP address from the pair, and .len, which
separates prefix length from the pair. So 1.2.0.0/16.len = 16 is true.
NET IP6 SADR nettype holds both destination and source IPv6 prefix. The literals are written as
ipaddress/pxlen from ipaddress/pxlen, where the first part is the destination prefix and the second
5.2. Data types 21
art is the source prefix. They support the same operators as IP prefixes, but just for the destination
part. They also support .src and .dst operators to get respective parts of the address as separate
NET IP6 values.
NET VPN4 and NET VPN6 prefixes hold an IP prefix with VPN Route Distinguisher (RFC 4364). They
support the same special operators as IP prefixes, and also .rd which extracts the Route Distinguisher.
Their literals are written as vpnrd ipprefix
NET ROA4 and NET ROA6 prefixes hold an IP prefix range together with an ASN. They support the same
special operators as IP prefixes, and also .maxlen which extracts maximal prefix length, and .asn
which extracts the ASN.
NET FLOW4 and NET FLOW6 hold an IP prefix together with a flowspec rule. Filters currently do not
support much flowspec parsing, only .src and .dst operators to get source and destination parts of
the flowspec as separate NET IP4 / NET IP6 values.
NET MPLS holds a single MPLS label and its handling is currently not implemented.
vpnrd
This is a route distinguisher according to RFC 4364. There are three kinds of RD’s: asn:32bit int,
asn4 :16bit int and IPv4 address:32bit int
ec
This is a specialized type used to represent BGP extended community values. It is essentially a 64bit
value, literals of this type are usually written as (kind , key, value), where kind is a kind of extended
community (e.g. rt / ro for a route target / route origin communities), the format and possible values
of key and value are usually integers, but it depends on the used kind. Similarly to pairs, ECs can
be constructed using expressions for key and value parts, (e.g. (ro, myas, 3*10), where myas is an
integer variable).
lc
This is a specialized type used to represent BGP large community values. It is essentially a triplet
of 32bit values, where the first value is reserved for the AS number of the issuer, while meaning of
remaining parts is defined by the issuer. Literals of this type are written as (123, 456, 789), with
any integer values. Similarly to pairs, LCs can be constructed using expressions for its parts, (e.g.
(myas, 10+20, 3*10), where myas is an integer variable).
int|pair|quad|ip|prefix|ec|lc|enum set
Filters recognize four types of sets. Sets are similar to strings: you can pass them around but you can’t
modify them. Literals of type int set look like [ 1, 2, 5..7 ]. As you can see, both simple values
and ranges are permitted in sets.
For pair sets, expressions like (123,*) can be used to denote ranges (in that case
(123,0)..(123,65535)). You can also use (123,5..100) for range (123,5)..(123,100). You can
also use * and a..b expressions in the first part of a pair, note that such expressions are translated
to a set of intervals, which may be memory intensive. E.g. (*,4..20) is translated to (0,4..20),
(1,4..20), (2,4..20), ... (65535, 4..20).
EC sets use similar expressions like pair sets, e.g. (rt, 123, 10..20) or (ro, 123, *). Expressions
requiring the translation (like (rt, *, 3)) are not allowed (as they usually have 4B range for ASNs).
Also LC sets use similar expressions like pair sets. You can use ranges and wildcards, but if one field
uses that, more specific (later) fields must be wildcards. E.g., (10, 20..30, *) or (10, 20, 30..40)
is valid, while (10, *, 20..30) or (10, 20..30, 40) is not valid.
You can also use expressions for int, pair, EC and LC set values. However, it must be possible to
evaluate these expressions before daemon boots. So you can use only constants inside them. E.g.
define one=1;
define myas=64500;
int set odds;
pair set ps;
ec set es;
5.2. Data types 22
Sets of prefixes are special: their literals does not allow ranges, but allows prefix patterns that are
written as ipaddress/pxlen{low ,high}. Prefix ip1 /len1 matches prefix pattern ip2 /len2 {l ,h} if the
first min(len1, len2) bits of ip1 and ip2 are identical and len1 <= ip1 <= len2. A valid prefix
pattern has to satisfy low <= high, but pxlen is not constrained by low or high. Obviously, a prefix
matches a prefix set literal if it matches any prefix pattern in the prefix set literal.
There are also two shorthands for prefix patterns: address/len+ is a shorthand for ad-
dress/len{len,maxlen} (where maxlen is 32 for IPv4 and 128 for IPv6), that means network pre-
fix address/len and all its subnets. address/len- is a shorthand for address/len{0,len}, that means
network prefix address/len and all its supernets (network prefixes that contain it).
For example, [ 1.0.0.0/8, 2.0.0.0/8+, 3.0.0.0/8-, 4.0.0.0/8{16,24} ] matches prefix
1.0.0.0/8, all subprefixes of 2.0.0.0/8, all superprefixes of 3.0.0.0/8 and prefixes 4.X.X.X whose
prefix length is 16 to 24. [ 0.0.0.0/0{20,24} ] matches all prefixes (regardless of IP address) whose
prefix length is 20 to 24, [ 1.2.3.4/32- ] matches any prefix that contains IP address 1.2.3.4.
1.2.0.0/16 ~ [ 1.0.0.0/8{15,17} ] is true, but 1.0.0.0/16 ~ [ 1.0.0.0/8- ] is false.
Cisco-style patterns like 10.0.0.0/8 ge 16 le 24 can be expressed in BIRD as 10.0.0.0/8{16,24},
192.168.0.0/16 le 24 as 192.168.0.0/16{16,24} and 192.168.0.0/16 ge 24 as
192.168.0.0/16{24,32}.
It is not possible to mix IPv4 and IPv6 prefixes in a prefix set. It is currently possible to mix IPv4
and IPv6 addresses in an ip set, but that behavior may change between versions without any warning;
don’t do it unless you are more than sure what you are doing. (Really, don’t do it.)
enum
Enumeration types are fixed sets of possibilities. You can’t define your own variables of such type, but
some route attributes are of enumeration type. Enumeration types are incompatible with each other.
bgppath
BGP path is a list of autonomous system numbers. You can’t write literals of this type. There are
several special operators on bgppaths:
P .first returns the first ASN (the neighbor ASN) in path P .
P .last returns the last ASN (the source ASN) in path P .
P .last nonaggregated returns the last ASN in the non-aggregated part of the path P .
Both first and last return zero if there is no appropriate ASN, for example if the path contains an
AS set element as the first (or the last) part. If the path ends with an AS set, last nonaggregated
may be used to get last ASN before any AS set.
P .len returns the length of path P .
P .empty makes the path P empty.
prepend(P ,A) prepends ASN A to path P and returns the result.
delete(P ,A) deletes all instances of ASN A from from path P and returns the result. A may also be
an integer set, in that case the operator deletes all ASNs from path P that are also members of set A.
filter(P ,A) deletes all ASNs from path P that are not members of integer set A. I.e., filter do
the same as delete with inverted set A.
Statement P = prepend(P , A); can be shortened to P .prepend(A); if P is appropriate route
attribute (for example bgp path). Similarly for delete and filter.
bgpmask
BGP masks are patterns used for BGP path matching (using path ~ [= 2 3 5 * =] syntax). The
masks resemble wildcard patterns as used by UNIX shells. Autonomous system numbers match them-
selves, * matches any (even empty) sequence of arbitrary AS numbers and ? matches one arbitrary AS
number. For example, if bgp path is 4 3 2 1, then: bgp path ~ [= * 4 3 * =] is true, but bgp path
5.3. Operators 23
~ [= * 4 5 * =] is false. There is also + operator which matches one or multiple instances of previous
expression, e.g. [= 1 2+ 3 =] matches both path 1 2 3 and path 1 2 2 2 3, but not 1 3 nor 1 2 4 3.
Note that while * and ? are wildcard-style operators, + is regex-style operator.
BGP mask expressions can also contain integer expressions enclosed in parenthesis and integer variables,
for example [= * 4 (1+2) a =]. You can also use ranges (e.g. [= * 3..5 2 100..200 * =]) and
sets (e.g. [= 1 2 [3, 5, 7] * =]).
clist
Clist is similar to a set, except that unlike other sets, it can be modified. The type is used for community
list (a set of pairs) and for cluster list (a set of quads). There exist no literals of this type. There are
three special operators on clists:
C .len returns the length of clist C .
C .empty makes the list C empty.
add(C ,P ) adds pair (or quad) P to clist C and returns the result. If item P is already in clist C , it
does nothing. P may also be a clist, in that case all its members are added; i.e., it works as clist union.
delete(C ,P ) deletes pair (or quad) P from clist C and returns the result. If clist C does not contain
item P , it does nothing. P may also be a pair (or quad) set, in that case the operator deletes all items
from clist C that are also members of set P . Moreover, P may also be a clist, which works analogously;
i.e., it works as clist difference.
filter(C ,P ) deletes all items from clist C that are not members of pair (or quad) set P . I.e., filter
do the same as delete with inverted set P . P may also be a clist, which works analogously; i.e., it
works as clist intersection.
Statement C = add(C , P ); can be shortened to C .add(P ); if C is appropriate route attribute (for
example bgp community). Similarly for delete and filter.
eclist
Eclist is a data type used for BGP extended community lists. Eclists are very similar to clists, but
they are sets of ECs instead of pairs. The same operations (like add, delete or ~ and !~ membership
operators) can be used to modify or test eclists, with ECs instead of pairs as arguments.
lclist
Lclist is a data type used for BGP large community lists. Like eclists, lclists are very similar to
clists, but they are sets of LCs instead of pairs. The same operations (like add, delete or ~ and !~
membership operators) can be used to modify or test lclists, with LCs instead of pairs as arguments.
5.3 Operators
The filter language supports common integer operators (+,-,*,/), parentheses (a*(b+c)), comparison
(a=b, a!=b, a<b, a>=b). Logical operations include unary not (!), and (&&), and or (||). Special operators
include (~, !~) for ”is (not) element of a set” operation - it can be used on element and set of elements of
the same type (returning true if element is contained in the given set), or on two strings (returning true if
first string matches a shell-like pattern stored in second string) or on IP and prefix (returning true if IP is
within the range defined by that prefix), or on prefix and prefix (returning true if first prefix is more specific
than second one) or on bgppath and bgpmask (returning true if the path matches the mask) or on number
and bgppath (returning true if the number is in the path) or on bgppath and int (number) set (returning
true if any ASN from the path is in the set) or on pair/quad and clist (returning true if the pair/quad is
element of the clist) or on clist and pair/quad set (returning true if there is an element of the clist that is
also a member of the pair/quad set).
There is one operator related to ROA infrastructure - roa check(). It examines a ROA table and does
RFC 6483 route origin validation for a given network prefix. The basic usage is roa check(table), which
checks the current route (which should be from BGP to have AS PATH argument) in the specified ROA
table and returns ROA UNKNOWN if there is no relevant ROA, ROA VALID if there is a matching ROA,
or ROA INVALID if there are some relevant ROAs but none of them match. There is also an extended
variant roa check(table, prefix , asn), which allows to specify a prefix and an ASN as arguments.
5.4. Control structures 24
case arg1 {
2: print "two"; print "I can do more commands without {}";
3 .. 5: print "three to five";
else: print "something else";
}
prefix net
The network prefix or anything else the route is talking about. The primary key of the routing table.
Read-only. (See the chapter about routes (p. 6).)
enum scope
The scope of the route. Possible values: SCOPE HOST for routes local to this host, SCOPE LINK
for those specific for a physical link, SCOPE SITE and SCOPE ORGANIZATION for private routes and
SCOPE UNIVERSE for globally visible routes. This attribute is not interpreted by BIRD and can be used
to mark routes in filters. The default value for new routes is SCOPE UNIVERSE.
int preference
Preference of the route. Valid values are 0-65535. (See the chapter about routing tables.)
ip from
The router which the route has originated from.
ip gw
Next hop packets routed using this route should be forwarded to.
string proto
The name of the protocol which the route has been imported from. Read-only.
5.6. Other statements 25
enum source
what protocol has told me about this route. Possible values: RTS DUMMY, RTS STATIC, RTS INHERIT,
RTS DEVICE, RTS RIP, RTS OSPF, RTS OSPF IA, RTS OSPF EXT1, RTS OSPF EXT2, RTS BGP, RTS PIPE,
RTS BABEL.
enum dest
Type of destination the packets should be sent to (RTD ROUTER for forwarding to a neighboring router,
RTD DEVICE for routing to a directly-connected network, RTD MULTIPATH for multipath destinations,
RTD BLACKHOLE for packets to be silently discarded, RTD UNREACHABLE, RTD PROHIBIT for packets that
should be returned with ICMP host unreachable / ICMP administratively prohibited messages). Can
be changed, but only to RTD BLACKHOLE, RTD UNREACHABLE or RTD PROHIBIT.
string ifname
Name of the outgoing interface. Sink routes (like blackhole, unreachable or prohibit) and multipath
routes have no interface associated with them, so ifname returns an empty string for such routes.
Setting it would also change route to a direct one (remove gateway).
int ifindex
Index of the outgoing interface. System wide index of the interface. May be used for interface matching,
however indexes might change on interface creation/removal. Zero is returned for routes with undefined
outgoing interfaces. Read-only.
int weight
Multipath weight of route next hops. Valid values are 1-256. Reading returns the weight of the first
next hop, setting it sets weights of all next hops to the specified value. Therefore, this attribute is
not much useful for manipulating individual next hops of an ECMP route, but can be used in BGP
multipath setup to set weights of individual routes that are merged to one ECMP route during export
to the Kernel protocol (with active marge paths (p. 45) option).
variable = expr
Set variable (or route attribute) to a given value.
accept|reject [ expr ]
Accept or reject the route, possibly printing expr .
return expr
Return expr from the current function, the function ends at this point.
print|printn expr [, expr...]
Prints given expressions; useful mainly while debugging filters. The printn variant does not terminate
the line.
Chapter 6: Protocols
6.1 Babel
6.1.1 Introduction
The Babel protocol (RFC 6126) is a loop-avoiding distance-vector routing protocol that is robust and efficient
both in ordinary wired networks and in wireless mesh networks. Babel is conceptually very simple in its
operation and ”just works” in its default configuration, though some configuration is possible and in some
cases desirable.
The Babel protocol is dual stack; i.e., it can carry both IPv4 and IPv6 routes over the same IPv6 transport.
For sending and receiving Babel packets, only a link-local IPv6 address is needed.
BIRD implements an extension for IPv6 source-specific routing (SSR or SADR), but must be configured
accordingly to use it. SADR-enabled Babel router can interoperate with non-SADR Babel router, but the
later would ignore routes with specific (non-zero) source prefix.
6.1.2 Configuration
The Babel protocol support both IPv4 and IPv6 channels; both can be configured simultaneously. It can also
be configured with IPv6 SADR (p. 7) channel instead of regular IPv6 channel, in such case SADR support
is enabled. Babel supports no global configuration options apart from those common to all other protocols,
but supports the following per-interface configuration options:
26
6.1. Babel 27
unreachable after a small number of Hello packets are lost, as described by limit option. On wireless
interfaces the ETX link quality estimation technique is used to compute the metrics of routes discovered
over this interface. This technique will gradually degrade the metric of routes when packets are lost
rather than the more binary up/down mechanism of wired type links. Default: wired.
rxcost num
This option specifies the nominal RX cost of the interface. The effective neighbor costs for route
metrics will be computed from this value with a mechanism determined by the interface type. Note
that in contrast to other routing protocols like RIP or OSPF, the rxcost specifies the cost of RX
instead of TX, so it affects primarily neighbors’ route selection and not local route selection. Default:
96 for wired interfaces, 256 for wireless.
limit num
BIRD keeps track of received Hello messages from each neighbor to establish neighbor reachability.
For wired type interfaces, this option specifies how many of last 16 hellos have to be correctly received
in order to neighbor is assumed to be up. The option is ignored on wireless type interfaces, where
gradual cost degradation is used instead of sharp limit. Default: 12.
hello interval time s|ms
Interval at which periodic Hello messages are sent on this interface, with time units. Default: 4 seconds.
update interval time s|ms
Interval at which periodic (full) updates are sent, with time units. Default: 4 times the hello interval.
port number
This option selects an UDP port to operate on. The default is to operate on port 6696 as specified in
the Babel RFC.
tx class|dscp|priority number
These options specify the ToS/DiffServ/Traffic class/Priority of the outgoing Babel packets. See tx
class (p. 13) common option for detailed description.
rx buffer number
This option specifies the size of buffers used for packet processing. The buffer size should be bigger
than maximal size of received packets. The default value is the interface MTU, and the value will be
clamped to a minimum of 512 bytes + IP packet overhead.
tx length number
This option specifies the maximum length of generated Babel packets. To avoid IP fragmentation, it
should not exceed the interface MTU value. The default value is the interface MTU value, and the
value will be clamped to a minimum of 512 bytes + IP packet overhead.
6.1.3 Attributes
Babel defines just one attribute: the internal babel metric of the route. It is exposed as the babel metric
attribute and has range from 1 to infinity (65535).
6.2. BFD 28
6.1.4 Example
protocol babel {
interface "eth*" {
type wired;
};
interface "wlan0", "wlan1" {
type wireless;
hello interval 1;
rxcost 512;
};
interface "tap0";
ipv4 {
export where (source = RTS_DEVICE) || (source = RTS_BABEL);
};
ipv6 {
export where (source = RTS_DEVICE) || (source = RTS_BABEL);
};
}
6.2 BFD
6.2.1 Introduction
Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it is an independent tool providing
liveness and failure detection. Routing protocols like OSPF and BGP use integrated periodic ”hello” messages
to monitor liveness of neighbors, but detection times of these mechanisms are high (e.g. 40 seconds by default
in OSPF, could be set down to several seconds). BFD offers universal, fast and low-overhead mechanism for
failure detection, which could be attached to any routing protocol in an advisory role.
BFD consists of mostly independent BFD sessions. Each session monitors an unicast bidirectional path
between two BFD-enabled routers. This is done by periodically sending control packets in both directions.
BFD does not handle neighbor discovery, BFD sessions are created on demand by request of other protocols
(like OSPF or BGP), which supply appropriate information like IP addresses and associated interfaces.
When a session changes its state, these protocols are notified and act accordingly (e.g. break an OSPF
adjacency when the BFD session went down).
BIRD implements basic BFD behavior as defined in RFC 5880 (some advanced features like the echo mode
or authentication are not implemented), IP transport for BFD as defined in RFC 5881 and RFC 5883 and
interaction with client protocols as defined in RFC 5882.
BFD packets are sent with a dynamic source port number. Linux systems use by default a bit different dy-
namic port range than the IANA approved one (49152-65535). If you experience problems with compatibility,
please adjust /proc/sys/net/ipv4/ip local port range.
6.2.2 Configuration
BFD configuration consists mainly of multiple definitions of interfaces. Most BFD config options are session
specific. When a new session is requested and dynamically created, it is configured from one of these
6.2. BFD 29
definitions. For sessions to directly connected neighbors, interface definitions are chosen based on the
interface associated with the session, while multihop definition is used for multihop sessions. If no definition
is relevant, the session is just created with the default configuration. Therefore, an empty BFD configuration
is often sufficient.
Note that to use BFD for other protocols like OSPF or BGP, these protocols also have to be configured
to request BFD sessions, usually by bfd option. In BGP case, it is also possible to specify per-peer BFD
session options (e.g. rx/tx intervals) as a part of the bfd option.
A BFD instance not associated with any VRF handles session requests from all other protocols, even ones
associated with a VRF. Such setup would work for single-hop BFD sessions if net.ipv4.udp l3mdev accept
sysctl is enabled, but does not currently work for multihop sessions. Another approach is to configure multiple
BFD instances, one for each VRF (including the default VRF). Each BFD instance associated with a VRF
(regular or default) only handles session requests from protocols in the same VRF.
Some of BFD session options require time value, which has to be specified with the appropriate unit: num
s|ms|us. Although microseconds are allowed as units, practical minimum values are usually in order of tens
of milliseconds.
contain interface specific options. See interface (p. 12) common option for a detailed description of
interface patterns. Note that contrary to the behavior of interface definitions of other protocols,
BFD protocol would accept sessions (in default configuration) even on interfaces not covered by such
definitions.
multihop { options }
Multihop definitions allow to specify options for multihop BFD sessions, in the same manner as
interface definitions are used for directly connected sessions. Currently only one such definition
(for all multihop sessions) could be used.
interval time
BFD ensures availability of the forwarding path associated with the session by periodically sending
BFD control packets in both directions. The rate of such packets is controlled by two options, min
rx interval and min tx interval (see below). This option is just a shorthand to set both of these
options together.
authentication none
No passwords are sent in BFD packets. This is the default value.
authentication simple
Every packet carries 16 bytes of password. Received packets lacking this password are ignored. This
authentication mechanism is very weak.
keyed SHA-1. Note that the algorithm is common for all keys (on one interface), in contrast to OSPF
or RIP, where it is a per-key option. Passwords (keys) are not sent open via network.
The meticulous variant means that cryptographic sequence numbers are increased for each sent packet,
while in the basic variant they are increased about once per second. Generally, the meticulous variant
offers better resistance to replay attacks but may require more computation.
password "text"
Specifies a password used for authentication. See password (p. 13) common option for detailed de-
scription. Note that password option algorithm is not available in BFD protocol. The algorithm is
selected by authentication option for all passwords.
6.2.3 Example
protocol bfd {
interface "eth*" {
min rx interval 20 ms;
min tx interval 50 ms;
idle tx interval 300 ms;
};
interface "gre*" {
interval 200 ms;
multiplier 10;
passive;
};
multihop {
interval 200 ms;
multiplier 10;
};
neighbor 192.168.1.10;
neighbor 192.168.2.2 dev "eth2";
neighbor 192.168.10.1 local 192.168.1.1 multihop;
}
6.3 BGP
The Border Gateway Protocol is the routing protocol used for backbone level routing in the today’s Internet.
Contrary to other protocols, its convergence does not rely on all routers following the same rules for route
selection, making it possible to implement any routing policy at any router in the network, the only restriction
being that if a router advertises a route, it must accept and forward packets according to it.
BGP works in terms of autonomous systems (often abbreviated as AS). Each AS is a part of the network
with common management and common routing policy. It is identified by a unique 16-bit number (ASN).
Routers within each AS usually exchange AS-internal routing information with each other using an interior
gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of the AS communicate
global (inter-AS) network reachability information with their neighbors in the neighboring AS’es via exterior
BGP (eBGP) and redistribute received information to other routers in the AS via interior BGP (iBGP).
Each BGP router sends to its neighbors updates of the parts of its routing table it wishes to export along
with complete path information (a list of AS’es the packet will travel through if it uses the particular route)
in order to avoid routing loops.
used for non link-local sessions when it is necessary to explicitly specify an interface, but only for direct
(not multihop) sessions.
direct
Specify that the neighbor is directly connected. The IP address of the neighbor must be from a directly
reachable IP range (i.e. associated with one of your router’s interfaces), otherwise the BGP session
wouldn’t start but it would wait for such interface to appear. The alternative is the multihop option.
Default: enabled for eBGP.
multihop [number ]
Configure multihop BGP session to a neighbor that isn’t directly connected. Accurately, this option
should be used if the configured neighbor IP address does not match with any local network subnets.
Such IP address have to be reachable through system routing table. The alternative is the direct
option. For multihop BGP it is recommended to explicitly configure the source address to have it
stable. Optional number argument can be used to specify the number of hops (used for TTL). Note
that the number of networks (edges) in a path is counted; i.e., if two BGP speakers are separated by
one router, the number of hops is 2. Default: enabled for iBGP.
source address ip
Define local address we should use as a source address for the BGP session. Default: the address of
the local end of the interface our neighbor is connected to.
dynamic name "text"
Define common prefix of names used for new BGP instances spawned when dynamic BGP behavior
is active. Actual names also contain numeric index to distinguish individual instances. Default:
”dynbgp”.
dynamic name digits number
Define minimum number of digits for index in names of spawned dynamic BGP instances. E.g., if set
to 2, then the first name would be ”dynbgp01”. Default: 0.
strict bind switch
Specify whether BGP listening socket should be bound to a specific local address (the same as the
source address) and associated interface, or to all addresses. Binding to a specific address could be
useful in cases like running multiple BIRD instances on a machine, each using its IP address. Note
that listening sockets bound to a specific address and to all addresses collide, therefore either all BGP
protocols (of the same address family and using the same local port) should have set strict bind, or
none of them. Default: disabled.
check link switch
BGP could use hardware link state into consideration. If enabled, BIRD tracks the link state of the
associated interface and when link disappears (e.g. an ethernet cable is unplugged), the BGP session
is immediately shut down. Note that this option cannot be used with multihop BGP. Default: enabled
for direct BGP, disabled otherwise.
bfd switch|graceful| { options }
BGP could use BFD protocol as an advisory mechanism for neighbor liveness and failure detection. If
enabled, BIRD setups a BFD session for the BGP neighbor and tracks its liveness by it. This has an
advantage of an order of magnitude lower detection times in case of failure. When a neighbor failure
is detected, the BGP session is restarted. Optionally, it can be configured (by graceful argument) to
trigger graceful restart instead of regular restart. It is also possible to specify section with per-peer BFD
session options instead of just switch argument. Most BFD session specific options are allowed here
with the exception of authentication options. here Note that BFD protocol also has to be configured,
see BFD (p. 28) section for details. Default: disabled.
ttl security switch
Use GTSM (RFC 5082 - the generalized TTL security mechanism). GTSM protects against spoofed
packets by ignoring received packets with a smaller than expected TTL. To work properly, GTSM
have to be enabled on both sides of a BGP session. If both ttl security and multihop options are
enabled, multihop option should specify proper hop value to compute expected TTL. Kernel support
required: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only. Note that full (ICMP
protection, for example) RFC 5082 support is provided by Linux only. Default: disabled.
6.3. BGP 35
password string
Use this password for MD5 authentication of BGP sessions (RFC 2385). When used on BSD systems,
see also setkey option below. Default: no authentication.
setkey switch
On BSD systems, keys for TCP MD5 authentication are stored in the global SA/SP database, which
can be accessed by external utilities (e.g. setkey(8)). BIRD configures security associations in the
SA/SP database automatically based on password options (see above), this option allows to disable
automatic updates by BIRD when manual configuration by external utilities is preferred. Note that
automatic SA/SP database updates are currently implemented only for FreeBSD. Passwords have
to be set manually by an external utility on NetBSD and OpenBSD. Default: enabled (ignored on
non-FreeBSD).
passive switch
Standard BGP behavior is both initiating outgoing connections and accepting incoming connections.
In passive mode, outgoing connections are not initiated. Default: off.
confederation number
BGP confederations (RFC 5065) are collections of autonomous systems that act as one entity to
external systems, represented by one confederation identifier (instead of AS numbers). This option
allows to enable BGP confederation behavior and to specify the local confederation identifier. When
BGP confederations are used, all BGP speakers that are members of the BGP confederation should
have the same confederation identifier configured. Default: 0 (no confederation).
confederation member switch
When BGP confederations are used, this option allows to specify whether the BGP neighbor is a
member of the same confederation as the local BGP speaker. The option is unnecessary (and ignored)
for IBGP sessions, as the same AS number implies the same confederation. Default: no.
rr client
Be a route reflector and treat the neighbor as a route reflection client. Default: disabled.
rr cluster id IPv4 address
Route reflectors use cluster id to avoid route reflection loops. When there is one route reflector in a
cluster it usually uses its router id as a cluster id, but when there are more route reflectors in a cluster,
these need to be configured (using this option) to use a common cluster id. Clients in a cluster need
not know their cluster id and this option is not allowed for them. Default: the same as router id.
rs client
Be a route server and treat the neighbor as a route server client. A route server is used as a replacement
for full mesh EBGP routing in Internet exchange points in a similar way to route reflectors used in
IBGP routing. BIRD does not implement obsoleted RFC 1863, but uses ad-hoc implementation, which
behaves like plain EBGP but reduces modifications to advertised route attributes to be transparent (for
example does not prepend its AS number to AS PATH attribute and keeps MED attribute). Default:
disabled.
allow bgp local pref switch
A standard BGP implementation do not send the Local Preference attribute to eBGP neighbors and
ignore this attribute if received from eBGP neighbors, as per RFC 4271. When this option is enabled
on an eBGP session, this attribute will be sent to and accepted from the peer, which is useful for
example if you have a setup like in RFC 7938. The option does not affect iBGP sessions. Default: off.
allow local as [number ]
BGP prevents routing loops by rejecting received routes with the local AS number in the AS path.
This option allows to loose or disable the check. Optional number argument can be used to specify the
maximum number of local ASNs in the AS path that is allowed for received routes. When the option is
used without the argument, the check is completely disabled and you should ensure loop-free behavior
by some other means. Default: 0 (no local AS number allowed).
allow as sets [switch]
AS path attribute received with BGP routes may contain not only sequences of AS numbers, but also
6.3. BGP 36
sets of AS numbers. These rarely used artifacts are results of inter-AS route aggregation. AS sets are
deprecated (RFC 6472), and likely to be rejected in the future, as they complicate security features
like RPKI validation. When this option is disabled, then received AS paths with AS sets are rejected
as malformed and corresponding BGP updates are treated as withdraws. Default: on.
enforce first as [switch]
Routes received from an EBGP neighbor are generally expected to have the first (leftmost) AS number
in their AS path equal to the neighbor AS number. This is not enforced by default as there are legitimate
cases where it is not true, e.g. connections to route servers. When this option is enabled, routes with
non-matching first AS number are rejected and corresponding updates are treated as withdraws. The
option is valid on EBGP sessions only. Default: off.
enable route refresh switch
After the initial route exchange, BGP protocol uses incremental updates to keep BGP speakers synchro-
nized. Sometimes (e.g., if BGP speaker changes its import filter, or if there is suspicion of inconsistency)
it is necessary to do a new complete route exchange. BGP protocol extension Route Refresh (RFC
2918) allows BGP speaker to request re-advertisement of all routes from its neighbor. BGP protocol
extension Enhanced Route Refresh (RFC 7313) specifies explicit begin and end for such exchanges,
therefore the receiver can remove stale routes that were not advertised during the exchange. This op-
tion specifies whether BIRD advertises these capabilities and supports related procedures. Note that
even when disabled, BIRD can send route refresh requests. Default: on.
mandatory switch
When local and neighbor sets of configured AFI/SAFI pairs differ, capability negotiation ensures that a
common subset is used. For mandatory channels their associated AFI/SAFI must be negotiated (i.e.,
also announced by the neighbor), otherwise BGP session negotiation fails with ’Required capability
missing’ error. Regardless, at least one AFI/SAFI must be negotiated in order to BGP session be
successfully established. Default: off.
next hop keep switch|ibgp|ebgp
Do not modify the Next Hop attribute and advertise the current one unchanged even in cases where
6.3. BGP 39
our own local address should be used instead. This is necessary when the BGP speaker does not
forward network traffic (route servers and some route reflectors) and also can be useful in some other
cases (e.g. multihop EBGP sessions). Can be enabled for all routes, or just for routes received from
IBGP / EBGP neighbors. Default: disabled for regular BGP, enabled for route servers, ibgp for route
reflectors.
gateway direct|recursive
For received routes, their gw (immediate next hop) attribute is computed from received bgp next hop
attribute. This option specifies how it is computed. Direct mode means that the IP address from
bgp next hop is used and must be directly reachable. Recursive mode means that the gateway is
computed by an IGP routing table lookup for the IP address from bgp next hop. Note that there is
just one level of indirection in recursive mode - the route obtained by the lookup must not be recursive
itself, to prevent mutually recursive routes.
Recursive mode is the behavior specified by the BGP standard. Direct mode is simpler, does not
require any routes in a routing table, and was used in older versions of BIRD, but does not handle
well nontrivial iBGP setups and multihop. Recursive mode is incompatible with sorted tables (p. 6).
Default: direct for direct sessions, recursive for multihop sessions.
6.3.6 Attributes
BGP defines several route attributes. Some of them (those marked with ‘I’ in the table below) are available
on internal BGP connections only, some of them (marked with ‘O’) are optional.
6.3.7 Example
protocol bgp {
local 198.51.100.14 as 65000; # Use a private AS number
neighbor 198.51.100.130 as 64496; # Our neighbor ...
multihop; # ... which is connected indirectly
ipv4 {
export filter { # We use non-trivial export rules
if source = RTS_STATIC then { # Export only static routes
# Assign our community
bgp_community.add((65000,64501));
# Artificially increase path length
# by advertising local AS number twice
if bgp_path ~ [= 65000 =] then
bgp_path.prepend(65000);
accept;
}
reject;
};
import all;
next hop self; # advertise this router as next hop
igp table myigptable4; # IGP table for routes with IPv4 nexthops
igp table myigptable6; # IGP table for routes with IPv6 nexthops
};
ipv6 {
export filter mylargefilter; # We use a named filter
import all;
missing lladdr self;
igp table myigptable4; # IGP table for routes with IPv4 nexthops
igp table myigptable6; # IGP table for routes with IPv6 nexthops
};
ipv4 multicast {
import all;
export filter someotherfilter;
table mymulticasttable4; # Another IPv4 table, dedicated for multicast
igp table myigptable4;
};
}
6.4. Device 43
6.4 Device
The Device protocol is not a real routing protocol. It doesn’t generate any routes and it only serves as a
module for getting information about network interfaces from the kernel. This protocol supports no channel.
Except for very unusual circumstances, you probably should include this protocol in the configuration since
almost all other protocols require network interfaces to be defined for them to work with.
6.4.1 Configuration
scan time number
Time in seconds between two scans of the network interface list. On systems where we are notified
about interface status changes asynchronously (such as newer versions of Linux), we need to scan the
list only in order to avoid confusion by lost notification messages, so the default time is set to a large
value.
interface pattern [, ...]
By default, the Device protocol handles all interfaces without any configuration. Interface definitions
allow to specify optional parameters for specific interfaces. See interface (p. 12) common option for
detailed description. Currently only one interface option is available:
preferred ip
If a network interface has more than one IP address, BIRD chooses one of them as a preferred one.
Preferred IP address is used as source address for packets or announced next hop by routing protocols.
Precisely, BIRD chooses one preferred IPv4 address, one preferred IPv6 address and one preferred
link-local IPv6 address. By default, BIRD chooses the first found IP address as the preferred one.
This option allows to specify which IP address should be preferred. May be used multiple times for
different address classes (IPv4, IPv6, IPv6 link-local). In all cases, an address marked by operating
system as secondary cannot be chosen as the primary one.
As the Device protocol doesn’t generate any routes, it cannot have any attributes. Example configuration
looks like this:
protocol device {
scan time 10; # Scan the interfaces often
interface "eth0" {
preferred 192.168.1.1;
preferred 2001:db8:1:10::1;
};
}
6.5 Direct
The Direct protocol is a simple generator of device routes for all the directly connected networks according to
the list of interfaces provided by the kernel via the Device protocol. The Direct protocol supports both IPv4
and IPv6 channels; both can be configured simultaneously. It can also be configured with IPv6 SADR (p. 7)
channel instead of regular IPv6 channel in order to be used together with SADR-enabled Babel protocol.
The question is whether it is a good idea to have such device routes in BIRD routing table. OS kernel
usually handles device routes for directly connected networks by itself so we don’t need (and don’t want)
to export these routes to the kernel protocol. OSPF protocol creates device routes for its interfaces itself
and BGP protocol is usually used for exporting aggregate routes. But the Direct protocol is necessary for
distance-vector protocols like RIP or Babel to announce local networks.
There are just few configuration options for the Direct protocol:
policy routing and some of the policy domains don’t contain all interfaces), just use this clause. See
interface (p. 12) common option for detailed description. The Direct protocol uses extended interface
clauses.
protocol direct {
ipv4;
ipv6;
interface "-arc*", "*"; # Exclude the ARCnets
}
6.6 Kernel
The Kernel protocol is not a real routing protocol. Instead of communicating with other routers in the
network, it performs synchronization of BIRD’s routing tables with the OS kernel. Basically, it sends all
routing table updates to the kernel and from time to time it scans the kernel tables to see whether some
routes have disappeared (for example due to unnoticed up/down transition of an interface) or whether an
‘alien’ route has been added by someone else (depending on the learn switch, such routes are either ignored
or accepted to our table).
Note that routes created by OS kernel itself, namely direct routes representing IP subnets of associated
interfaces, are not imported even with learn enabled. You can use Direct protocol (p. 43) to generate these
direct routes.
If your OS supports only a single routing table, you can configure only one instance of the Kernel protocol.
If it supports multiple tables (in order to allow policy routing; such an OS is for example Linux), you can
run as many instances as you want, but each of them must be connected to a different BIRD routing table
and to a different kernel table.
Because the kernel protocol is partially integrated with the connected routing table, there are two limitations
- it is not possible to connect more kernel protocols to the same routing table and changing route destination
(gateway) in an export filter of a kernel protocol does not work. Both limitations can be overcome using
another routing table and the pipe protocol.
The Kernel protocol supports both IPv4 and IPv6 channels; only one channel can be configured in each
protocol instance. On Linux, it also supports IPv6 SADR (p. 7) and MPLS (p. 7) channels.
6.6.1 Configuration
persist switch
Tell BIRD to leave all its routes in the routing tables when it exits (instead of cleaning them up).
scan time number
Time in seconds between two consecutive scans of the kernel routing table.
learn switch
Enable learning of routes added to the kernel routing tables by other routing daemons or by the system
administrator. This is possible only on systems which support identification of route authorship.
kernel table number
Select which kernel table should this particular instance of the Kernel protocol work with. Available
only on systems supporting multiple routing tables.
6.6. Kernel 45
metric number
(Linux) Use specified value as a kernel metric (priority) for all routes sent to the kernel. When multiple
routes for the same network are in the kernel routing table, the Linux kernel chooses one with lower
metric. Also, routes with different metrics do not clash with each other, therefore using dedicated
metric value is a reliable way to avoid overwriting routes from other sources (e.g. kernel device routes).
Metric 0 has a special meaning of undefined metric, in which either OS default is used, or per-route
metric can be set using krt metric attribute. Default: 32.
graceful restart switch
Participate in graceful restart recovery. If this option is enabled and a graceful restart recovery is
active, the Kernel protocol will defer synchronization of routing tables until the end of the recovery.
Note that import of kernel routes to BIRD is not affected.
merge paths switch [limit number ]
Usually, only best routes are exported to the kernel protocol. With path merging enabled, both best
routes and equivalent non-best routes are merged during export to generate one ECMP (equal-cost
multipath) route for each network. This is useful e.g. for BGP multipath. Note that best routes
are still pivotal for route export (responsible for most properties of resulting ECMP routes), while
exported non-best routes are responsible just for additional multipath next hops. This option also
allows to specify a limit on maximal number of nexthops in one route. By default, multipath merging
is disabled. If enabled, default value of the limit is 16.
6.6.2 Attributes
The Kernel protocol defines several attributes. These attributes are translated to appropriate system (and
OS-specific) route attributes. We support these attributes:
In Linux, there is also a plenty of obscure route attributes mostly focused on tuning TCP performance
of local connections. BIRD supports most of these attributes, see Linux or iproute2 documentation for
their meaning. Attributes krt lock * and krt feature * have type bool, others have type int. Supported
attributes are:
krt mtu, krt lock mtu, krt window, krt lock window, krt rtt, krt lock rtt, krt rttvar,
krt lock rttvar, krt sstresh, krt lock sstresh, krt cwnd, krt lock cwnd, krt advmss,
krt lock advmss, krt reordering, krt lock reordering, krt hoplimit, krt lock hoplimit,
krt rto min, krt lock rto min, krt initcwnd, krt initrwnd, krt quickack, krt feature ecn,
krt feature allfrag
6.7. MRT 46
6.6.3 Example
A simple configuration can look this way:
protocol kernel {
export all;
}
6.7 MRT
6.7.1 Introduction
The MRT protocol is a component responsible for handling the Multi-Threaded Routing Toolkit (MRT)
routing information export format, which is mainly used for collecting and analyzing of routing information
from BGP routers. The MRT protocol can be configured to do periodic dumps of routing tables, created
MRT files can be analyzed later by other tools. Independent MRT table dumps can also be requested from
BIRD client. There is also a feature to save incoming BGP messages in MRT files, but it is controlled by
mrtdump (p. 12) options independently of MRT protocol, although that might change in the future.
BIRD implements the main MRT format specification as defined in RFC 6396 and the ADD PATH extension
(RFC 8050).
6.7.2 Configuration
MRT configuration consists of several statements describing routing table dumps. Multiple independent
periodic dumps can be done as multiple MRT protocol instances. The MRT protocol does not use channels.
There are two mandatory statements: filename and period.
The behavior can be modified by following configuration parameters:
filename "filename"
Specify a filename for MRT dump files. The filename may contain time format sequences with strf-
time(3) notation (see man strftime for details), there is also a sequence ”%N” that is expanded to the
name of dumped table. Therefore, each periodic dump of each table can be saved to a different file.
Mandatory, see example below.
period number
Specify the time interval (in seconds) between periodic dumps. Mandatory.
always add path switch
The MRT format uses special records (specified in RFC 8050) for routes received using BGP
ADD PATH extension to keep Path ID, while other routes use regular records. This has advantage of
better compatibility with tools that do not know special records, but it loses information about which
route is the best route. When this option is enabled, both ADD PATH and non-ADD PATH routes
are stored in ADD PATH records and order of routes for network is preserved. Default: disabled.
6.7.3 Example
protocol mrt {
table "tab*";
where source = RTS_BGP;
filename "/var/log/bird/%N_%F_%T.mrt";
period 300;
}
6.8 OSPF
6.8.1 Introduction
Open Shortest Path First (OSPF) is a quite complex interior gateway protocol. The current IPv4 version
(OSPFv2) is defined in RFC 2328 and the current IPv6 version (OSPFv3) is defined in RFC 5340 It’s a
link state (a.k.a. shortest path first) protocol – each router maintains a database describing the autonomous
system’s topology. Each participating router has an identical copy of the database and all routers run the
same algorithm calculating a shortest path tree with themselves as a root. OSPF chooses the least cost path
as the best path.
In OSPF, the autonomous system can be split to several areas in order to reduce the amount of resources
consumed for exchanging the routing information and to protect the other areas from incorrect routing data.
Topology of the area is hidden to the rest of the autonomous system.
Another very important feature of OSPF is that it can keep routing information from other protocols (like
Static or BGP) in its link state database as external routes. Each external route can be tagged by the
advertising router, making it possible to pass additional information between routers on the boundary of the
autonomous system.
OSPF quickly detects topological changes in the autonomous system (such as router interface failures) and
calculates new loop-free routes after a short period of convergence. Only a minimal amount of routing traffic
is involved.
Each router participating in OSPF routing periodically sends Hello messages to all its interfaces. This allows
neighbors to be discovered dynamically. Then the neighbors exchange theirs parts of the link state database
and keep it identical by flooding updates. The flooding process is reliable and ensures that each router
detects all changes.
6.8.2 Configuration
First, the desired OSPF version can be specified by using ospf v2 or ospf v3 as a protocol type. By
default, OSPFv2 is used. In the main part of configuration, there can be multiple definitions of OSPF
areas, each with a different id. These definitions includes many other switches and multiple definitions of
6.8. OSPF 48
interfaces. Definition of interface may contain many switches and constant definitions and list of neighbors
on nonbroadcast networks.
OSPFv2 needs one IPv4 channel. OSPFv3 needs either one IPv6 channel, or one IPv4 channel (RFC 5838).
Therefore, it is possible to use OSPFv3 for both IPv4 and Pv6 routing, but it is necessary to have two protocol
instances anyway. If no channel is configured, appropriate channel is defined with default parameters.
protocol ospf [v2|v3] <name> {
rfc1583compat <switch>;
rfc5838 <switch>;
instance id <num>;
stub router <switch>;
tick <num>;
ecmp <switch> [limit <num>];
merge external <switch>;
graceful restart <switch>|aware;
graceful restart time <num>;
area <id> {
stub;
nssa;
summary <switch>;
default nssa <switch>;
default cost <num>;
default cost2 <num>;
translator <switch>;
translator stability <num>;
networks {
<prefix>;
<prefix> hidden;
};
external {
<prefix>;
<prefix> hidden;
<prefix> tag <num>;
};
stubnet <prefix>;
stubnet <prefix> {
hidden <switch>;
summary <switch>;
cost <num>;
};
interface <interface pattern> [instance <num>] {
cost <num>;
stub <switch>;
hello <num>;
poll <num>;
retransmit <num>;
priority <num>;
wait <num>;
dead count <num>;
dead <num>;
secondary <switch>;
rx buffer [normal|large|<num>];
tx length <num>;
type [broadcast|bcast|pointopoint|ptp|
nonbroadcast|nbma|pointomultipoint|ptmp];
link lsa suppression <switch>;
strict nonbroadcast <switch>;
6.8. OSPF 49
rfc1583compat switch
This option controls compatibility of routing table calculation with RFC 1583. Default value is no.
rfc5838 switch
Basic OSPFv3 is limited to IPv6 unicast routing. The RFC 5838 extension defines support for more
address families (IPv4, IPv6, both unicast and multicast). The extension is enabled by default, but
can be disabled if necessary, as it restricts the range of available instance IDs. Default value is yes.
instance id num
When multiple OSPF protocol instances are active on the same links, they should use different instance
6.8. OSPF 50
IDs to distinguish their packets. Although it could be done on per-interface basis, it is often preferred
to set one instance ID to whole OSPF domain/topology (e.g., when multiple instances are used to
represent separate logical topologies on the same physical network). This option specifies the instance
ID for all interfaces of the OSPF instance, but can be overridden by interface option. Default value
is 0 unless OSPFv3-AF extended address families are used, see RFC 5838 for that case.
stub router switch
This option configures the router to be a stub router, i.e., a router that participates in the OSPF
topology but does not allow transit traffic. In OSPFv2, this is implemented by advertising maximum
metric for outgoing links. In OSPFv3, the stub router behavior is announced by clearing the R-bit in
the router LSA. See RFC 6987 for details. Default value is no.
tick num
The routing table calculation and clean-up of areas’ databases is not performed when a single link
state change arrives. To lower the CPU utilization, it’s processed later at periodical intervals of num
seconds. The default value is 1.
ecmp switch [limit number ]
This option specifies whether OSPF is allowed to generate ECMP (equal-cost multipath) routes. Such
routes are used when there are several directions to the destination, each with the same (computed)
cost. This option also allows to specify a limit on maximum number of nexthops in one route. By
default, ECMP is enabled if supported by Kernel. Default value of the limit is 16.
merge external switch
This option specifies whether OSPF should merge external routes from different routers/LSAs for the
same destination. When enabled together with ecmp, equal-cost external routes will be combined to
multipath routes in the same way as regular routes. When disabled, external routes from different
LSAs are treated as separate even if they represents the same destination. Default value is no.
graceful restart switch|aware
When an OSPF instance is restarted, neighbors break adjacencies and recalculate their routing tables,
which disrupts packet forwarding even when the forwarding plane of the restarting router remains
intact. RFC 3623 specifies a graceful restart mechanism to alleviate this issue. For OSPF graceful
restart, restarting router originates Grace-LSAs, announcing intent to do graceful restart. Neighbors
receiving these LSAs enter helper mode, in which they ignore breakdown of adjacencies, behave as if
nothing is happening and keep old routes. When adjacencies are reestablished, the restarting router
flushes Grace-LSAs and graceful restart is ended.
This option controls the graceful restart mechanism. It has three states: Disabled, when no support
is provided. Aware, when graceful restart helper mode is supported, but no local graceful restart
is allowed (i.e. helper-only role). Enabled, when the full graceful restart support is provided (i.e.
both restarting and helper role). Note that proper support for local graceful restart requires also
configuration of other protocols. Default: aware.
graceful restart time num
The restart time is announced in the Grace-LSA and specifies how long neighbors should wait for
proper end of the graceful restart before exiting helper mode prematurely. Default: 120 seconds.
area id
This defines an OSPF area with given area ID (an integer or an IPv4 address, similarly to a router
ID). The most important area is the backbone (ID 0) to which every other area must be connected.
stub
This option configures the area to be a stub area. External routes are not flooded into stub areas. Also
summary LSAs can be limited in stub areas (see option summary). By default, the area is not a stub
area.
nssa
This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA is a variant of a stub area
which allows a limited way of external route propagation. Global external routes are not propagated
into a NSSA, but an external route can be imported into NSSA as a (area-wide) NSSA-LSA (and
possibly translated and/or aggregated on area boundary). By default, the area is not NSSA.
6.8. OSPF 51
summary switch
This option controls propagation of summary LSAs into stub or NSSA areas. If enabled, summary
LSAs are propagated as usual, otherwise just the default summary route (0.0.0.0/0) is propagated (this
is sometimes called totally stubby area). If a stub area has more area boundary routers, propagating
summary LSAs could lead to more efficient routing at the cost of larger link state database. Default
value is no.
default nssa switch
When summary option is enabled, default summary route is no longer propagated to the NSSA. In that
case, this option allows to originate default route as NSSA-LSA to the NSSA. Default value is no.
default cost num
This option controls the cost of a default route propagated to stub and NSSA areas. Default value is
1000.
default cost2 num
When a default route is originated as NSSA-LSA, its cost can use either type 1 or type 2 metric. This
option allows to specify the cost of a default route in type 2 metric. By default, type 1 metric (option
default cost) is used.
translator switch
This option controls translation of NSSA-LSAs into external LSAs. By default, one translator per
NSSA is automatically elected from area boundary routers. If enabled, this area boundary router
would unconditionally translate all NSSA-LSAs regardless of translator election. Default value is no.
translator stability num
This option controls the translator stability interval (in seconds). When the new translator is elected,
the old one keeps translating until the interval is over. Default value is 40.
networks { set }
Definition of area IP ranges. This is used in summary LSA origination. Hidden networks are not
propagated into other areas.
external { set }
Definition of external area IP ranges for NSSAs. This is used for NSSA-LSA translation. Hidden
networks are not translated into external LSAs. Networks can have configured route tag.
stubnet prefix { options }
Stub networks are networks that are not transit networks between OSPF routers. They are also
propagated through an OSPF area as a part of a link state database. By default, BIRD generates a
stub network record for each primary network address on each OSPF interface that does not have any
OSPF neighbors, and also for each non-primary network address on each OSPF interface. This option
allows to alter a set of stub networks propagated by this router.
Each instance of this option adds a stub network with given network prefix to the set of propagated
stub network, unless option hidden is used. It also suppresses default stub networks for given network
prefix. When option summary is used, also default stub networks that are subnetworks of given stub
network are suppressed. This might be used, for example, to aggregate generated stub networks.
interface pattern [instance num]
Defines that the specified interfaces belong to the area being defined. See interface (p. 12) common
option for detailed description. In OSPFv2, extended interface clauses are used, because each network
prefix is handled as a separate virtual interface.
You can specify alternative instance ID for the interface definition, therefore it is possible to have several
instances of that interface with different options or even in different areas. For OSPFv2, instance ID
support is an extension (RFC 6549) and is supposed to be set per-protocol. For OSPFv3, it is an
integral feature.
virtual link id [instance num]
Virtual link to router with the router id. Virtual link acts as a point-to-point interface belonging to
backbone. The actual area is used as a transport area. This item cannot be in the backbone. Like with
6.8. OSPF 52
interface option, you could also use several virtual links to one destination with different instance
IDs.
cost num
Specifies output cost (metric) of an interface. Default value is 10.
stub switch
If set to interface it does not listen to any packet and does not send any hello. Default value is no.
hello num
Specifies interval in seconds between sending of Hello messages. Beware, all routers on the same
network need to have the same hello interval. Default value is 10.
poll num
Specifies interval in seconds between sending of Hello messages for some neighbors on NBMA network.
Default value is 20.
retransmit num
Specifies interval in seconds between retransmissions of unacknowledged updates. Default value is 5.
transmit delay num
Specifies estimated transmission delay of link state updates send over the interface. The value is added
to LSA age of LSAs propagated through it. Default value is 1.
priority num
On every multiple access network (e.g., the Ethernet) Designated Router and Backup Designated router
are elected. These routers have some special functions in the flooding process. Higher priority increases
preferences in this election. Routers with priority 0 are not eligible. Default value is 1.
wait num
After start, router waits for the specified number of seconds between starting election and building
adjacency. Default value is 4*hello.
dead count num
When the router does not receive any messages from a neighbor in dead count*hello seconds, it will
consider the neighbor down.
dead num
When the router does not receive any messages from a neighbor in dead seconds, it will consider the
neighbor down. If both directives dead count and dead are used, dead has precedence.
rx buffer num
This option allows to specify the size of buffers used for packet processing. The buffer size should be
bigger than maximal size of any packets. By default, buffers are dynamically resized as needed, but a
fixed value could be specified. Value large means maximal allowed packet size - 65535.
tx length num
Transmitted OSPF messages that contain large amount of information are segmented to separate OSPF
packets to avoid IP fragmentation. This option specifies the soft ceiling for the length of generated
OSPF packets. Default value is the MTU of the network interface. Note that larger OSPF packets
may still be generated if underlying OSPF messages cannot be splitted (e.g. when one large LSA is
propagated).
type broadcast|bcast
BIRD detects a type of a connected network automatically, but sometimes it’s convenient to force use
of a different type manually. On broadcast networks (like ethernet), flooding and Hello messages are
sent using multicasts (a single packet for all the neighbors). A designated router is elected and it is
responsible for synchronizing the link-state databases and originating network LSAs. This network
type cannot be used on physically NBMA networks and on unnumbered networks (networks without
proper IP prefix).
6.8. OSPF 53
type pointopoint|ptp
Point-to-point networks connect just 2 routers together. No election is performed and no network LSA
is originated, which makes it simpler and faster to establish. This network type is useful not only for
physically PtP ifaces (like PPP or tunnels), but also for broadcast networks used as PtP links. This
network type cannot be used on physically NBMA networks.
type nonbroadcast|nbma
On NBMA networks, the packets are sent to each neighbor separately because of lack of multicast
capabilities. Like on broadcast networks, a designated router is elected, which plays a central role in
propagation of LSAs. This network type cannot be used on unnumbered networks.
type pointomultipoint|ptmp
This is another network type designed to handle NBMA networks. In this case the NBMA network is
treated as a collection of PtP links. This is useful if not every pair of routers on the NBMA network
has direct communication, or if the NBMA network is used as an (possibly unnumbered) PtP link.
bfd switch
OSPF could use BFD protocol as an advisory mechanism for neighbor liveness and failure detection.
If enabled, BIRD setups a BFD session for each OSPF neighbor and tracks its liveness by it. This
has an advantage of an order of magnitude lower detection times in case of failure. Note that BFD
protocol also has to be configured, see BFD (p. 28) section for details. Default value is no.
ttl security [switch | tx only]
TTL security is a feature that protects routing protocols from remote spoofed packets by using TTL
255 instead of TTL 1 for protocol packets destined to neighbors. Because TTL is decremented when
packets are forwarded, it is non-trivial to spoof packets with TTL 255 from remote locations. Note
that this option would interfere with OSPF virtual links.
If this option is enabled, the router will send OSPF packets with TTL 255 and drop received packets
with TTL less than 255. If this option si set to tx only, TTL 255 is used for sent packets, but is not
checked for received packets. Default value is no.
tx class|dscp|priority num
These options specify the ToS/DiffServ/Traffic class/Priority of the outgoing OSPF packets. See tx
class (p. 13) common option for detailed description.
ecmp weight num
When ECMP (multipath) routes are allowed, this value specifies a relative weight used for nexthops
going through the iface. Allowed values are 1-256. Default value is 1.
authentication none
No passwords are sent in OSPF packets. This is the default value.
authentication simple
Every packet carries 8 bytes of password. Received packets lacking this password are ignored. This
authentication mechanism is very weak. This option is not available in OSPFv3.
authentication cryptographic
An authentication code is appended to every packet. The specific cryptographic algorithm is selected
by option algorithm for each key. The default cryptographic algorithm for OSPFv2 keys is Keyed-
MD5 and for OSPFv3 keys is HMAC-SHA-256. Passwords are not sent open via network, so this
mechanism is quite secure. Packets can still be read by an attacker.
password "text"
Specifies a password used for authentication. See password (p. 13) common option for detailed descrip-
tion.
neighbors { set }
A set of neighbors to which Hello messages on NBMA or PtMP networks are to be sent. For NBMA
networks, some of them could be marked as eligible. In OSPFv3, link-local addresses should be used,
using global ones is possible, but it is nonstandard and might be problematic. And definitely, link-local
and global addresses should not be mixed.
6.8.3 Attributes
OSPF defines four route attributes. Each internal route has a metric.
Metric is ranging from 1 to infinity (65535). External routes use metric type 1 or metric type 2. A
metric of type 1 is comparable with internal metric, a metric of type 2 is always longer than any
metric of type 1 or any internal metric. Internal metric or metric of type 1 is stored in attribute
ospf metric1, metric type 2 is stored in attribute ospf metric2.
When both metrics are specified then metric of type 2 is used. This is relevant e.g. when a type 2
external route is propagated from one OSPF domain to another and ospf metric1 is an internal distance to
the original ASBR, while ospf metric2 stores the type 2 metric. Note that in such cases if ospf metric1
is non-zero then ospf metric2 is increased by one to ensure monotonicity of metric, as internal distance is
reset to zero when an external route is announced.
Each external route can also carry attribute ospf tag which is a 32-bit integer which is used when exporting
routes to other protocols; otherwise, it doesn’t affect routing inside the OSPF domain at all. The fourth
6.8. OSPF 55
attribute ospf router id is a router ID of the router advertising that route / network. This attribute is
read-only. Default is ospf metric2 = 10000 and ospf tag = 0.
6.8.4 Example
protocol ospf MyOSPF {
ipv4 {
export filter {
if source = RTS_BGP then {
ospf_metric1 = 100;
accept;
}
reject;
};
};
area 0.0.0.0 {
interface "eth*" {
cost 11;
hello 15;
priority 100;
retransmit 7;
authentication simple;
password "aaa";
};
interface "ppp*" {
cost 100;
authentication cryptographic;
password "abc" {
id 1;
generate to "22-04-2003 11:00:06";
accept from "17-01-2001 12:01:05";
algorithm hmac sha384;
};
password "def" {
id 2;
generate to "22-07-2005 17:03:21";
accept from "22-02-2001 11:34:06";
algorithm hmac sha512;
};
};
interface "arc0" {
cost 10;
stub yes;
};
interface "arc1";
};
area 120 {
stub yes;
networks {
172.16.1.0/24;
172.16.2.0/24 hidden;
};
interface "-arc0" , "arc*" {
type nonbroadcast;
authentication none;
strict nonbroadcast yes;
wait 120;
6.9. Perf 56
poll 40;
dead count 8;
neighbors {
192.168.120.1 eligible;
192.168.120.2;
192.168.120.10;
};
};
};
}
6.9 Perf
6.9.1 Introduction
The Perf protocol is a generator of fake routes together with a time measurement framework. Its purpose is
to check BIRD performance and to benchmark filters.
Import mode of this protocol runs in several steps. In each step, it generates 2ˆx routes, imports them into
the appropriate table and withdraws them. The exponent x is configurable. It runs the benchmark several
times for the same x, then it increases x by one until it gets too high, then it stops.
Export mode of this protocol repeats route refresh from table and measures how long it takes.
Output data is logged on info level. There is a Perl script proto/perf/parse.pl which may be handy to
parse the data and draw some plots.
Implementation of this protocol is experimental. Use with caution and do not keep any instance of Perf in
production configs for long time. The config interface is also unstable and may change in future versions
without warning.
6.9.2 Configuration
mode import|export
Set perf mode. Default: import
repeat number
Run this amount of iterations of the benchmark for every amount step. Default: 4
exp from number
Begin benchmarking on this exponent for number of generated routes in one step. Default: 10
exp to number
Stop benchmarking on this exponent. Default: 20
threshold min time
If a run for the given exponent took less than this time for route import, increase the exponent
immediately. Default: 1 ms
6.10 Pipe
6.10.1 Introduction
The Pipe protocol serves as a link between two routing tables, allowing routes to be passed from a table
declared as primary (i.e., the one the pipe is connected to using the table configuration keyword) to the
secondary one (declared using peer table) and vice versa, depending on what’s allowed by the filters.
6.10. Pipe 57
Export filters control export of routes from the primary table to the secondary one, import filters control
the opposite direction. Both tables must be of the same nettype.
The Pipe protocol retransmits all routes from one table to the other table, retaining their original source
and attributes. If import and export filters are set to accept, then both tables would have the same content.
The primary use of multiple routing tables and the Pipe protocol is for policy routing, where handling of a
single packet doesn’t depend only on its destination address, but also on its source address, source interface,
protocol type and other similar parameters. In many systems (Linux being a good example), the kernel
allows to enforce routing policies by defining routing rules which choose one of several routing tables to be
used for a packet according to its parameters. Setting of these rules is outside the scope of BIRD’s work (on
Linux, you can use the ip command), but you can create several routing tables in BIRD, connect them to
the kernel ones, use filters to control which routes appear in which tables and also you can employ the Pipe
protocol for exporting a selected subset of one table to another one.
6.10.2 Configuration
Essentially, the Pipe protocol is just a channel connected to a table on both sides. Therefore, the configuration
block for protocol pipe shall directly include standard channel config options; see the example below.
6.10.3 Attributes
The Pipe protocol doesn’t define any route attributes.
6.10.4 Example
Let’s consider a router which serves as a boundary router of two different autonomous systems, each of them
connected to a subset of interfaces of the router, having its own exterior connectivity and wishing to use the
other AS as a backup connectivity in case of outage of its own exterior line.
Probably the simplest solution to this situation is to use two routing tables (we’ll call them as1 and as2)
and set up kernel routing rules, so that packets having arrived from interfaces belonging to the first AS will
be routed according to as1 and similarly for the second AS. Thus we have split our router to two logical
routers, each one acting on its own routing table, having its own routing protocols on its own interfaces. In
order to use the other AS’s routes for backup purposes, we can pass the routes between the tables through a
Pipe protocol while decreasing their preferences and correcting their BGP paths to reflect the AS boundary
crossing.
6.11 RAdv
6.11.1 Introduction
The RAdv protocol is an implementation of Router Advertisements, which are used in the IPv6 stateless
autoconfiguration. IPv6 routers send (in irregular time intervals or as an answer to a request) advertisement
packets to connected networks. These packets contain basic information about a local network (e.g. a list
of network prefixes), which allows network hosts to autoconfigure network addresses and choose a default
route. BIRD implements router behavior as defined in RFC 4861, router preferences and specific routes
(RFC 4191), and DNS extensions (RFC 6106).
The RAdv protocols supports just IPv6 channel.
6.11.2 Configuration
There are several classes of definitions in RAdv configuration – interface definitions, prefix definitions and
DNS definitions:
processed before global definitions. As expected, the prefix definition is matching if the network prefix
is a subnet of the prefix in prefix definition.
rdnss { options }
RDNSS definitions allow to specify a list of advertised recursive DNS servers together with their options.
As options are seldom necessary, there is also a short variant rdnss address that just specifies one DNS
server. Multiple definitions are cumulative. RDNSS definitions may also be interface-specific when used
inside interface options. By default, interface uses both global and interface-specific options, but that
can be changed by rdnss local option.
dnssl { options }
DNSSL definitions allow to specify a list of advertised DNS search domains together with their options.
Like rdnss above, multiple definitions are cumulative, they can be used also as interface-specific options
and there is a short variant dnssl domain that just specifies one DNS search domain.
trigger prefix
RAdv protocol could be configured to change its behavior based on availability of routes. When this
option is used, the protocol waits in suppressed state until a trigger route (for the specified network) is
exported to the protocol, the protocol also returns to suppressed state if the trigger route disappears.
Note that route export depends on specified export filter, as usual. This option could be used, e.g., for
handling failover in multihoming scenarios.
During suppressed state, router advertisements are generated, but with some fields zeroed. Exact
behavior depends on which fields are zeroed, this can be configured by sensitive option for appropriate
fields. By default, just default lifetime (also called router lifetime) is zeroed, which means hosts
cannot use the router as a default router. preferred lifetime and valid lifetime could also be
configured as sensitive for a prefix, which would cause autoconfigured IPs to be deprecated or even
removed.
propagate routes switch
This option controls propagation of more specific routes, as defined in RFC 4191. If enabled, all routes
exported to the RAdv protocol, with the exception of the trigger prefix, are added to advertisments
as additional options. The lifetime and preference of advertised routes can be set individually by
ra lifetime and ra preference route attributes, or per interface by route lifetime and route
preference options. Default: disabled.
Note that the RFC discourages from sending more than 17 routes and recommends the routes to be
configured manually.
skip switch
This option allows to specify that given prefix should not be advertised. This is useful for making
exceptions from a default policy of advertising all prefixes. Note that for withdrawing an already
advertised prefix it is more useful to advertise it with zero valid lifetime. Default: no
6.11. RAdv 61
onlink switch
This option specifies whether hosts may use the advertised prefix for onlink determination. Default:
yes
autonomous switch
This option specifies whether hosts may use the advertised prefix for stateless autoconfiguration. De-
fault: yes
valid lifetime expr [sensitive switch]
This option specifies the time (in seconds) how long (after the receipt of RA) the prefix information is
valid, i.e., autoconfigured IP addresses can be assigned and hosts with that IP addresses are considered
directly reachable. 0 means the prefix is no longer valid. For sensitive option, see trigger (p. 59).
Default: 86400 (1 day), sensitive no.
preferred lifetime expr [sensitive switch]
This option specifies the time (in seconds) how long (after the receipt of RA) IP addresses generated
from the prefix using stateless autoconfiguration remain preferred. For sensitive option, see trigger
(p. 59). Default: 14400 (4 hours), sensitive no.
ns address
This option specifies one recursive DNS server. Can be used multiple times for multiple servers. It is
mandatory to have at least one ns option in rdnss definition.
lifetime [mult] expr
This option specifies the time how long the RDNSS information may be used by clients after the receipt
of RA. It is expressed either in seconds or (when mult is used) in multiples of max ra interval. Note
that RDNSS information is also invalidated when default lifetime expires. 0 means these addresses
are no longer valid DNS servers. Default: 3 * max ra interval.
domain address
This option specifies one DNS search domain. Can be used multiple times for multiple domains. It is
mandatory to have at least one domain option in dnssl definition.
lifetime [mult] expr
This option specifies the time how long the DNSSL information may be used by clients after the receipt
of RA. Details are the same as for RDNSS lifetime option above. Default: 3 * max ra interval.
6.11.3 Attributes
RAdv defines two route attributes:
enum ra preference
The preference of the route. The value can be RA PREF LOW , RA PREF MEDIUM or
RA PREF HIGH . If the attribute is not set, the route preference (p. 60) option is used.
int ra lifetime
The advertised lifetime of the route, in seconds. The special value of 0xffffffff represents infinity. If the
attribute is not set, the route lifetime (p. 60) option is used.
6.11.4 Example
6.12. RIP 62
protocol static {
ipv6 { table radv_routes; };
protocol radv {
propagate routes yes; # Propagate the routes from the radv_routes table
ipv6 { table radv_routes; export all; };
interface "eth2" {
max ra interval 5; # Fast failover with more routers
managed yes; # Using DHCPv6 on eth2
prefix ::/0 {
autonomous off; # So do not autoconfigure any IP
};
};
prefix 2001:0DB8:1234::/48 {
preferred lifetime 0; # Deprecated address range
};
prefix 2001:0DB8:2000::/48 {
autonomous off; # Do not autoconfigure
};
rdnss {
lifetime mult 10;
ns 2001:0DB8:1234::11;
ns 2001:0DB8:1234::12;
};
dnssl {
lifetime 3600;
domain "abc.com";
domain "xyz.com";
};
}
6.12 RIP
6.12.1 Introduction
The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts
(to all its neighbors) distances to all networks it can reach. When a router hears distance to another network,
6.12. RIP 63
it increments it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network
goes unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually,
plus interface metric, which is usually one). After some time, the distance reaches infinity (that’s 15 in RIP)
and all routers know that network is unreachable. RIP tries to minimize situations where counting to infinity
is necessary, because it is slow. Due to infinity being 16, you can’t use RIP on networks where maximal
distance is higher than 15 hosts.
BIRD supports RIPv1 (RFC 1058), RIPv2 (RFC 2453), RIPng (RFC 2080), Triggered RIP for demand
circuits (RFC 2091), and RIP cryptographic authentication (RFC 4822).
RIP is a very simple protocol, and it has a lot of shortcomings. Slow convergence, big network load and
inability to handle larger networks makes it pretty much obsolete. It is still usable on very small networks.
6.12.2 Configuration
RIP configuration consists mainly of common protocol options and interface definitions, most RIP options
are interface specific. RIPng (RIP for IPv6) protocol instance can be configured by using rip ng instead of
just rip as a protocol type.
RIP needs one IPv4 channel. RIPng needs one IPv6 channel. If no channel is configured, appropriate channel
is defined with default parameters.
infinity number
Selects the distance of infinity. Bigger values will make protocol convergence even slower. The default
value is 16.
metric num
This option specifies the metric of the interface. When a route is received from the interface, its metric
is increased by this value before further processing. Valid values are 1-255, but values higher than
infinity has no further meaning. Default: 1.
mode multicast|broadcast
This option selects the mode for RIP to use on the interface. The default is multicast mode for RIPv2
and broadcast mode for RIPv1. RIPng always uses the multicast mode.
passive switch
Passive interfaces receive routing updates but do not transmit any messages. Default: no.
address ip
This option specifies a destination address used for multicast or broadcast messages, the default is the
official RIP (224.0.0.9) or RIPng (ff02::9) multicast address, or an appropriate broadcast address in
the broadcast mode.
port number
This option selects an UDP port to operate on, the default is the official RIP (520) or RIPng (521)
port.
version 1|2
This option selects the version of RIP used on the interface. For RIPv1, automatic subnet aggregation
is not implemented, only classful network routes and host routes are propagated. Note that BIRD
allows RIPv1 to be configured with features that are defined for RIPv2 only, like authentication or
using multicast sockets. The default is RIPv2 for IPv4 RIP, the option is not supported for RIPng, as
no further versions are defined.
tx class|dscp|priority number
These options specify the ToS/DiffServ/Traffic class/Priority of the outgoing RIP packets. See tx class
(p. 13) common option for detailed description.
rx buffer number
This option specifies the size of buffers used for packet processing. The buffer size should be bigger
than maximal size of received packets. The default value is 532 for IPv4 RIP and interface MTU value
for RIPng.
6.13. RPKI 66
tx length number
This option specifies the maximum length of generated RIP packets. To avoid IP fragmentation, it
should not exceed the interface MTU value. The default value is 532 for IPv4 RIP and interface MTU
value for RIPng.
check link switch
If set, the hardware link state (as reported by OS) is taken into consideration. When the link disappears
(e.g. an ethernet cable is unplugged), neighbors are immediately considered unreachable and all routes
received from them are withdrawn. It is possible that some hardware drivers or platforms do not
implement this feature. Default: yes.
6.12.3 Attributes
RIP defines two route attributes:
6.12.4 Example
protocol rip {
ipv4 {
import all;
export all;
};
interface "eth*" {
metric 2;
port 1520;
mode multicast;
update time 12;
timeout time 60;
authentication cryptographic;
password "secret" { algorithm hmac sha256; };
};
}
6.13 RPKI
6.13.1 Introduction
The Resource Public Key Infrastructure (RPKI) is mechanism for origin validation of BGP routes (RFC
6480). BIRD supports only so-called RPKI-based origin validation. There is implemented RPKI to Router
(RPKI-RTR) protocol (RFC 6810). It uses some of the RPKI data to allow a router to verify that the
autonomous system announcing an IP address prefix is in fact authorized to do so. This is not crypto
checked so can be violated. But it should prevent the vast majority of accidental hijackings on the Internet
today, e.g. the famous Pakistani accidental announcement of YouTube’s address space.
The RPKI-RTR protocol receives and maintains a set of ROAs from a cache server (also called validator).
You can validate routes (RFC 6483, RFC 6811) using function roa check() in filter and set it as import
filter at the BGP protocol. BIRD offers crude automatic re-validating of affected routes after RPKI update,
6.13. RPKI 67
see option rpki reload (p. 14). Or you can use a BIRD client command reload in bgp protocol name for
manual call of revalidation of all routes.
6.13.3 Configuration
We currently support just one cache server per protocol. However you can define more RPKI protocols
generally.
Alse note that you have to specify the ROA channel. If you want to import only IPv4 prefixes you have to
specify only roa4 channel. Similarly with IPv6 prefixes only. If you want to fetch both IPv4 and even IPv6
ROAs you have to specify both channels.
data for this time period. Must be in range from 600 seconds (ten minutes) to 172800 seconds (two
days). A keyword keep suppresses updating this value by a cache server. Default: 7200 seconds
ignore max length switch
Ignore received max length in ROA records and use max value (32 or 128) instead. This may be useful
for implementing loose RPKI check for blackholes. Default: disabled.
transport tcp
Unprotected transport over TCP. It’s a default transport. Should be used only on secure private
networks. Default: tcp
user "name"
A SSH user name for authentication. This option is a required.
6.13.4 Examples
BGP origin validation
protocol rpki {
debug all;
retry keep 5;
refresh keep 30;
expire 600;
}
filter peer_in_v4 {
if (roa_check(r4, net, bgp_path.last) = ROA_INVALID) then
{
print "Ignore RPKI invalid ", net, " for ASN ", bgp_path.last;
reject;
}
accept;
}
protocol bgp {
6.14. Static 69
debug all;
local as 65000;
neighbor 192.168.2.1 as 65001;
ipv4 {
import filter peer_in_v4;
export none;
};
}
protocol rpki {
debug all;
6.14 Static
The Static protocol doesn’t communicate with other routers in the network, but instead it allows you to
define routes manually. This is often used for specifying how to forward packets to parts of the network
which don’t use dynamic routing at all and also for defining sink routes (i.e., those telling to return packets
as undeliverable if they are in your IP block, you don’t have any specific destination for them and you don’t
want to send them out through the default route to prevent routing loops).
There are three classes of definitions in Static protocol configuration – global options, static route definitions,
and per-route options. Usually, the definition of the protocol contains mainly a list of static routes. Static
routes have no specific attributes, but igp metric (p. 25) attribute is used to compare static routes with the
same preference.
The list of static routes may contain multiple routes for the same network (usually, but not necessary,
distinquished by preference or igp metric), but only routes of the same network type are allowed, as
the static protocol has just one channel. E.g., to have both IPv4 and IPv6 static routes, define two static
protocols, each with appropriate routes and channel.
Global options:
When the particular destination is not available (the interface is down or the next hop of the route is not a
neighbor at the moment), Static just uninstalls the route from the table it is connected to and adds it again
as soon as the destination becomes adjacent again.
Per-nexthop options
There are several options that in a case of multipath route are per-nexthop (i.e., they can be used multiple
times for a route, one time for each nexthop). Syntactically, they are not separate options but just parts of
route statement after each via statement, not separated by semicolons. E.g., statement route 10.0.0.08
via 192.0.2.1 bfd weight 1 via 192.0.2.2 weight 2;/ describes a route with two nexthops, the first nexthop has
two per-nexthop options (bfd and weight 1), the second nexthop has just weight 2.
bfd switch
The Static protocol could use BFD protocol for next hop liveness detection. If enabled, a BFD session
to the route next hop is created and the static route is BFD-controlled – the static route is announced
only if the next hop liveness is confirmed by BFD. If the BFD session fails, the static route (or just
the affected nexthop from multiple ones) is removed. Note that this is a bit different compared to
other protocols, which may use BFD as an advisory mechanism for fast failure detection but ignore it
if a BFD session is not even established. Note that BFD protocol also has to be configured, see BFD
(p. 28) section for details. Default value is no.
mpls num[/num[/num[...]]]
MPLS labels that should be pushed to packets forwarded by the route. The option could be used
for both IP routes (on MPLS ingress routers) and MPLS switching rules (on MPLS transit routers).
Default value is no labels.
onlink switch
Onlink flag means that the specified nexthop is accessible on the (specified) interface regardless of IP
prefixes of the interface. The interface must be attached to nexthop IP address using link-local-scope
format (e.g. 192.0.2.1%eth0). Default value is no.
weight switch
For multipath routes, this value specifies a relative weight of the nexthop. Allowed values are 1-256.
Default value is 1.
6.14.3 Flowspec
The flow specification are rules for routers and firewalls for filtering purpose. It is described by RFC
5575. There are 3 types of arguments: inet4 or inet6 prefixes, bitmasks matching expressions and numbers
matching expressions.
Bitmasks matching is written using value/mask or !value/mask pairs. It means that (data & mask ) is or is
not equal to value.
Numbers matching is a matching sequence of numbers and ranges separeted by a commas (,) (e.g. 10,20,30).
Ranges can be written using double dots .. notation (e.g. 80..90,120..124). An alternative notation are
sequence of one or more pairs of relational operators and values separated by logical operators && or ||.
Allowed relational operators are =, !=, <, <=, >, >=, true and false.
IPv4 Flowspec
dst inet4
Set a matching destination prefix (e.g. dst 192.168.0.0/16). Only this option is mandatory in IPv4
Flowspec.
src inet4
Set a matching source prefix (e.g. src 10.0.0.0/8).
proto numbers-match
Set a matching IP protocol numbers (e.g. proto 6).
port numbers-match
Set a matching source or destination TCP/UDP port numbers (e.g. port 1..1023,1194,3306).
dport numbers-match
Set a mating destination port numbers (e.g. dport 49151).
sport numbers-match
Set a matching source port numbers (e.g. sport = 0).
dscp numbers-match
Set a matching DiffServ Code Point number (e.g. length > 1500;).
fragment fragmentation-type
Set a matching type of packet fragmentation. Allowed fragmentation types are dont fragment,
is fragment, first fragment, last fragment (e.g. fragment is fragment && !dont fragment).
protocol static {
flow4;
route flow4 {
dst 10.0.0.0/8;
port > 24 && < 30 || 40..50,60..70,80 && >= 90;
tcp flags 0x03/0x0f;
6.14. Static 72
• Prefixes inet6 can be specified not only with prefix length, but with prefix offset num too (e.g.
::1234:5678:9800:0000/101 offset 64). Offset means to don’t care of num first bits.
• IPv6 Flowspec hasn’t mandatory any flowspec component.
• In IPv6 packets, there is a matching the last next header value for a matching IP protocol number
(e.g. next header 6).
protocol static {
flow6 { table myflow6; };
route flow6 {
dst fec0:1122:3344:5566:7788:99aa:bbcc:ddee/128;
src 0000:0000:0000:0001:1234:5678:9800:0000/101 offset 63;
next header = 23;
sport > 24 && < 30 || = 40 || 50,60,70..80;
dport = 50;
tcp flags 0x03/0x0f, !0/0xff || 0x33/0x33;
fragment !is_fragment || !first_fragment;
label 0xaaaa/0xaaaa && 0x33/0x33;
};
}
protocol static {
ipv4 { table testable; }; # Connect to a non-default routing table
check link; # Advertise routes only if link is up
route 0.0.0.0/0 via 198.51.100.130; # Default route
route 10.0.0.0/8 # Multipath route
via 198.51.100.10 weight 2
via 198.51.100.20 bfd # BFD-controlled next hop
via 192.0.2.1;
route 203.0.113.0/24 blackhole; # Sink route
route 10.2.0.0/24 via "arc0"; # Secondary network
route 192.168.10.0/24 via 198.51.100.100 {
ospf_metric1 = 20; # Set extended attribute
};
route 192.168.11.0/24 via 198.51.100.100 {
ospf_metric2 = 100; # Set extended attribute
ospf_tag = 2; # Set extended attribute
};
route 192.168.12.0/24 via 198.51.100.100 {
bgp_community.add((65535, 65281)); # Set extended BGP attribute
bgp_large_community.add((64512, 1, 1)); # Set extended BGP attribute
};
}
protocol static {
ipv6; # Channel is mandatory
route 2001:db8:10::/48 via 2001:db8:1::1; # Route with global nexthop
route 2001:db8:20::/48 via fe80::10%eth0; # Route with link-local nexthop
route 2001:db8:30::/48 via fe80::20%’eth1.60’; # Iface with non-alphanumeric charac
route 2001:db8:40::/48 via "eth2"; # Direct route to eth2
route 2001:db8::/32 unreachable; # Unreachable route
route ::/0 via 2001:db8:1::1 bfd; # BFD-controlled default route
}
Chapter 7: Conclusions
7.1 Future work
Although BIRD supports all the commonly used routing protocols, there are still some features which would
surely deserve to be implemented in future versions of BIRD:
• Opaque LSA’s
74