BIRD 2.18.1 User's Guide: Configuration

Next Previous Contents

## 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 (or underscore) followed by any combination of letters, numbers and underscores (e.g. `R123`, `my_filter`, `bgp5`) or you can enclose the name into apostrophes (`'`) and than you can use any combination of numbers, letters, underscores, hyphens, dots and colons (e.g. `'1:strange-name'`, `'-NAME-'`, `'cool::name'`).

In most cases where options use an argument that is a basic data type (e.g. number, string, IP address) it is possible to use a named constant (defined by define statement), or a constant expression enclosed in parenthesis (e.g. `(2 + 2)`). These expressions use the BIRD filter language.

Here is an example of a simple config file. It enables synchronization of routing tables with OS kernel, learns network interfaces and runs RIP on all network interfaces found.

    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 "*";
    }

## 3.2 Global options

`include "filename";`

  This statement causes inclusion of a new file. The 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 can be used anywhere in the config file, even inside other options, but always on the beginning of line. In the following example, the first semicolon belongs to the `include`, the second to `ipv6 table`. If the `tablename.conf` contains exactly one token (the name of the table), this construction is correct:

      ipv6 table
      include "tablename.conf";;

`log "filename" [limit "backup"] | syslog [name name] | stderr | udp address [port port] 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), the stderr output, or as a UDP message (in RFC 3164 syslog format).

  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 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 in the following section. Default: off.

`debug channels all|off|{ states|routes|filters|events [, ...] }`

  Set global defaults of channel debugging options. See debug in the channel section. Default: off.

`debug tables all|off|{ states|routes|filters|events [, ...] }`

  Set global defaults of table debugging options. See debug in the table 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) [ -> return type ] 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.

`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.

`attribute type name`

  Declare a custom route attribute. You can set and get it in filters like any other route attribute. This feature is intended for marking routes in import filters for export filtering purposes instead of locally assigned BGP communities which have to be deleted in export filters.

`router id number | IPv4 address`

  Set BIRD's router ID. It's a 4-byte non-zero integer that should be unique within an AS. Default: the lowest IPv4 address of the router.

`router id from [-] [ "mask" ] [ prefix ] [, ...]`

  Set BIRD's router ID based on an IPv4 address of an interface specified by an interface pattern. See interface section for detailed description of interface patterns with extended clauses.

`hostname "name"`

  Set hostname. Default: node name as returned by `uname -n'.

`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 and `log` is used in a log file.

  "format1" is a format string using strftime(3) notation (see man strftime for details). It is extended to support sub-second time part with variable precision (up to microseconds) using "%f" conversion code (e.g., "%T.%3f" is hh:mm:ss.sss time). limit and "format2" allow to specify the second format string for times in past deeper than limit seconds.

  There are several shorthands: `iso long` is a ISO 8601 date/time format (YYYY-MM-DD hh:mm:ss) that can be also specified using `"%F %T"`. Similarly, `iso long ms` and `iso long us` are ISO 8601 date/time formats with millisecond or microsecond precision. `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"`. And there are also `iso short ms` and `iso short us` high-precision variants of that.

  By default, BIRD uses the `iso short ms` format for `route` and `protocol` times, and the `iso long ms` format for `base` and `log` times.

`nettype table name [ { option; [...] } ]`

  Define a new routing table. The default routing tables `master4` and `master6` are defined implicitly, other routing tables have to be defined by this option. See the routing table configuration section for routing table options.

`mpls domain name [ { option; [...] } ]`

  Define a new MPLS domain. MPLS domains represent independent label spaces and are responsible for MPLS label management. All MPLS-aware protocols are associated with some MPLS domain. See the MPLS configuration section for MPLS domain options.

`eval expr`

  Evaluates given filter expression. It is used by the developers for testing of filters.

## 3.3 Routing table options

Most routing tables do not need any options and are defined without an option block, but there are still some options to tweak routing table behavior. Note that implicit tables (`master4` and `master6`) can be redefined in order to set options.

`debug all|off|{ states|routes|filters [, ...] }`

  Set table debugging options. Like in protocol debugging, tables are capable of writing trace messages about its work to the log (with category `trace`). For now, this does nothing, but in version 3, it is used. Default: off.

`sorted switch`

  Usually, a routing table just chooses the selected (best) route from a list of routes for each network, while keeping remaining routes unsorted. If enabled, these lists of routes are kept completely sorted (according to preference or some protocol-dependent metric).

  This is needed for some protocol features (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. Default: off.

`trie switch`

  BIRD routing tables are implemented with hash tables, which is efficient for exact-match lookups, but inconvenient for longest-match lookups or interval lookups (finding superprefix or subprefixes). This option activates additional trie structure that is used to accelerate these lookups, while using the hash table for exact-match lookups.

  This has advantage for RPKI (on ROA tables), for recursive next-hops (on IGP tables), and is required for flowspec validation (on base IP tables). Another advantage is that interval results (like from `show route in ...` command) are lexicographically sorted. The disadvantage is that trie-enabled routing tables require more memory, which may be an issue especially in multi-table setups. Default: off.

`min settle time time`

  Specify a minimum value of the settle time. When a ROA table changes, automatic RPKI reload may be triggered, after a short settle time. Minimum settle time is a delay from the last ROA table change to wait for more updates. Default: 1 s.

`max settle time time`

  Specify a maximum value of the settle time. When a ROA table changes, automatic RPKI reload may be triggered, after a short settle time. Maximum settle time is an upper limit to the settle time from the initial ROA table change even if there are consecutive updates gradually renewing the settle time. Default: 20 s.

`gc threshold number`

  Specify a minimum amount of removed networks that triggers a garbage collection (GC) cycle. Default: 1000.

`gc period time`

  Specify a period of time between consecutive GC cycles. When there is a significant amount of route withdraws, GC cycles are executed repeatedly with given period time (with some random factor). When there is just small amount of changes, GC cycles are not executed. In extensive route server setups, running GC on hundreds of full BGP routing tables can take significant amount of time, therefore they should use higher GC periods. Default: adaptive, based on number of routing tables in the configuration. From 10 s (with <= 25 routing tables) up to 600 s (with >= 1500 routing tables).

## 3.4 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").

`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) 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.

`router id number | IPv4 address`

  This option can be used to override global router id for a given protocol. Default: uses global router id.

`hostname "name"`

  This option can be used to override global hostname for a given protocol. Default: uses global hostname.

`description "text"`

  This is an optional description of the protocol. It is displayed as a part of the output of 'show protocols all' command.

`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 specifying `vrf` 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. In BGP, this can be avoided by using strict bind option.

`channel name [{channel config}]`

  Every channel must be explicitly stated. See the protocol-specific configuration for the list of supported channel names. See the channel configuration section for channel definition.

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, thus `interface "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, 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 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 number`

  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 number`

  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" | bytestring [ { 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.

  A password can be specified as a string or as a sequence of hexadecimal digit pairs ( bytestring).

  This option is allowed in BFD, OSPF, RIP, and Babel 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 number`

  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 `YYYY-MM-DD [hh:mm:ss[.sss]]`.

`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` 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 | blake2s128 | blake2s256 | blake2b256 | blake2b512 )`

  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 and Babel it is HMAC-SHA-256.

## 3.5 Channel options

Every channel belongs to a protocol and is configured inside its block. The minimal channel config is empty, then it uses default values. The name of the channel implies its nettype. Channel definitions can be inherited from protocol templates. Multiple definitions of the same channel are forbidden, but channels inherited from templates can be updated by new definitions.

`debug all|off|{ states|routes|filters [, ...] }`

  Set channel debugging options. Like in protocol debugging, channels are 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 channel state changes (channel going up, down, feeding, reloading etc.), `routes` for routes propagated through the channel, `filters` for details on route filtering, remaining debug flags are not used in channel debug. Default: off.

`table name`

  Specify a table to which the channel is connected. Default: the first table of given nettype.

`preference expr`

  Sets the preference of routes generated by the protocol and imported through this channel. Default: protocol dependent.

`import all | none | filter name | filter { filter commands } | where boolean filter expression`

  Specify a filter to be used for filtering routes coming from the protocol to the routing table. `all` is for keeping all routes, `none` is for dropping all routes. Default: `all` (except for EBGP).

`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` (except for EBGP and L3VPN).

`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.

`rpki reload switch`

  Import or export filters may depend on route RPKI status (using `roa_check()` or `aspa_check()` operators). In contrast to other filter operators, this status for the same route may change as the content of ROA and ASPA tables changes. When this option is active, BIRD activates automatic reload of affected channels whenever ROA and ASPA tables are updated (after a short settle time). When disabled, route reloads have to be requested manually. The option is ignored if neither `roa_check()` nor `aspa_check()` is used in channel filters. Note that for BGP channels, automatic reload requires import table or export table (for respective direction). Default: on.

`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 if `import 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`.

This is a trivial example of RIP configured for IPv6 on all interfaces:

    protocol rip ng {
            ipv6;
            interface "*";
    }

This is a non-trivial example.

    protocol rip ng {
            ipv6 {
                    table mytable6;
                    import filter { ... };
                    export filter { ... };
                    import limit 50;
            };
            interface "*";
    }

And this is even more complicated example using templates.

    template bgp {
            local 198.51.100.14 as 65000;

            ipv4 {
                    table mytable4;
                    import filter { ... };
                    export none;
            };
            ipv6 {
                    table mytable6;
                    import filter { ... };
                    export none;
            };
    }

    protocol bgp from  {
            neighbor 198.51.100.130 as 64496;

            # IPv4 channel is inherited as-is, while IPv6
            # channel is adjusted by export filter option
            ipv6 {
                    export filter { ... };
            };
    }

## 3.6 MPLS options

The MPLS domain definition is mandatory for a MPLS router. All MPLS channels and MPLS-aware protocols are associated with some MPLS domain (although usually implicitly with the sole one). In the MPLS domain definition you can configure details of MPLS label allocation. Currently, there is just one option, `label range`.

Note that the MPLS subsystem is experimental, it is likely that there will be some backward-incompatible changes in the future.

`label range name { start number; length number; [...] }`

  Define a new label range, or redefine implicit label ranges `static` and `dynamic`. MPLS channels use configured label ranges for dynamic label allocation, while `static` label range is used for static label allocation. The label range definition must specify the extent of the range. By default, the range `static` is 16-1000, while the range `dynamic` is 1000-10000.

MPLS channel should be defined in each MPLS-aware protocol in addition to its regular channels. It is responsible for label allocation and for announcing MPLS routes to the MPLS routing table. Besides common channel options, MPLS channels have some specific options:

`domain name`

  Specify a MPLS domain to which this channel and protocol belongs. Default: The first defined MPLS domain.

`label range name`

  Use specific label range for dynamic label allocation. Note that static labels always use the range `static`. Default: the range `dynamic`.

`label policy static|prefix|aggregate|vrf`

  Label policy specifies how routes are grouped to forwarding equivalence classes (FECs) and how labels are assigned to them.

  The policy `static` means no dynamic label allocation is done, and static labels must be set in import filters using the route attribute mpls_label.

  The policy `prefix` means each prefix uses separate label associated with that prefix. When a labeled route is updated, it keeps the label. This policy is appropriate for IGPs.

  The policy `aggregate` means routes are grouped to FECs according to their next hops (including next hop labels), and one label is used for all routes in the same FEC. When a labeled route is updated, it may change next hop, change FEC and therefore change label. This policy is appropriate for BGP.

  The policy `vrf` is only valid in L3VPN protocols. It uses one label for all routes from a VRF, while replacing the original next hop with lookup in the VRF.

  Default: `prefix`.

This is a trivial example of MPLS setup:

    mpls domain mdom {
            label range bgprange { start 2000; length 1000; };
    }

    mpls table mtab;

    protocol static {
            ipv6;
            mpls;

            route 2001:db8:1:1/64 mpls 100 via 2001:db8:1:2::1/64 mpls 200;
    }

    protocol bgp {
            # regular channels
            ipv6 mpls { ... };
            vpn6 mpls { ... };

            # MPLS channel
            mpls {
                    # domain mdom;
                    # table mtab;
                    label range bgprange;
                    label policy aggregate;
            };

            ...
    }

Next Previous Contents