BIRD User's Guide: Configuration

Next Previous Contents

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.

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

log "filename"|syslog|stderr all|{ list of classes }

Set logging of messages having the given class (either all or { error, trace } etc.) into selected destination. 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. You may specify more than one log 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.

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] { 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. You can run more than one instance of most protocols (like RIP or BGP). By default, no instances are configured.

define constant = (expression)|number|IP address

Define a constant. You can use it later in every place you could use a simple integer or an IP address.

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.

listen bgp [address address] [port port] [v6only]

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 v6only can be used to specify that BGP socket should listen to IPv6 connections only. This is needed if you want to run both bird and bird6 on the same port.

table name

Create a new routing table. The default routing table is created implicitly, other routing tables have to be added by this 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 of all 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 and packets for packets sent and received by the protocol. Default: off.

router id IPv4 address

This option can be used to override global router id for a given protocol. This option is not yet implemented for OSPF 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 for where true and none is shorthand for where 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.

table name

Connect this protocol to a non-default routing table.

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 (separted by commas), each clause may contain a mask, a prefix, or both of them. An interface matches the clause if its name matches the mask (if specified) and its address matches the prefix (if specified). Mask is specified as shell-like pattern.

An interface matches the pattern if it matches any of its clauses. If the clause begins with -, matching interfaces are excluded. Patterns are parsed left-to-right, thus interface "eth0", -"eth*", "*"; means eth0 and all non-ethernets.

An interface option can be used more times with different interfaces-specific options, in that case for given interface the first matching interface option is used.

This option is allowed in Direct, OSPF and RIP protocols, but in OSPF protocol it is used in area subsection.

Default: none.

Examples:

interface "*" { type broadcast; }; - start the protocol on all interfaces with type broadcast option.

interface "eth1", "eth4", "eth5" { type pointopoint; }; - start the protocol on enumerated interfaces with type pointopoint 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.

password "password" [ { id num; generate from time; generate to time; accept from time; accept to time; } ]

Specifies a password that can be used by the protocol. 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 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's 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 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.

Next Previous Contents

3. Configuration

3.1 Introduction

3.2 Global options

3.3 Protocol options