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

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

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

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

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

`passwords { password "password" from time to time passive time id num [...] }`

  Specifies passwords to be used with this protocol. `Passive time` is time from which the password is not used for sending, but it is recognized on reception. `id` is password ID as needed by certain protocols. Format of `time` is `dd-mm-yyyy HH:MM:SS`.

`interface "mask"|prefix [ { option ; [...] } ]`

  Specifies which interfaces is this protocol active on and allows you to set options on a per-interface basis. Mask is specified as in shell-like patterns, thus `interface "*" { mode broadcast; };` will start the protocol on all interfaces with `mode broadcast;` option. If the first character of mask is `-`, such interfaces are excluded. Masks are parsed left-to-right, thus `interface "-eth*", "*";` means all but the ethernets. Default: none.

Next Previous Contents