3. Configuration
3.1 Introduction
BIRD is configured using a text configuration file. Upon startup, BIRD reads
prefix/etc/bird.conf
(unless the -c
command line option
is given). Configuration may be changed at user's request: if you modify the
config file and then signal BIRD with SIGHUP
, it will adjust to the new
config. Then there's the client which allows you to talk with BIRD in an
extensive way.
In the config, everything on a line after #
or inside /* */
is
a comment, whitespace characters are treated as a single space. If there's a
variable number of options, they are grouped using the { }
brackets. Each
option is terminated by a ;
. Configuration is case sensitive. There are two
ways how to name symbols (like protocol names, filter names, constants etc.). You
can either use a simple string starting with a letter followed by any
combination of letters and numbers (e.g. "R123", "myfilter", "bgp5") or you can
enclose the name into apostrophes ('
) and than you can use any combination
of numbers, letters. hyphens, dots and colons (e.g. "'1:strange-name'",
"'-NAME-'", "'cool::name'").
Here is an example of a simple config file. It enables synchronization of routing tables with OS kernel, scans for new network interfaces every 10 seconds and runs RIP on all network interfaces found.
protocol kernel { persist; # Don't remove routes on BIRD shutdown scan time 20; # Scan kernel routing table every 20 seconds export all; # Default is export none } protocol device { scan time 10; # Scan interfaces every 10 seconds } protocol rip { export all; import all; interface "*"; }
3.2 Global options
include "filename"
This statement causes inclusion of a new file. Filename could also be a wildcard, in that case matching files are included in alphabetic order. The maximal depth is 8. Note that this statement could be used anywhere in the config file, not just as a top-level option.
log "filename"|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, syslog with optional name argument, or the stderr output). Classes are:info
,warning
,error
andfatal
for messages about local problems,debug
for debugging messages,trace
when you want to know what happens in the network,remote
for messages about misbehavior of remote machines,auth
about authentication failures,bug
for internal BIRD bugs. You may specify more than onelog
line to establish logging to multiple destinations. Default: log everything to the system log.debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, ...] }
Set global defaults of protocol debugging options. See
debug
in the following 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 anyname
). You can learn more about configuring protocols in their own chapters. Whenfrom name2
expression is used, initial protocol options are taken from protocol or templatename2
You can run more than one instance of most protocols (like RIP or BGP). By default, no instances are configured.template rip|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 (andfrom
expression) are not implemented for OSPF protocol.define constant = expression
Define a constant. You can use it later in every place you could use a value of the same type. Besides, there are some predefined numeric constants based on /etc/iproute2/rt_* files. A list of defined constants can be seen (together with other symbols) using 'show symbols' command.
router id IPv4 address
Set BIRD's router ID. It's a world-wide unique identification of your router, usually one of router's IPv4 addresses. Default: in IPv4 version, the lowest IP address of a non-loopback interface. In IPv6 version, this option is mandatory.
router id from [-] [ "mask" ] [ prefix ] [, ...]
Set BIRD's router ID based on an IP address of an interface specified by an interface pattern. The option is applicable for IPv4 version only. See interface section for detailed description of interface patterns with extended clauses.
listen bgp [address address] [port port] [dual]
This option allows to specify address and port where BGP protocol should listen. It is global option as listening socket is common to all BGP instances. Default is to listen on all addresses (0.0.0.0) and port 179. In IPv6 mode, option
dual
can be used to specify that BGP socket should accept both IPv4 and IPv6 connections (but even in that case, BIRD would accept IPv6 routes only). Such behavior was default in older versions of BIRD.graceful restart wait number
During graceful restart recovery, BIRD waits for convergence of routing protocols. This option allows to specify a timeout for the recovery to prevent waiting indefinitely if some protocols cannot converge. Default: 240 seconds.
timeformat route|protocol|base|log "format1" [limit "format2"]
This option allows to specify a format of date/time used by BIRD. The first argument specifies for which purpose such format is used.
route
is a format used in 'show route' command output,protocol
is used in 'show protocols' command output,base
is used for other commands andlog
is used in a log file."format1" is a format string using strftime(3) notation (see man strftime for details). limit> and "format2" allow to specify the second format string for times in past deeper than limit seconds. There are few shorthands:
iso long
is a ISO 8601 datetime format (YYYY-MM-DD hh:mm:ss) that can be also specified using"%F %T"
.iso short
is a variant of ISO 8601 that uses just the time format (hh:mm:ss) for near times (up to 20 hours in the past) and the date format (YYYY-MM-DD) for far times. This is a shorthand for"%T" 72000 "%F"
.By default, BIRD uses the
iso short
format forroute
andprotocol
times, and theiso long
format forbase
andlog
times.In pre-1.4.0 versions, BIRD used an short, ad-hoc format for
route
andprotocol
times, and aiso long
similar format (DD-MM-YYYY hh:mm:ss) forbase
andlog
. These timeformats could be set byold short
andold long
compatibility shorthands.table name [sorted]
Create a new routing table. The default routing table is created implicitly, other routing tables have to be added by this command. Option
sorted
can be used to enable sorting of routes, see sorted table description for details.roa table name [ { roa table options ... } ]
Create a new ROA (Route Origin Authorization) table. ROA tables can be used to validate route origination of BGP routes. A ROA table contains ROA entries, each consist of a network prefix, a max prefix length and an AS number. A ROA entry specifies prefixes which could be originated by that AS number. ROA tables could be filled with data from RPKI (RFC 6480) or from public databases like Whois. ROA tables are examined by
roa_check()
operator in filters.Currently, there is just one option,
roa prefix max num as num
, which can be used to populate the ROA table with static ROA entries. The option may be used multiple times. Other entries can be added dynamically byadd roa
command.eval expr
Evaluates given filter expression. It is used by us for testing of filters.
3.3 Protocol options
For each protocol instance, you can configure a bunch of options. Some of them (those described in this section) are generic, some are specific to the protocol (see sections talking about the protocols).
Several options use a switch argument. It can be either on
,
yes
or a numeric expression with a non-zero value for the option to be
enabled or off
, no
or a numeric expression evaluating to zero to
disable it. An empty switch is equivalent to on
("silence means
agreement").
preference expr
Sets the preference of routes generated by this protocol. Default: protocol dependent.
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 ofall
trace messages or only of the types selected: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 andpackets
for packets sent and received by the protocol. 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 ofdebug
option, their meaning is different and protocol-specific. For BGP protocol,states
logs BGP state changes andmessages
logs received BGP messages. Other protocols does not support MRTdump yet.router id IPv4 address
This option can be used to override global router id for a given protocol. Default: uses global router id.
import all | none | filter name | filter { filter commands } | where filter expression
Specify a filter to be used for filtering routes coming from the protocol to the routing table.
all
is shorthand forwhere true
andnone
is shorthand forwhere false
. Default:all
.export filter
This is similar to the
import
keyword, except that it works in the direction from the routing table to the protocol. Default:none
.import keep filtered switch
Usually, if an import filter rejects a route, the route is forgotten. When this option is active, these routes are kept in the routing table, but they are hidden and not propagated to other protocols. But it is possible to show them using
show route filtered
. Note that this option does not work for the pipe protocol. Default: off.import limit [number | off ] [action warn | block | restart | disable]
Specify an import route limit (a maximum number of routes imported from the protocol) and optionally the action to be taken when the limit is hit. Warn action just prints warning log message. Block action discards new routes coming from the protocol. Restart and disable actions shut the protocol down like appropriate commands. Disable is the default action if an action is not explicitly specified. Note that limits are reset during protocol reconfigure, reload or restart. Default:
off
.receive limit [number | off ] [action warn | block | restart | disable]
Specify an receive route limit (a maximum number of routes received from the protocol and remembered). It works almost identically to
import limit
option, the only difference is that ifimport keep filtered
option is active, filtered routes are counted towards the limit and blocked routes are forgotten, as the main purpose of the receive limit is to protect routing tables from overflow. Import limit, on the contrary, counts accepted routes only and routes blocked by the limit are handled like filtered routes. Default:off
.export limit [ number | off ] [action warn | block | restart | disable]
Specify an export route limit, works similarly to the
import limit
option, but for the routes exported to the protocol. This option is experimental, there are some problems in details of its behavior -- the number of exported routes can temporarily exceed the limit without triggering it during protocol reload, exported routes counter ignores route blocking and block action also blocks route updates of already accepted routes -- and these details will probably change in the future. Default:off
.description "text"
This is an optional description of the protocol. It is displayed as a part of the output of 'show protocols all' command.
table name
Connect this protocol to a non-default routing table.
vrf "text"|default
Associate the protocol with specific VRF. The protocol will be restricted to interfaces assigned to the VRF and will use sockets bound to the VRF. A corresponding VRF interface must exist on OS level. For kernel protocol, an appropriate table still must be explicitly selected by
table
option.By selecting
default
, the protocol is associated with the default VRF; i.e., it will be restricted to interfaces not assigned to any regular VRF. That is different from not specifyingvrf
at all, in which case the protocol may use any interface regardless of its VRF status.Note that for proper VRF support it is necessary to use Linux kernel version at least 4.14, older versions have limited VRF implementation. Before Linux kernel 5.0, a socket bound to a port in default VRF collide with others in regular VRFs.
There are several options that give sense only with certain protocols:
interface [-] [ "mask" ] [ prefix ] [, ...] [ { option; [...] } ]
Specifies a set of interfaces on which the protocol is activated with given interface-specific options. A set of interfaces specified by one interface option is described using an interface pattern. The interface pattern consists of a sequence of clauses (separated by commas), each clause is a mask specified as a shell-like pattern. Interfaces are matched by their name.
An interface matches the pattern if it matches any of its clauses. If the clause begins with
-
, matching interfaces are excluded. Patterns are processed left-to-right, thusinterface "eth0", -"eth*", "*";
means eth0 and all non-ethernets.Some protocols (namely OSPFv2 and Direct) support extended clauses that may contain a mask, a prefix, or both of them. An interface matches such clause if its name matches the mask (if specified) 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, Direct, OSPF, RAdv and RIP protocols, but in OSPF protocol it is used in the
area
subsection.Default: none.
Examples:
interface "*" { type broadcast; };
- start the protocol on all interfaces withtype broadcast
option.interface "eth1", "eth4", "eth5" { type ptp; };
- start the protocol on enumerated interfaces withtype ptp
option.interface -192.168.1.0/24, 192.168.0.0/16;
- start the protocol on all interfaces that have address from 192.168.0.0/16, but not from 192.168.1.0/24.interface -192.168.1.0/24, 192.168.0.0/16;
- start the protocol on all interfaces that have address 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). Withdscp
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, (1-255). If it is not used, BIRD will choose ID based on an order of the password item in the interface. For example, second password item in one interface will have default ID 2. 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
isdd-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.
from "time"
Shorthand for setting both
generate from
andaccept from
.to "time"
Shorthand for setting both
generate to
andaccept 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.
Next Previous Contents