<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9">
<TITLE>BIRD User's Guide: Configuration</TITLE>
<LINK HREF="bird-4.html" REL=next>
<LINK HREF="bird-2.html" REL=previous>
<LINK HREF="bird.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="bird-4.html">Next</A>
<A HREF="bird-2.html">Previous</A>
<A HREF="bird.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3.</A> <A HREF="bird.html#toc3">Configuration</A></H2>
<H2><A NAME="ss3.1">3.1</A> <A HREF="bird.html#toc3.1">Introduction</A>
</H2>
<P>BIRD is configured using a text configuration file. Upon startup, BIRD reads <I>prefix</I>/etc/bird.conf (unless the
<CODE>-c</CODE> command line option is given). Configuration may be changed at user's request: if you modify
the config file and then signal BIRD with <CODE>SIGHUP</CODE>, it will adjust to the new
config. Then there's the client
which allows you to talk with BIRD in an extensive way.
<P>
<P>In the config, everything on a line after <CODE>#</CODE> or inside <CODE>/*
*/</CODE> is a comment, whitespace characters are treated as a single space. If there's a variable number of options, they are grouped using
the <CODE>{ }</CODE> brackets. Each option is terminated by a <CODE>;</CODE>. Configuration
is case sensitive.
<P>
<P>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.
<P>
<P>
<HR>
<PRE>
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 "*";
}
</PRE>
<HR>
<P>
<P>
<H2><A NAME="ss3.2">3.2</A> <A HREF="bird.html#toc3.2">Global options</A>
</H2>
<P>
<DL>
<DT><CODE>include "<I>filename</I>"</CODE><DD><P>This statement causes inclusion of a new file. The maximal depth is set to 5.
<P>
<DT><CODE>log "<I>filename</I>"|syslog [name <I>name</I>]|stderr all|{ <I>list of classes</I> }</CODE><DD><P>Set logging of messages having the given class (either <CODE>all</CODE> or <CODE>{
error, trace }</CODE> etc.) into selected destination (a file specified as a filename string,
syslog with optional name argument, or the stderr output). Classes are:
<CODE>info</CODE>, <CODE>warning</CODE>, <CODE>error</CODE> and <CODE>fatal</CODE> for messages about local problems,
<CODE>debug</CODE> for debugging messages,
<CODE>trace</CODE> when you want to know what happens in the network,
<CODE>remote</CODE> for messages about misbehavior of remote machines,
<CODE>auth</CODE> about authentication failures,
<CODE>bug</CODE> for internal BIRD bugs. You may specify more than one <CODE>log</CODE> line to establish logging to multiple
destinations. Default: log everything to the system log.
<P>
<DT><CODE>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</CODE><DD><P>Set global defaults of protocol debugging options. See <CODE>debug</CODE> in the following section. Default: off.
<P>
<DT><CODE>debug commands <I>number</I></CODE><DD><P>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.
<P>
<DT><CODE>mrtdump "<I>filename</I>"</CODE><DD><P>Set MRTdump file name. This option must be specified to allow MRTdump feature.
Default: no dump file.
<P>
<DT><CODE>mrtdump protocols all|off|{ states, messages }</CODE><DD><P>Set global defaults of MRTdump options. See <CODE>mrtdump</CODE> in the following section.
Default: off.
<P>
<DT><CODE>filter <I>name local variables</I>{ <I>commands</I> }</CODE><DD><P>Define a filter. You can learn more about filters
in the following chapter.
<P>
<DT><CODE>function <I>name</I> (<I>parameters</I>) <I>local variables</I> { <I>commands</I> }</CODE><DD><P>Define a function. You can learn more
about functions in the following chapter.
<P>
<DT><CODE>protocol rip|ospf|bgp|... [<I>name</I> [from <I>name2</I>]] { <I>protocol options</I> }</CODE><DD><P>Define a protocol instance called <CODE><I>name</I></CODE> (or with a name like "rip5" generated
automatically if you don't specify any <CODE><I>name</I></CODE>). You can learn more about
configuring protocols in their own chapters. When <CODE>from <I>name2</I></CODE> expression is
used, initial protocol options are taken from protocol or template <CODE><I>name2</I></CODE>
You can run more than one instance of most protocols (like RIP or BGP). By default, no
instances are configured.
<P>
<DT><CODE>template rip|bgp|... [<I>name</I> [from <I>name2</I>]] { <I>protocol options</I> }</CODE><DD><P>Define a protocol template instance called <CODE><I>name</I></CODE> (or with a name like "bgp1"
generated automatically if you don't specify any <CODE><I>name</I></CODE>). 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 <CODE>from</CODE>
expression and the name of the template. At the moment templates (and <CODE>from</CODE> expression)
are not implemented for OSPF protocol.
<P>
<DT><CODE>define <I>constant</I> = (<I>expression</I>)|<I>number</I>|<I>IP address</I></CODE><DD><P>Define a constant. You can use it later in every place you could use a simple integer or an IP address.
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.
<P>
<DT><CODE>router id <I>IPv4 address</I></CODE><DD><P>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.
<P>
<DT><CODE>listen bgp [address <I>address</I>] [port <I>port</I>] [dual]</CODE><DD><P>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
<CODE>dual</CODE> 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.
<P>
<DT><CODE>timeformat route|protocol|base|log "<I>format1</I>" [<I>limit</I> "<I>format2</I>"]</CODE><DD><P>This option allows to specify a format of date/time used by
BIRD. The first argument specifies for which purpose such
format is used. <CODE>route</CODE> is a format used in 'show route'
command output, <CODE>protocol</CODE> is used in 'show protocols'
command output, <CODE>base</CODE> is used for other commands and
<CODE>log</CODE> is used in a log file.
<P>"<I>format1</I>" is a format string using <I>strftime(3)</I>
notation (see <I>man strftime</I> for details). <I>limit> and
"<I>format2</I>" allow to specify the second format string for
times in past deeper than <I>limit</I> seconds. There are two
shorthands: <CODE>iso long</CODE> is a ISO 8601 date</I>time format
(YYYY-MM-DD hh:mm:ss) that can be also specified using <CODE>"%F
%T"</CODE>. <CODE>iso short</CODE> 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 <CODE>"%T" 72000 "%F"</CODE>.
<P>By default, BIRD uses an short, ad-hoc format for <CODE>route</CODE>
and <CODE>protocol</CODE> times, and a <CODE>iso long</CODE> similar format
(DD-MM-YYYY hh:mm:ss) for <CODE>base</CODE> and <CODE>log</CODE>. These
defaults are here for a compatibility with older versions
and might change in the future.
<P>
<DT><CODE>table <I>name</I></CODE><DD><P>Create a new routing table. The default
routing table is created implicitly, other routing tables have
to be added by this command.
<P>
<DT><CODE>roa table [ { roa table options ... } ] <I>name</I></CODE><DD><P>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 <CODE>roa_check()</CODE> operator in filters.
<P>Currently, there is just one option,
<CODE>roa <I>prefix</I> max <I>num</I> as <I>num</I></CODE>, 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 by <CODE>add roa</CODE> command.
<P>
<DT><CODE>eval <I>expr</I></CODE><DD><P>Evaluates given filter expression. It
is used by us for testing of filters.
</DL>
<P>
<H2><A NAME="ss3.3">3.3</A> <A HREF="bird.html#toc3.3">Protocol options</A>
</H2>
<P>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).
<P>
<P>Several options use a <CODE><I>switch</I></CODE> argument. It can be either
<CODE>on</CODE>, <CODE>yes</CODE> or a numeric expression with a non-zero value for the
option to be enabled or <CODE>off</CODE>, <CODE>no</CODE> or a numeric expression evaluating
to zero to disable it. An empty <CODE><I>switch</I></CODE> is equivalent to <CODE>on</CODE>
("silence means agreement").
<P>
<DL>
<DT><CODE>preference <I>expr</I></CODE><DD><P>Sets the preference of routes generated by this protocol. Default: protocol dependent.
<P>
<DT><CODE>disabled <I>switch</I></CODE><DD><P>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.
<P>
<DT><CODE>debug all|off|{ states, routes, filters, interfaces, events, packets }</CODE><DD><P>Set protocol debugging options. If asked, each protocol is capable of
writing trace messages about its work to the log (with category
<CODE>trace</CODE>). You can either request printing of <CODE>all</CODE> trace messages
or only of the types selected: <CODE>states</CODE> for protocol state changes
(protocol going up, down, starting, stopping etc.),
<CODE>routes</CODE> for routes exchanged with the routing table,
<CODE>filters</CODE> for details on route filtering,
<CODE>interfaces</CODE> for interface change events sent to the protocol,
<CODE>events</CODE> for events internal to the protocol and
<CODE>packets</CODE> for packets sent and received by the protocol. Default: off.
<P>
<DT><CODE>mrtdump all|off|{ states, messages }</CODE><DD><P>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 <CODE>mrtdump</CODE> option, see the previous
section). Although these flags are similar to flags of
<CODE>debug</CODE> option, their meaning is different and
protocol-specific. For BGP protocol, <CODE>states</CODE> logs BGP
state changes and <CODE>messages</CODE> logs received BGP messages.
Other protocols does not support MRTdump yet.
<P>
<DT><CODE>router id <I>IPv4 address</I></CODE><DD><P>This option can be used
to override global router id for a given protocol. Default:
uses global router id.
<P>
<DT><CODE>import all | none | filter <I>name</I> | filter { <I>filter commands</I> } | where <I>filter expression</I></CODE><DD><P>Specify a filter to be used for filtering routes coming from the protocol to the routing table. <CODE>all</CODE> is shorthand for <CODE>where true</CODE> and <CODE>none</CODE> is shorthand for <CODE>where false</CODE>. Default: <CODE>all</CODE>.
<P>
<DT><CODE>export <I>filter</I></CODE><DD><P>This is similar to the <CODE>import</CODE> keyword, except that it
works in the direction from the routing table to the protocol. Default: <CODE>none</CODE>.
<P>
<DT><CODE>description "<I>text</I>"</CODE><DD><P>This is an optional
description of the protocol. It is displayed as a part of the
output of 'show route all' command.
<P>
<DT><CODE>table <I>name</I></CODE><DD><P>Connect this protocol to a non-default routing table.
</DL>
<P>
<P>There are several options that give sense only with certain protocols:
<P>
<DL>
<DT><CODE>
<A NAME="dsc-iface"></A> interface [-] [ "<I>mask</I>" ] [ <I>prefix</I> ] [, ...] [ { <I>option</I> ; [...] } ]</CODE><DD><P>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 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. For IPv6, the prefix part of a clause
is generally ignored and interfaces are matched just by their name.
<P>An interface matches the pattern if it matches any of its
clauses. If the clause begins with <CODE>-</CODE>, matching interfaces are
excluded. Patterns are parsed left-to-right, thus
<CODE>interface "eth0", -"eth*", "*";</CODE> means eth0 and all
non-ethernets.
<P>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.
<P>This option is allowed in Direct, OSPF, RIP and RAdv protocols,
but in OSPF protocol it is used in <CODE>area</CODE> subsection.
<P>Default: none.
<P>Examples:
<P><CODE>interface "*" { type broadcast; };</CODE> - start the protocol on all interfaces with
<CODE>type broadcast</CODE> option.
<P><CODE>interface "eth1", "eth4", "eth5" { type ptp; };</CODE> - start the protocol
on enumerated interfaces with <CODE>type ptp</CODE> option.
<P><CODE>interface -192.168.1.0/24, 192.168.0.0/16;</CODE> - start the protocol on all
interfaces that have address from 192.168.0.0/16, but not
from 192.168.1.0/24.
<P><CODE>interface -192.168.1.0/24, 192.168.0.0/16;</CODE> - start the protocol on all
interfaces that have address from 192.168.0.0/16, but not
from 192.168.1.0/24.
<P><CODE>interface "eth*" 192.168.1.0/24;</CODE> - start the protocol on all
ethernet interfaces that have address from 192.168.1.0/24.
<P>
<DT><CODE>
<A NAME="dsc-pass"></A> password "<I>password</I>" [ { id <I>num</I>; generate from <I>time</I>; generate to <I>time</I>; accept from <I>time</I>; accept to <I>time</I>; } ]</CODE><DD><P>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
<CODE>authentication</CODE> option.
<P>This option is allowed in OSPF and RIP protocols. BGP has also
<CODE>password</CODE> option, but it is slightly different and described
separately.
<P>Default: none.
</DL>
<P>
<P>Password option can contain section with some (not necessary all) password sub-options:
<P>
<DL>
<DT><CODE>id <I>num</I></CODE><DD><P>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.
<P>
<DT><CODE>generate from "<I>time</I>"</CODE><DD><P>The start time of the usage of the password for packet signing.
The format of <CODE><I>time</I></CODE> is <CODE>dd-mm-yyyy HH:MM:SS</CODE>.
<P>
<DT><CODE>generate to "<I>time</I>"</CODE><DD><P>The last time of the usage of the password for packet signing.
<P>
<DT><CODE>accept from "<I>time</I>"</CODE><DD><P>The start time of the usage of the password for packet verification.
<P>
<DT><CODE>accept to "<I>time</I>"</CODE><DD><P>The last time of the usage of the password for packet verification.
</DL>
<P>
<HR>
<A HREF="bird-4.html">Next</A>
<A HREF="bird-2.html">Previous</A>
<A HREF="bird.html#toc3">Contents</A>
</BODY>
</HTML>
