2334 lines
101 KiB
Text
2334 lines
101 KiB
Text
<!doctype birddoc system>
|
|
|
|
<!--
|
|
BIRD documentation
|
|
|
|
This documentation can have 4 forms: sgml (this is master copy), html,
|
|
ASCII text and dvi/postscript (generated from sgml using
|
|
sgmltools). You should always edit master copy.
|
|
|
|
This is a slightly modified linuxdoc dtd. Anything in <descrip> tags is considered definition of
|
|
configuration primitives, <cf> is fragment of configuration within normal text, <m> is
|
|
"meta" information within fragment of configuration - something in config which is not keyword.
|
|
|
|
(set-fill-column 100)
|
|
|
|
Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
|
|
|
|
-->
|
|
|
|
<book>
|
|
|
|
<title>BIRD User's Guide
|
|
<author>
|
|
Ondrej Filip <it/<feela@network.cz>/,
|
|
Pavel Machek <it/<pavel@ucw.cz>/,
|
|
Martin Mares <it/<mj@ucw.cz>/,
|
|
Ondrej Zajicek <it/<santiago@crfreenet.org>/
|
|
</author>
|
|
|
|
<abstract>
|
|
This document contains user documentation for the BIRD Internet Routing Daemon project.
|
|
</abstract>
|
|
|
|
<!-- Table of contents -->
|
|
<toc>
|
|
|
|
<!-- Begin the document -->
|
|
|
|
<chapt>Introduction
|
|
|
|
<sect>What is BIRD
|
|
|
|
<p><label id="intro">
|
|
The name `BIRD' is actually an acronym standing for `BIRD Internet Routing Daemon'.
|
|
Let's take a closer look at the meaning of the name:
|
|
|
|
<p><em/BIRD/: Well, we think we have already explained that. It's an acronym standing
|
|
for `BIRD Internet Routing Daemon', you remember, don't you? :-)
|
|
|
|
<p><em/Internet Routing/: It's a program (well, a daemon, as you are going to discover in a moment)
|
|
which works as a dynamic router in an Internet type network (that is, in a network running either
|
|
the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected
|
|
networks in order to allow hosts not connected directly to the same local area network to
|
|
communicate with each other. They also communicate with the other routers in the Internet to discover
|
|
the topology of the network which allows them to find optimal (in terms of some metric) rules for
|
|
forwarding of packets (which are called routing tables) and to adapt themselves to the
|
|
changing conditions such as outages of network links, building of new connections and so on. Most of
|
|
these routers are costly dedicated devices running obscure firmware which is hard to configure and
|
|
not open to any changes (on the other hand, their special hardware design allows them to keep up with lots of high-speed network interfaces, better than general-purpose computer does). Fortunately, most operating systems of the UNIX family allow an ordinary
|
|
computer to act as a router and forward packets belonging to the other hosts, but only according to
|
|
a statically configured table.
|
|
|
|
<p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program running on
|
|
background which does the dynamic part of Internet routing, that is it communicates
|
|
with the other routers, calculates routing tables and sends them to the OS kernel
|
|
which does the actual packet forwarding. There already exist other such routing
|
|
daemons: routed (RIP only), GateD (non-free), Zebra<HTMLURL URL="http://www.zebra.org">
|
|
and MRTD<HTMLURL URL="http://sourceforge.net/projects/mrt">, but their capabilities are
|
|
limited and they are relatively hard to configure and maintain.
|
|
|
|
<p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
|
|
to support all the routing technology used in the today's Internet or planned to be
|
|
used in near future and to have a clean extensible architecture allowing new routing
|
|
protocols to be incorporated easily. Among other features, BIRD supports:
|
|
|
|
<itemize>
|
|
<item>both IPv4 and IPv6 protocols
|
|
<item>multiple routing tables
|
|
<item>the Border Gateway Protocol (BGPv4)
|
|
<item>the Routing Information Protocol (RIPv2)
|
|
<item>the Open Shortest Path First protocol (OSPFv2, OSPFv3)
|
|
<item>the Router Advertisements for IPv6 hosts
|
|
<item>a virtual protocol for exchange of routes between different routing tables on a single host
|
|
<item>a command-line interface allowing on-line control and inspection
|
|
of status of the daemon
|
|
<item>soft reconfiguration (no need to use complex online commands
|
|
to change the configuration, just edit the configuration file
|
|
and notify BIRD to re-read it and it will smoothly switch itself
|
|
to the new configuration, not disturbing routing protocols
|
|
unless they are affected by the configuration changes)
|
|
<item>a powerful language for route filtering
|
|
</itemize>
|
|
|
|
<p>BIRD has been developed at the Faculty of Math and Physics, Charles University, Prague,
|
|
Czech Republic as a student project. It can be freely distributed under the terms of the GNU General
|
|
Public License.
|
|
|
|
<p>BIRD has been designed to work on all UNIX-like systems. It has
|
|
been developed and tested under Linux 2.0 to 2.6, and then ported to
|
|
FreeBSD, NetBSD and OpenBSD, porting to other systems (even non-UNIX
|
|
ones) should be relatively easy due to its highly modular
|
|
architecture.
|
|
|
|
<p>BIRD supports either IPv4 or IPv6 protocol, but have to be compiled
|
|
separately for each one. Therefore, a dualstack router would run two
|
|
instances of BIRD (one for IPv4 and one for IPv6), with completely
|
|
separate setups (configuration files, tools ...).
|
|
|
|
<sect>Installing BIRD
|
|
|
|
<p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) and Perl, installing BIRD should be as easy as:
|
|
|
|
<code>
|
|
./configure
|
|
make
|
|
make install
|
|
vi /usr/local/etc/bird.conf
|
|
bird
|
|
</code>
|
|
|
|
<p>You can use <tt>./configure --help</tt> to get a list of configure
|
|
options. The most important ones are:
|
|
<tt/--enable-ipv6/ which enables building of an IPv6 version of BIRD,
|
|
<tt/--with-protocols=/ to produce a slightly smaller BIRD executable by configuring out routing protocols you don't use, and
|
|
<tt/--prefix=/ to install BIRD to a place different from.
|
|
<file>/usr/local</file>.
|
|
|
|
<sect>Running BIRD
|
|
|
|
<p>You can pass several command-line options to bird:
|
|
|
|
<descrip>
|
|
<tag>-c <m/config name/</tag>
|
|
use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
|
|
|
|
<tag>-d</tag>
|
|
enable debug messages and run bird in foreground.
|
|
|
|
<tag>-D <m/filename of debug log/</tag>
|
|
log debugging information to given file instead of stderr.
|
|
|
|
<tag>-p</tag>
|
|
just parse the config file and exit. Return value is zero if the config file is valid,
|
|
nonzero if there are some errors.
|
|
|
|
<tag>-s <m/name of communication socket/</tag>
|
|
use given filename for a socket for communications with the client, default is <it/prefix/<file>/var/run/bird.ctl</file>.
|
|
</descrip>
|
|
|
|
<p>BIRD writes messages about its work to log files or syslog (according to config).
|
|
|
|
<chapt>About routing tables
|
|
|
|
<p>BIRD has one or more routing tables which may or may not be
|
|
synchronized with OS kernel and which may or may not be synchronized with
|
|
each other (see the Pipe protocol). Each routing table contains a list of
|
|
known routes. Each route consists of:
|
|
|
|
<itemize>
|
|
<item>network prefix this route is for (network address and prefix length -- the number of bits forming the network part of the address; also known as a netmask)
|
|
<item>preference of this route
|
|
<item>IP address of router which told us about this route
|
|
<item>IP address of router we should forward the packets to
|
|
using this route
|
|
<item>other attributes common to all routes
|
|
<item>dynamic attributes defined by protocols which may or
|
|
may not be present (typically protocol metrics)
|
|
</itemize>
|
|
|
|
Routing table maintains multiple entries
|
|
for a network, but at most one entry for one network and one
|
|
protocol. The entry with the highest preference is used for routing (we
|
|
will call such an entry the <it/selected route/). If
|
|
there are more entries with the same preference and they are from the same
|
|
protocol, the protocol decides (typically according to metrics). If they aren't,
|
|
an internal ordering is used to break the tie. You can
|
|
get the list of route attributes in the Route attributes section.
|
|
|
|
<p>Each protocol is connected to a routing table through two filters
|
|
which can accept, reject and modify the routes. An <it/export/
|
|
filter checks routes passed from the routing table to the protocol,
|
|
an <it/import/ filter checks routes in the opposite direction.
|
|
When the routing table gets a route from a protocol, it recalculates
|
|
the selected route and broadcasts it to all protocols connected to
|
|
the table. The protocols typically send the update to other routers
|
|
in the network.
|
|
|
|
<chapt>Configuration
|
|
|
|
<sect>Introduction
|
|
|
|
<p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <it/prefix/<file>/etc/bird.conf</file> (unless the
|
|
<tt/-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 <tt/SIGHUP/, it will adjust to the new
|
|
config. Then there's the client
|
|
which allows you to talk with BIRD in an extensive way.
|
|
|
|
<p>In the config, everything on a line after <cf/#/ or inside <cf>/*
|
|
*/</cf> is a comment, whitespace characters are treated as a single space. If there's a variable number of options, they are grouped using
|
|
the <cf/{ }/ brackets. Each option is terminated by a <cf/;/. Configuration
|
|
is case sensitive.
|
|
|
|
<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.
|
|
|
|
|
|
<code>
|
|
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 "*";
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>Global options
|
|
|
|
<p><descrip>
|
|
<tag>log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag>
|
|
Set logging of messages having the given class (either <cf/all/ or <cf/{
|
|
error, trace }/ etc.) into selected destination (a file specified as a filename string,
|
|
syslog with optional name argument, or the stderr output). Classes are:
|
|
<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
|
|
<cf/debug/ for debugging messages,
|
|
<cf/trace/ when you want to know what happens in the network,
|
|
<cf/remote/ for messages about misbehavior of remote machines,
|
|
<cf/auth/ about authentication failures,
|
|
<cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple
|
|
destinations. Default: log everything to the system log.
|
|
|
|
<tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
|
|
Set global defaults of protocol debugging options. See <cf/debug/ in the following section. Default: off.
|
|
|
|
<tag>debug commands <m/number/</tag>
|
|
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.
|
|
|
|
<tag>mrtdump "<m/filename/"</tag>
|
|
Set MRTdump file name. This option must be specified to allow MRTdump feature.
|
|
Default: no dump file.
|
|
|
|
<tag>mrtdump protocols all|off|{ states, messages }</tag>
|
|
Set global defaults of MRTdump options. See <cf/mrtdump/ in the following section.
|
|
Default: off.
|
|
|
|
<tag>filter <m/name local variables/{ <m/commands/ }</tag> Define a filter. You can learn more about filters
|
|
in the following chapter.
|
|
|
|
<tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more
|
|
about functions in the following chapter.
|
|
|
|
<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
|
|
instance called <cf><m/name/</cf> (or with a name like "rip5" generated automatically if you don't specify any <cf><m/name/</cf>). 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.
|
|
|
|
<tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/IP address/</tag> Define a constant. You can use it later in every place
|
|
you could use a simple integer or an IP address.
|
|
|
|
<tag>router id <m/IPv4 address/</tag> 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.
|
|
|
|
<tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
|
|
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
|
|
<cf/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.
|
|
|
|
<tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
|
|
This option allows to specify a format of date/time used by
|
|
BIRD. The first argument specifies for which purpose such
|
|
format is used. <cf/route/ is a format used in 'show route'
|
|
command output, <cf/protocol/ is used in 'show protocols'
|
|
command output, <cf/base/ is used for other commands and
|
|
<cf/log/ is used in a log file.
|
|
|
|
"<m/format1/" is a format string using <it/strftime(3)/
|
|
notation (see <it/man strftime/ for details). <m/limit> and
|
|
"<m/format2/" allow to specify the second format string for
|
|
times in past deeper than <m/limit/ seconds. There are two
|
|
shorthands: <cf/iso long/ is a ISO 8601 date/time format
|
|
(YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F
|
|
%T"/. <cf/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 <cf/"%T" 72000 "%F"/.
|
|
|
|
By default, BIRD uses an short, ad-hoc format for <cf/route/
|
|
and <cf/protocol/ times, and a <cf/iso long/ similar format
|
|
(DD-MM-YYYY hh:mm:ss) for <cf/base/ and <cf/log/. These
|
|
defaults are here for a compatibility with older versions
|
|
and might change in the future.
|
|
|
|
<tag>table <m/name/</tag> Create a new routing table. The default
|
|
routing table is created implicitly, other routing tables have
|
|
to be added by this command.
|
|
|
|
<tag>eval <m/expr/</tag> Evaluates given filter expression. It
|
|
is used by us for testing of filters.
|
|
</descrip>
|
|
|
|
<sect>Protocol options
|
|
|
|
<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>Several options use a <cf><m/switch/</cf> argument. It can be either
|
|
<cf/on/, <cf/yes/ or a numeric expression with a non-zero value for the
|
|
option to be enabled or <cf/off/, <cf/no/ or a numeric expression evaluating
|
|
to zero to disable it. An empty <cf><m/switch/</cf> is equivalent to <cf/on/
|
|
("silence means agreement").
|
|
|
|
<descrip>
|
|
<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
|
|
|
|
<tag>disabled <m/switch/</tag> 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.
|
|
|
|
<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
|
|
Set protocol debugging options. If asked, each protocol is capable of
|
|
writing trace messages about its work to the log (with category
|
|
<cf/trace/). You can either request printing of <cf/all/ trace messages
|
|
or only of the types selected: <cf/states/ for protocol state changes
|
|
(protocol going up, down, starting, stopping etc.),
|
|
<cf/routes/ for routes exchanged with the routing table,
|
|
<cf/filters/ for details on route filtering,
|
|
<cf/interfaces/ for interface change events sent to the protocol,
|
|
<cf/events/ for events internal to the protocol and
|
|
<cf/packets/ for packets sent and received by the protocol. Default: off.
|
|
|
|
<tag>mrtdump all|off|{ states, messages }</tag>
|
|
|
|
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 <cf/mrtdump/ option, see the previous
|
|
section). Although these flags are similar to flags of
|
|
<cf/debug/ option, their meaning is different and
|
|
protocol-specific. For BGP protocol, <cf/states/ logs BGP
|
|
state changes and <cf/messages/ logs received BGP messages.
|
|
Other protocols does not support MRTdump yet.
|
|
|
|
<tag>router id <m/IPv4 address/</tag> This option can be used
|
|
to override global router id for a given protocol. Default:
|
|
uses global router id.
|
|
|
|
<tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag>
|
|
Specify a filter to be used for filtering routes coming from the protocol to the routing table. <cf/all/ is shorthand for <cf/where true/ and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/.
|
|
|
|
<tag>export <m/filter/</tag> This is similar to the <cf>import</cf> keyword, except that it
|
|
works in the direction from the routing table to the protocol. Default: <cf/none/.
|
|
|
|
<tag>description "<m/text/"</tag> This is an optional
|
|
description of the protocol. It is displayed as a part of the
|
|
output of 'show route all' command.
|
|
|
|
<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
|
|
</descrip>
|
|
|
|
<p>There are several options that give sense only with certain protocols:
|
|
|
|
<descrip>
|
|
<tag><label id="dsc-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...] [ { <m/option/ ; [...] } ]</tag>
|
|
|
|
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.
|
|
|
|
An interface matches the pattern if it matches any of its
|
|
clauses. If the clause begins with <cf/-/, matching interfaces are
|
|
excluded. Patterns are parsed left-to-right, thus
|
|
<cf/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, RIP and RAdv protocols,
|
|
but in OSPF protocol it is used in <cf/area/ subsection.
|
|
|
|
Default: none.
|
|
|
|
Examples:
|
|
|
|
<cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with
|
|
<cf>type broadcast</cf> option.
|
|
|
|
<cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the protocol
|
|
on enumerated interfaces with <cf>type ptp</cf> option.
|
|
|
|
<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
|
|
interfaces that have address from 192.168.0.0/16, but not
|
|
from 192.168.1.0/24.
|
|
|
|
<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
|
|
interfaces that have address from 192.168.0.0/16, but not
|
|
from 192.168.1.0/24.
|
|
|
|
<cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all
|
|
ethernet interfaces that have address from 192.168.1.0/24.
|
|
|
|
<tag><label id="dsc-pass">password "<m/password/" [ { id <m/num/; generate from <m/time/; generate to <m/time/; accept from <m/time/; accept to <m/time/; } ]</tag>
|
|
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
|
|
<cf/authentication/ option.
|
|
|
|
This option is allowed in OSPF and RIP protocols. BGP has also
|
|
<cf/password/ option, but it is slightly different and described
|
|
separately.
|
|
|
|
Default: none.
|
|
</descrip>
|
|
|
|
<p>Password option can contain section with some (not necessary all) password sub-options:
|
|
|
|
<descrip>
|
|
<tag>id <M>num</M></tag>
|
|
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.
|
|
|
|
<tag>generate from "<m/time/"</tag>
|
|
The start time of the usage of the password for packet signing.
|
|
The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
|
|
|
|
<tag>generate to "<m/time/"</tag>
|
|
The last time of the usage of the password for packet signing.
|
|
|
|
<tag>accept from "<m/time/"</tag>
|
|
The start time of the usage of the password for packet verification.
|
|
|
|
<tag>accept to "<m/time/"</tag>
|
|
The last time of the usage of the password for packet verification.
|
|
</descrip>
|
|
|
|
<chapt>Remote control
|
|
|
|
<p>You can use the command-line client <file>birdc</file> to talk with
|
|
a running BIRD. Communication is done using a <file/bird.ctl/ UNIX
|
|
domain socket (unless changed with the <tt/-s/ option given to both
|
|
the server and the client). The commands can perform simple actions
|
|
such as enabling/disabling of protocols, telling BIRD to show various
|
|
information, telling it to show routing table filtered by filter, or
|
|
asking BIRD to reconfigure. Press <tt/?/ at any time to get online
|
|
help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
|
|
client, which allows just read-only commands (<cf/show .../). Option
|
|
<tt/-v/ can be passed to the client, to make it dump numeric return
|
|
codes along with the messages. You do not necessarily need to use
|
|
<file/birdc/ to talk to BIRD, your own applications could do that, too
|
|
-- the format of communication between BIRD and <file/birdc/ is stable
|
|
(see the programmer's documentation).
|
|
|
|
Many commands have the <m/name/ of the protocol instance as an argument.
|
|
This argument can be omitted if there exists only a single instance.
|
|
|
|
<p>Here is a brief list of supported functions:
|
|
|
|
<descrip>
|
|
<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
|
|
Dump contents of internal data structures to the debugging output.
|
|
|
|
<tag>show status</tag>
|
|
Show router status, that is BIRD version, uptime and time from last reconfiguration.
|
|
|
|
<tag>show protocols [all]</tag>
|
|
Show list of protocol instances along with tables they are connected to and protocol status, possibly giving verbose information, if <cf/all/ is specified.
|
|
|
|
<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
|
|
Show detailed information about OSPF interfaces.
|
|
|
|
<tag>show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
|
|
Show a list of OSPF neighbors and a state of adjacency to them.
|
|
|
|
<tag>show ospf state [all] [<m/name/]</tag>
|
|
Show detailed information about OSPF areas based on a content
|
|
of the link-state database. It shows network topology, stub
|
|
networks, aggregated networks and routers from other areas and
|
|
external routes. The command shows information about reachable
|
|
network nodes, use option <cf/all/ to show information about
|
|
all network nodes in the link-state database.
|
|
|
|
<tag>show ospf topology [all] [<m/name/]</tag>
|
|
Show a topology of OSPF areas based on a content of the
|
|
link-state database. It is just a stripped-down version of
|
|
'show ospf state'.
|
|
|
|
<tag>show static [<m/name/]</tag>
|
|
Show detailed information about static routes.
|
|
|
|
<tag>show interfaces [summary]</tag>
|
|
Show the list of interfaces. For each interface, print its type, state, MTU and addresses assigned.
|
|
|
|
<tag>show symbols</tag>
|
|
Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
|
|
|
|
<tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(export|preexport) <m/p/] [protocol <m/p/] [<m/options/]</tag>
|
|
Show contents of a routing table (by default of the main one),
|
|
that is routes, their metrics and (in case the <cf/all/ switch is given)
|
|
all their attributes.
|
|
|
|
<p>You can specify a <m/prefix/ if you want to print routes for a
|
|
specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get
|
|
the entry which will be used for forwarding of packets to the given
|
|
destination. By default, all routes for each network are printed with
|
|
the selected one at the top, unless <cf/primary/ is given in which case
|
|
only the selected route is shown.
|
|
|
|
<p>You can also ask for printing only routes processed and accepted by
|
|
a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
|
|
</cf> or matching a given condition (<cf>where <m/condition/</cf>).
|
|
The <cf/export/ and <cf/preexport/ switches ask for printing of entries
|
|
that are exported to the specified protocol. With <cf/preexport/, the
|
|
export filter of the protocol is skipped.
|
|
|
|
<p>You can also select just routes added by a specific protocol.
|
|
<cf>protocol <m/p/</cf>.
|
|
|
|
<p>The <cf/stats/ switch requests showing of route statistics (the
|
|
number of networks, number of routes before and after filtering). If
|
|
you use <cf/count/ instead, only the statistics will be printed.
|
|
|
|
<tag>configure [soft] ["<m/config file/"]</tag>
|
|
Reload configuration from a given file. BIRD will smoothly
|
|
switch itself to the new configuration, protocols are
|
|
reconfigured if possible, restarted otherwise. Changes in
|
|
filters usually lead to restart of affected protocols. If
|
|
<cf/soft/ option is used, changes in filters does not cause
|
|
BIRD to restart affected protocols, therefore already accepted
|
|
routes (according to old filters) would be still propagated,
|
|
but new routes would be processed according to the new
|
|
filters.
|
|
|
|
<tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
|
|
Enable, disable or restart a given protocol instance, instances matching the <cf><m/pattern/</cf> or <cf/all/ instances.
|
|
|
|
<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
|
|
|
|
Reload a given protocol instance, that means re-import routes
|
|
from the protocol instance and re-export preferred routes to
|
|
the instance. If <cf/in/ or <cf/out/ options are used, the
|
|
command is restricted to one direction (re-import or
|
|
re-export).
|
|
|
|
This command is useful if appropriate filters have changed but
|
|
the protocol instance was not restarted (or reloaded),
|
|
therefore it still propagates the old set of routes. For example
|
|
when <cf/configure soft/ command was used to change filters.
|
|
|
|
Re-export always succeeds, but re-import is protocol-dependent
|
|
and might fail (for example, if BGP neighbor does not support
|
|
route-refresh extension). In that case, re-export is also
|
|
skipped. Note that for the pipe protocol, both directions are
|
|
always reloaded together (<cf/in/ or <cf/out/ options are
|
|
ignored in that case).
|
|
|
|
<tag/down/
|
|
Shut BIRD down.
|
|
|
|
<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
|
|
Control protocol debugging.
|
|
</descrip>
|
|
|
|
<chapt>Filters
|
|
|
|
<sect>Introduction
|
|
|
|
<p>BIRD contains a simple programming language. (No, it can't yet read mail :-). There are
|
|
two objects in this language: filters and functions. Filters are interpreted by BIRD core when a route is
|
|
being passed between protocols and routing tables. The filter language contains control structures such
|
|
as if's and switches, but it allows no loops. An example of a filter using many features can be found in <file>filter/test.conf</file>.
|
|
|
|
<p>Filter gets the route, looks at its attributes and
|
|
modifies some of them if it wishes. At the end, it decides whether to
|
|
pass the changed route through (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks
|
|
like this:
|
|
|
|
<code>
|
|
filter not_too_far
|
|
int var;
|
|
{
|
|
if defined( rip_metric ) then
|
|
var = rip_metric;
|
|
else {
|
|
var = 1;
|
|
rip_metric = 1;
|
|
}
|
|
if rip_metric > 10 then
|
|
reject "RIP metric is too big";
|
|
else
|
|
accept "ok";
|
|
}
|
|
</code>
|
|
|
|
<p>As you can see, a filter has a header, a list of local variables, and a body. The header consists of
|
|
the <cf/filter/ keyword followed by a (unique) name of filter. The list of local variables consists of
|
|
<cf><M>type name</M>;</cf> pairs where each pair defines one local variable. The body consists of
|
|
<cf> { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You can group
|
|
several statements to a single compound statement by using braces (<cf>{ <M>statements</M> }</cf>) which is useful if
|
|
you want to make a bigger block of code conditional.
|
|
|
|
<p>BIRD supports functions, so that you don't have to repeat the same blocks of code over and
|
|
over. Functions can have zero or more parameters and they can have local variables. Recursion is not allowed. Function definitions
|
|
look like this:
|
|
|
|
<code>
|
|
function name ()
|
|
int local_variable;
|
|
{
|
|
local_variable = 5;
|
|
}
|
|
|
|
function with_parameters (int parameter)
|
|
{
|
|
print parameter;
|
|
}
|
|
</code>
|
|
|
|
<p>Unlike in C, variables are declared after the <cf/function/ line, but before the first <cf/{/. You can't declare
|
|
variables in nested blocks. Functions are called like in C: <cf>name();
|
|
with_parameters(5);</cf>. Function may return values using the <cf>return <m/[expr]/</cf>
|
|
command. Returning a value exits from current function (this is similar to C).
|
|
|
|
<p>Filters are declared in a way similar to functions except they can't have explicit
|
|
parameters. They get a route table entry as an implicit parameter, it is also passed automatically
|
|
to any functions called. The filter must terminate with either
|
|
<cf/accept/ or <cf/reject/ statement. If there's a runtime error in filter, the route
|
|
is rejected.
|
|
|
|
<p>A nice trick to debug filters is to use <cf>show route filter
|
|
<m/name/</cf> from the command line client. An example session might look
|
|
like:
|
|
|
|
<code>
|
|
pavel@bug:~/bird$ ./birdc -s bird.ctl
|
|
BIRD 0.0.0 ready.
|
|
bird> show route
|
|
10.0.0.0/8 dev eth0 [direct1 23:21] (240)
|
|
195.113.30.2/32 dev tunl1 [direct1 23:21] (240)
|
|
127.0.0.0/8 dev lo [direct1 23:21] (240)
|
|
bird> show route ?
|
|
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
|
|
bird> show route filter { if 127.0.0.5 ˜ net then accept; }
|
|
127.0.0.0/8 dev lo [direct1 23:21] (240)
|
|
bird>
|
|
</code>
|
|
|
|
<sect>Data types
|
|
|
|
<p>Each variable and each value has certain type. Booleans, integers and enums are
|
|
incompatible with each other (that is to prevent you from shooting in the foot).
|
|
|
|
<descrip>
|
|
<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
|
|
<cf/false/. Boolean is the only type you can use in <cf/if/
|
|
statements.
|
|
|
|
<tag/int/ This is a general integer type, you can expect it to store signed values from -2000000000
|
|
to +2000000000. Overflows are not checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
|
|
|
|
<tag/pair/ This is a pair of two short integers. Each component can have values from 0 to
|
|
65535. Literals of this type are written as <cf/(1234,5678)/. The same syntax can also be
|
|
used to construct a pair from two arbitrary integer expressions (for example <cf/(1+2,a)/).
|
|
|
|
<tag/quad/ This is a dotted quad of numbers used to represent
|
|
router IDs (and others). Each component can have a value
|
|
from 0 to 255. Literals of this type are written like IPv4
|
|
addresses.
|
|
|
|
<tag/string/ This is a string of characters. There are no ways to modify strings in
|
|
filters. You can pass them between functions, assign them to variables of type <cf/string/, print
|
|
such variables, but you can't concatenate two strings. String literals
|
|
are written as <cf/"This is a string constant"/.
|
|
|
|
<tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it
|
|
is either an IPv4 or IPv6 address. IP addresses are written in the standard notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator <cf>.mask(<M>num</M>)</cf>
|
|
on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP
|
|
address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
|
|
|
|
<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
|
|
<cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
|
|
<cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
|
|
operators on prefixes:
|
|
<cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
|
|
length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
|
|
|
|
<tag/int|pair|quad|ip|prefix|enum set/
|
|
Filters recognize four types of sets. Sets are similar to strings: you can pass them around
|
|
but you can't modify them. Literals of type <cf>int set</cf> look like <cf>
|
|
[ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
|
|
sets.
|
|
For pair sets, expressions like <cf/(123,*)/ can be used to denote ranges (in
|
|
that case <cf/(123,0)..(123,65535)/). You can also use <cf/(123,5..100)/ for range
|
|
<cf/(123,5)..(123,100)/. You can also use <cf/(*,123)/ which is translated as
|
|
<cf/(0,123) , (1,123) , (2,123) , ... , (65535, 123)/
|
|
You can also use expressions for both, pair sets and int sets. However it must
|
|
be possible to evaluate these expressions before daemon boots. So you can use
|
|
only constants inside them. E.g.
|
|
<code>
|
|
define one=1;
|
|
int set odds;
|
|
pair set ps;
|
|
|
|
odds = [ one, (2+1), (6-one), (2*2*2-1), 9, 11 ];
|
|
ps = [ (1,(one+one)), (3,4)..(4,8), (5,*), (6,3..6) ];
|
|
</code>
|
|
|
|
Sets of prefixes are special: their literals does not allow ranges, but allows
|
|
prefix patterns that are written as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
|
|
Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if
|
|
the first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are identical and <cf>len1 <= ip1 <= len2</cf>.
|
|
A valid prefix pattern has to satisfy <cf>low <= high</cf>, but <cf/pxlen/ is not constrained by <cf/low/
|
|
or <cf/high/. Obviously, a prefix matches a prefix set literal if it matches any prefix pattern in the
|
|
prefix set literal.
|
|
|
|
There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
|
|
<cf><m>address</m>/<m/len/{<m/len/,<m/maxlen/}</cf> (where <cf><m>maxlen</m></cf> is 32 for IPv4 and 128 for IPv6),
|
|
that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
|
|
is a shorthand for <cf><m>address</m>/<m/len/{0,<m/len/}</cf>, that means network prefix <cf><m>address</m>/<m/len/</cf>
|
|
and all its supernets (network prefixes that contain it).
|
|
|
|
For example, <cf>[ 1.0.0.0/8, 2.0.0.0/8+, 3.0.0.0/8-, 4.0.0.0/8{16,24} ]</cf> matches
|
|
prefix <cf>1.0.0.0/8</cf>, all subprefixes of <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes
|
|
<cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf> matches all prefixes (regardless of
|
|
IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
|
|
<cf>1.2.3.4</cf>. <cf>1.2.0.0/16 ˜ [ 1.0.0.0/8{15,17} ]</cf> is true,
|
|
but <cf>1.0.0.0/16 ˜ [ 1.0.0.0/8- ]</cf> is false.
|
|
|
|
Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
|
|
in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as
|
|
<cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
|
|
<cf>192.168.0.0/16{24,32}</cf>.
|
|
|
|
<tag/enum/
|
|
Enumeration types are fixed sets of possibilities. You can't define your own
|
|
variables of such type, but some route attributes are of enumeration
|
|
type. Enumeration types are incompatible with each other.
|
|
|
|
<tag/bgppath/
|
|
BGP path is a list of autonomous system numbers. You can't write literals of this type.
|
|
There are several special operators on bgppaths:
|
|
|
|
<cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/.
|
|
|
|
<cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/.
|
|
|
|
Both <cf/first/ and <cf/last/ return zero if there is no appropriate ASN,
|
|
for example if the path contains an AS set element as the first (or the last) part.
|
|
|
|
<cf><m/P/.len</cf> returns the length of path <m/P/.
|
|
|
|
<cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result.
|
|
Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
|
|
<cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
|
|
(for example <cf/bgp_path/).
|
|
|
|
<tag/bgpmask/
|
|
BGP masks are patterns used for BGP path matching
|
|
(using <cf>path ˜ [= 2 3 5 * =]</cf> syntax). The masks
|
|
resemble wildcard patterns as used by UNIX shells. Autonomous
|
|
system numbers match themselves, <cf/*/ matches any (even empty)
|
|
sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
|
|
For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
|
|
<tt>bgp_path ˜ [= * 4 3 * =]</tt> is true, but
|
|
<tt>bgp_path ˜ [= * 4 5 * =]</tt> is false.
|
|
BGP mask expressions can also contain integer expressions enclosed in parenthesis
|
|
and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
|
|
There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
|
|
|
|
<tag/clist/
|
|
Clist is similar to a set, except that unlike other sets, it
|
|
can be modified. The type is used for community list (a set
|
|
of pairs) and for cluster list (a set of quads). There exist
|
|
no literals of this type. There are two special operators on
|
|
clists:
|
|
|
|
<cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist
|
|
<m/C/ and returns the result. If item <m/P/ is already in
|
|
clist <m/C/, it does nothing.
|
|
|
|
<cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad)
|
|
<m/P/ from clist <m/C/ and returns the result. If clist
|
|
<m/C/ does not contain item <m/P/, it does nothing.
|
|
<m/P/ may also be a pair (or quad) set, in that case the
|
|
operator deletes all items from clist <m/C/ that are also
|
|
members of set <m/P/.
|
|
|
|
Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
|
|
<cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute
|
|
(for example <cf/bgp_community/). Similarly for <cf/delete/.
|
|
|
|
</descrip>
|
|
|
|
<sect>Operators
|
|
|
|
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
|
|
<cf/(a=b, a!=b, a<b, a>=b)/. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/).
|
|
Special operators include <cf/˜/ for "is element of a set" operation - it can be
|
|
used on element and set of elements of the same type (returning true if element is contained in the given set), or
|
|
on two strings (returning true if first string matches a shell-like pattern stored in second string) or on IP and prefix (returning true if IP is within the range defined by that prefix), or on
|
|
prefix and prefix (returning true if first prefix is more specific than second one) or on bgppath and bgpmask (returning true if the path matches the mask) or on pair/quad and clist (returning true if the pair/quad is element of the clist) or on clist and pair/quad set (returning true if there is an element of the clist that is also a member of the pair/quad set).
|
|
|
|
|
|
<sect>Control structures
|
|
|
|
<p>Filters support two control structures: conditions and case switches.
|
|
|
|
<p>Syntax of a condition is: <cf>if
|
|
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
|
|
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
|
|
clause may be omitted. If the <cf><m>boolean expression</m></cf> is true, <cf><m>command1</m></cf> is executed, otherwise <cf><m>command2</m></cf> is executed.
|
|
|
|
<p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else: |
|
|
<m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ ... ] }</cf>. The expression after
|
|
<cf>case</cf> can be of any type which can be on the left side of the ˜ operator and anything that could
|
|
be a member of a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ grouping.
|
|
If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed.
|
|
|
|
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
|
|
|
|
<code>
|
|
case arg1 {
|
|
2: print "two"; print "I can do more commands without {}";
|
|
3 .. 5: print "three to five";
|
|
else: print "something else";
|
|
}
|
|
|
|
if 1234 = i then printn "."; else {
|
|
print "not 1234";
|
|
print "You need {} around multiple commands";
|
|
}
|
|
</code>
|
|
|
|
<sect>Route attributes
|
|
|
|
<p>A filter is implicitly passed a route, and it can access its
|
|
attributes just like it accesses variables. Attempts to access undefined
|
|
attribute result in a runtime error; you can check if an attribute is
|
|
defined by using the <cf>defined( <m>attribute</m> )</cf> operator.
|
|
One notable exception to this rule are attributes of clist type, where
|
|
undefined value is regarded as empty clist for most purposes.
|
|
|
|
<descrip>
|
|
<tag><m/prefix/ net</tag>
|
|
Network the route is talking about. Read-only. (See the chapter about routing tables.)
|
|
|
|
<tag><m/enum/ scope</tag>
|
|
The scope of the route. Possible values: <cf/SCOPE_HOST/ for
|
|
routes local to this host, <cf/SCOPE_LINK/ for those specific
|
|
for a physical link, <cf/SCOPE_SITE/ and
|
|
<cf/SCOPE_ORGANIZATION/ for private routes and
|
|
<cf/SCOPE_UNIVERSE/ for globally visible routes. This
|
|
attribute is not interpreted by BIRD and can be used to mark
|
|
routes in filters. The default value for new routes is
|
|
<cf/SCOPE_UNIVERSE/.
|
|
|
|
<tag><m/int/ preference</tag>
|
|
Preference of the route. Valid values are 0-65535. (See the chapter about routing tables.)
|
|
|
|
<tag><m/ip/ from</tag>
|
|
The router which the route has originated from. Read-only.
|
|
|
|
<tag><m/ip/ gw</tag>
|
|
Next hop packets routed using this route should be forwarded to.
|
|
|
|
<tag><m/string/ proto</tag>
|
|
The name of the protocol which the route has been imported from. Read-only.
|
|
|
|
<tag><m/enum/ source</tag>
|
|
what protocol has told me about this route. Possible values: <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/, <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/, <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/, <cf/RTS_PIPE/.
|
|
|
|
<tag><m/enum/ cast</tag>
|
|
|
|
Route type (Currently <cf/RTC_UNICAST/ for normal routes,
|
|
<cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will
|
|
be used in the future for broadcast, multicast and anycast
|
|
routes). Read-only.
|
|
|
|
<tag><m/enum/ dest</tag>
|
|
Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_DEVICE/ for routing to a directly-connected network, <cf/RTD_BLACKHOLE/ for packets to be silently discarded, <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be returned with ICMP host unreachable / ICMP administratively prohibited messages). Read-only.
|
|
|
|
<tag><m/int/ igp_metric</tag>
|
|
The optional attribute that can be used to specify a distance
|
|
to the network for routes that do not have a native protocol
|
|
metric attribute (like <cf/ospf_metric1/ for OSPF routes). It
|
|
is used mainly by BGP to compare internal distances to boundary
|
|
routers (see below). It is also used when the route is exported
|
|
to OSPF as a default value for OSPF type 1 metric.
|
|
</descrip>
|
|
|
|
<p>There also exist some protocol-specific attributes which are described in the corresponding protocol sections.
|
|
|
|
<sect>Other statements
|
|
|
|
<p>The following statements are available:
|
|
|
|
<descrip>
|
|
<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
|
|
|
|
<tag>accept|reject [ <m/expr/ ]</tag> Accept or reject the route, possibly printing <cf><m>expr</m></cf>.
|
|
|
|
<tag>return <m/expr/</tag> Return <cf><m>expr</m></cf> from the current function, the function ends at this point.
|
|
|
|
<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
|
|
Prints given expressions; useful mainly while debugging
|
|
filters. The <cf/printn/ variant does not terminate the line.
|
|
|
|
<tag>quitbird</tag>
|
|
Terminates BIRD. Useful when debugging the filter interpreter.
|
|
</descrip>
|
|
|
|
<chapt>Protocols
|
|
|
|
<sect>BGP
|
|
|
|
<p>The Border Gateway Protocol is the routing protocol used for backbone
|
|
level routing in the today's Internet. Contrary to the other protocols, its convergence
|
|
doesn't rely on all routers following the same rules for route selection,
|
|
making it possible to implement any routing policy at any router in the
|
|
network, the only restriction being that if a router advertises a route,
|
|
it must accept and forward packets according to it.
|
|
|
|
<p>BGP works in terms of autonomous systems (often abbreviated as
|
|
AS). Each AS is a part of the network with common management and
|
|
common routing policy. It is identified by a unique 16-bit number
|
|
(ASN). Routers within each AS usually exchange AS-internal routing
|
|
information with each other using an interior gateway protocol (IGP,
|
|
such as OSPF or RIP). Boundary routers at the border of
|
|
the AS communicate global (inter-AS) network reachability information with
|
|
their neighbors in the neighboring AS'es via exterior BGP (eBGP) and
|
|
redistribute received information to other routers in the AS via
|
|
interior BGP (iBGP).
|
|
|
|
<p>Each BGP router sends to its neighbors updates of the parts of its
|
|
routing table it wishes to export along with complete path information
|
|
(a list of AS'es the packet will travel through if it uses the particular
|
|
route) in order to avoid routing loops.
|
|
|
|
<p>BIRD supports all requirements of the BGP4 standard as defined in
|
|
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
|
|
It also supports the community attributes
|
|
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
|
|
capability negotiation
|
|
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
|
|
MD5 password authentication
|
|
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
|
|
route reflectors
|
|
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
|
|
multiprotocol extensions
|
|
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
|
|
and 4B AS numbers
|
|
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">).
|
|
|
|
|
|
For IPv6, it uses the standard multiprotocol extensions defined in
|
|
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
|
|
including changes described in the
|
|
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
|
|
and applied to IPv6 according to
|
|
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
|
|
|
|
<sect1>Route selection rules
|
|
|
|
<p>BGP doesn't have any simple metric, so the rules for selection of an optimal
|
|
route among multiple BGP routes with the same preference are a bit more complex
|
|
and they are implemented according to the following algorithm. It starts the first
|
|
rule, if there are more "best" routes, then it uses the second rule to choose
|
|
among them and so on.
|
|
|
|
<itemize>
|
|
<item>Prefer route with the highest Local Preference attribute.
|
|
<item>Prefer route with the shortest AS path.
|
|
<item>Prefer IGP origin over EGP and EGP origin over incomplete.
|
|
<item>Prefer the lowest value of the Multiple Exit Discriminator.
|
|
<item>Prefer routes received via eBGP over ones received via iBGP.
|
|
<item>Prefer routes with lower internal distance to a boundary router.
|
|
<item>Prefer the route with the lowest value of router ID of the
|
|
advertising router.
|
|
</itemize>
|
|
|
|
<sect1>IGP routing table
|
|
|
|
<p>BGP is mainly concerned with global network reachability and with
|
|
routes to other autonomous systems. When such routes are redistributed
|
|
to routers in the AS via BGP, they contain IP addresses of a boundary
|
|
routers (in route attribute NEXT_HOP). BGP depends on existing IGP
|
|
routing table with AS-internal routes to determine immediate next hops
|
|
for routes and to know their internal distances to boundary routers
|
|
for the purpose of BGP route selection. In BIRD, there is usually
|
|
one routing table used for both IGP routes and BGP routes.
|
|
|
|
<sect1>Configuration
|
|
|
|
<p>Each instance of the BGP corresponds to one neighboring router.
|
|
This allows to set routing policy and all the other parameters differently
|
|
for each neighbor using the following configuration parameters:
|
|
|
|
<descrip>
|
|
<tag>local <m/[ip]/] as <m/number/</tag> Define which AS we
|
|
are part of. (Note that contrary to other IP routers, BIRD is
|
|
able to act as a router located in multiple AS'es
|
|
simultaneously, but in such cases you need to tweak the BGP
|
|
paths manually in the filters to get consistent behavior.)
|
|
Optional <cf/ip/ argument specifies a source address,
|
|
equivalent to the <cf/source address/ option (see below).
|
|
This parameter is mandatory.
|
|
|
|
<tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router
|
|
this instance will be talking to and what AS it's located in. Unless
|
|
you use the <cf/multihop/ clause, it must be directly connected to one
|
|
of your router's interfaces. In case the neighbor is in the same AS
|
|
as we are, we automatically switch to iBGP. This parameter is mandatory.
|
|
|
|
<tag>multihop <m/[number]/]</tag> Configure multihop BGP
|
|
session to a neighbor that isn't directly connected.
|
|
Accurately, this option should be used if the configured
|
|
neighbor IP address does not match with any local network
|
|
subnets. Such IP address have to be reachable through system
|
|
routing table. For multihop BGP it is recommended to
|
|
explicitly configure <cf/source address/ to have it
|
|
stable. Optional <cf/number/ argument can be used to limit TTL
|
|
(the number of hops).
|
|
Default: switched off.
|
|
|
|
<tag>source address <m/ip/</tag> Define local address we
|
|
should use for next hop calculation and as a source address
|
|
for the BGP session. Default: the address of the local
|
|
end of the interface our neighbor is connected to.
|
|
|
|
<tag>next hop self</tag> Avoid calculation of the Next Hop
|
|
attribute and always advertise our own source address as a
|
|
next hop. This needs to be used only occasionally to
|
|
circumvent misconfigurations of other routers. Default:
|
|
disabled.
|
|
|
|
<tag>missing lladdr self|drop|ignore</tag>Next Hop attribute
|
|
in BGP-IPv6 sometimes contains just the global IPv6 address,
|
|
but sometimes it has to contain both global and link-local
|
|
IPv6 addresses. This option specifies what to do if BIRD have
|
|
to send both addresses but does not know link-local address.
|
|
This situation might happen when routes from other protocols
|
|
are exported to BGP, or when improper updates are received
|
|
from BGP peers. <cf/self/ means that BIRD advertises its own
|
|
local address instead. <cf/drop/ means that BIRD skips that
|
|
prefixes and logs error. <cf/ignore/ means that BIRD ignores
|
|
the problem and sends just the global address (and therefore
|
|
forms improper BGP update). Default: <cf/self/, unless BIRD
|
|
is configured as a route server (option <cf/rs client/), in
|
|
that case default is <cf/ignore/, because route servers usually
|
|
do not forward packets themselves.
|
|
|
|
<tag>gateway direct|recursive</tag>For received routes, their
|
|
<cf/gw/ (immediate next hop) attribute is computed from
|
|
received <cf/bgp_next_hop/ attribute. This option specifies
|
|
how it is computed. Direct mode means that the IP address from
|
|
<cf/bgp_next_hop/ is used if it is directly reachable,
|
|
otherwise the neighbor IP address is used. Recursive mode
|
|
means that the gateway is computed by an IGP routing table
|
|
lookup for the IP address from <cf/bgp_next_hop/. Recursive
|
|
mode is the behavior specified by the BGP standard. Direct
|
|
mode is simpler, does not require any routes in a routing
|
|
table, and was used in older versions of BIRD, but does not
|
|
handle well nontrivial iBGP setups and multihop. Default:
|
|
<cf/direct/ for singlehop eBGP, <cf/recursive/ otherwise.
|
|
|
|
<tag>igp table <m/name/</tag> Specifies a table that is used
|
|
as an IGP routing table. Default: the same as the table BGP is
|
|
connected to.
|
|
|
|
<tag>password <m/string/</tag> Use this password for MD5 authentication
|
|
of BGP sessions. Default: no authentication. Password has to be set by
|
|
external utility (e.g. setkey(8)) on BSD systems.
|
|
|
|
<tag>passive <m/switch/</tag> Standard BGP behavior is both
|
|
initiating outgoing connections and accepting incoming
|
|
connections. In passive mode, outgoing connections are not
|
|
initiated. Default: off.
|
|
|
|
<tag>rr client</tag> Be a route reflector and treat the neighbor as
|
|
a route reflection client. Default: disabled.
|
|
|
|
<tag>rr cluster id <m/IPv4 address/</tag> Route reflectors use cluster id
|
|
to avoid route reflection loops. When there is one route reflector in a cluster
|
|
it usually uses its router id as a cluster id, but when there are more route
|
|
reflectors in a cluster, these need to be configured (using this option) to
|
|
use a common cluster id. Clients in a cluster need not know their cluster
|
|
id and this option is not allowed for them. Default: the same as router id.
|
|
|
|
<tag>rs client</tag> Be a route server and treat the neighbor
|
|
as a route server client. A route server is used as a
|
|
replacement for full mesh EBGP routing in Internet exchange
|
|
points in a similar way to route reflectors used in IBGP routing.
|
|
BIRD does not implement obsoleted RFC 1863, but uses ad-hoc implementation,
|
|
which behaves like plain EBGP but reduces modifications to advertised route
|
|
attributes to be transparent (for example does not prepend its AS number to
|
|
AS PATH attribute and keep MED attribute). Default: disabled.
|
|
|
|
<tag>enable route refresh <m/switch/</tag> When BGP speaker
|
|
changes its import filter, it has to re-examine all routes
|
|
received from its neighbor against the new filter. As these
|
|
routes might not be available, there is a BGP protocol
|
|
extension Route Refresh (specified in RFC 2918) that allows
|
|
BGP speaker to request re-advertisement of all routes from its
|
|
neighbor. This option specifies whether BIRD advertises this
|
|
capability and accepts such requests. Even when disabled, BIRD
|
|
can send route refresh requests. Default: on.
|
|
|
|
<tag>interpret communities <m/switch/</tag> RFC 1997 demands
|
|
that BGP speaker should process well-known communities like
|
|
no-export (65535, 65281) or no-advertise (65535, 65282). For
|
|
example, received route carrying a no-adverise community
|
|
should not be advertised to any of its neighbors. If this
|
|
option is enabled (which is by default), BIRD has such
|
|
behavior automatically (it is evaluated when a route is
|
|
exported to the BGP protocol just before the export filter).
|
|
Otherwise, this integrated processing of well-known
|
|
communities is disabled. In that case, similar behavior can be
|
|
implemented in the export filter. Default: on.
|
|
|
|
<tag>enable as4 <m/switch/</tag> BGP protocol was designed to use 2B AS numbers
|
|
and was extended later to allow 4B AS number. BIRD supports 4B AS extension,
|
|
but by disabling this option it can be persuaded not to advertise it and
|
|
to maintain old-style sessions with its neighbors. This might be useful for
|
|
circumventing bugs in neighbor's implementation of 4B AS extension.
|
|
Even when disabled (off), BIRD behaves internally as AS4-aware BGP router.
|
|
Default: on.
|
|
|
|
<tag>capabilities <m/switch/</tag> Use capability advertisement
|
|
to advertise optional capabilities. This is standard behavior
|
|
for newer BGP implementations, but there might be some older
|
|
BGP implementations that reject such connection attempts.
|
|
When disabled (off), features that request it (4B AS support)
|
|
are also disabled. Default: on, with automatic fallback to
|
|
off when received capability-related error.
|
|
|
|
<tag>advertise ipv4 <m/switch/</tag> Advertise IPv4 multiprotocol capability.
|
|
This is not a correct behavior according to the strict interpretation
|
|
of RFC 4760, but it is widespread and required by some BGP
|
|
implementations (Cisco and Quagga). This option is relevant
|
|
to IPv4 mode with enabled capability advertisement only. Default: on.
|
|
|
|
<tag>route limit <m/number/</tag> The maximal number of routes
|
|
that may be imported from the protocol. If the route limit is
|
|
exceeded, the connection is closed with error. Default: no limit.
|
|
|
|
<tag>disable after error <m/switch/</tag> When an error is encountered (either
|
|
locally or by the other side), disable the instance automatically
|
|
and wait for an administrator to fix the problem manually. Default: off.
|
|
|
|
<tag>hold time <m/number/</tag> Time in seconds to wait for a Keepalive
|
|
message from the other side before considering the connection stale.
|
|
Default: depends on agreement with the neighboring router, we prefer
|
|
240 seconds if the other side is willing to accept it.
|
|
|
|
<tag>startup hold time <m/number/</tag> Value of the hold timer used
|
|
before the routers have a chance to exchange open messages and agree
|
|
on the real value. Default: 240 seconds.
|
|
|
|
<tag>keepalive time <m/number/</tag> Delay in seconds between sending
|
|
of two consecutive Keepalive messages. Default: One third of the hold time.
|
|
|
|
<tag>connect retry time <m/number/</tag> Time in seconds to wait before
|
|
retrying a failed attempt to connect. Default: 120 seconds.
|
|
|
|
<tag>start delay time <m/number/</tag> Delay in seconds between protocol
|
|
startup and the first attempt to connect. Default: 5 seconds.
|
|
|
|
<tag>error wait time <m/number/,<m/number/</tag> Minimum and maximum delay in seconds between a protocol
|
|
failure (either local or reported by the peer) and automatic restart.
|
|
Doesn't apply when <cf/disable after error/ is configured. If consecutive
|
|
errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300.
|
|
|
|
<tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol
|
|
failures to treat them as a error sequence which makes the <cf/error wait time/
|
|
increase exponentially. Default: 300 seconds.
|
|
|
|
<tag>path metric <m/switch/</tag> Enable comparison of path lengths
|
|
when deciding which BGP route is the best one. Default: on.
|
|
|
|
<tag>igp metric <m/switch/</tag> Enable comparison of internal
|
|
distances to boundary routers during best route selection. Default: on.
|
|
|
|
<tag>prefer older <m/switch/</tag> Standard route selection algorithm
|
|
breaks ties by comparing router IDs. This changes the behavior
|
|
to prefer older routes (when both are external and from different
|
|
peer). For details, see RFC 5004. Default: off.
|
|
|
|
<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
|
|
Discriminator to be used during route selection when the MED attribute
|
|
is missing. Default: 0.
|
|
|
|
<tag>default bgp_local_pref <m/number/</tag> A default value
|
|
for the Local Preference attribute. It is used when a new
|
|
Local Preference attribute is attached to a route by the BGP
|
|
protocol itself (for example, if a route is received through
|
|
eBGP and therefore does not have such attribute). Default: 100
|
|
(0 in pre-1.2.0 versions of BIRD).
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
|
|
<p>BGP defines several route attributes. Some of them (those marked with `<tt/I/' in the
|
|
table below) are available on internal BGP connections only, some of them (marked
|
|
with `<tt/O/') are optional.
|
|
|
|
<descrip>
|
|
<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
|
|
the packet will travel through when forwarded according to the particular route. In case of
|
|
internal BGP it doesn't contain the number of the local AS.
|
|
|
|
<tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for
|
|
selection among multiple BGP routes (see the selection rules above). It's
|
|
used as an additional metric which is propagated through the whole local AS.
|
|
|
|
<tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
|
|
is an optional attribute which is used on on external (inter-AS) links to
|
|
convey to an adjacent AS the optimal entry point into the local AS.
|
|
The received attribute may be also propagated over internal BGP links
|
|
(and this is default behavior). The attribute value is zeroed when a route
|
|
is exported from a routing table to a BGP instance to ensure that the attribute
|
|
received from a neighboring AS is not propagated to other neighboring ASes.
|
|
A new value might be set in the export filter of a BGP instance.
|
|
See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
|
|
for further discussion of BGP MED attribute.
|
|
|
|
<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
|
|
if the route has originated in an interior routing protocol or
|
|
<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
|
|
(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
|
|
is unknown.
|
|
|
|
<tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets
|
|
to this destination. On internal BGP connections, it's an address of the
|
|
originating router if it's inside the local AS or a boundary router the
|
|
packet will leave the AS through if it's an exterior route, so each BGP
|
|
speaker within the AS has a chance to use the shortest interior path
|
|
possible to this point.
|
|
|
|
<tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute
|
|
which carries no value, but the sole presence of which indicates that the route
|
|
has been aggregated from multiple routes by some router on the path from
|
|
the originator.
|
|
|
|
<!-- we don't handle aggregators right since they are of a very obscure type
|
|
<tag>bgp_aggregator</tag>
|
|
-->
|
|
<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
|
|
with the route. Each such value is a pair (represented as a <cf/pair/ data
|
|
type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
|
|
the community and the second one being a per-AS identifier. There are lots
|
|
of uses of the community mechanism, but generally they are used to carry
|
|
policy information like "don't export to USA peers". As each AS can define
|
|
its own routing policy, it also has a complete freedom about which community
|
|
attributes it defines and what will their semantics be.
|
|
|
|
<tag>quad <cf/bgp_originator_id/ [O]</tag> This attribute is created by the
|
|
route reflector when reflecting the route and contains the router ID of the
|
|
originator of the route in the local AS.
|
|
|
|
<tag>clist <cf/bgp_cluster_list/ [O]</tag> This attribute contains a list
|
|
of cluster IDs of route reflectors. Each route reflector prepends its
|
|
cluster ID when reflecting the route.
|
|
</descrip>
|
|
|
|
<sect1>Example
|
|
|
|
<p><code>
|
|
protocol bgp {
|
|
local as 65000; # Use a private AS number
|
|
neighbor 62.168.0.130 as 5588; # Our neighbor ...
|
|
multihop; # ... which is connected indirectly
|
|
export filter { # We use non-trivial export rules
|
|
if source = RTS_STATIC then { # Export only static routes
|
|
# Assign our community
|
|
bgp_community.add((65000,5678));
|
|
# Artificially increase path length
|
|
# by advertising local AS number twice
|
|
if bgp_path ~ [= 65000 =] then
|
|
bgp_path.prepend(65000);
|
|
accept;
|
|
}
|
|
reject;
|
|
};
|
|
import all;
|
|
source address 62.168.0.1; # Use a non-standard source address
|
|
}
|
|
</code>
|
|
|
|
<sect>Device
|
|
|
|
<p>The Device protocol is not a real routing protocol. It doesn't generate
|
|
any routes and it only serves as a module for getting information about network
|
|
interfaces from the kernel.
|
|
|
|
<p>Except for very unusual circumstances, you probably should include
|
|
this protocol in the configuration since almost all other protocols
|
|
require network interfaces to be defined for them to work with.
|
|
|
|
<sect1>Configuration
|
|
|
|
<p><descrip>
|
|
<tag>scan time <m/number/</tag> Time in seconds between two scans
|
|
of the network interface list. On systems where we are notified about
|
|
interface status changes asynchronously (such as newer versions of
|
|
Linux), we need to scan the list only in order to avoid confusion by lost
|
|
notification messages, so the default time is set to a large value.
|
|
|
|
<tag>primary [ "<m/mask/" ] <m/prefix/</tag>
|
|
If a network interface has more than one network address,
|
|
BIRD has to choose one of them as a primary one, because some
|
|
routing protocols (for example OSPFv2) suppose there is only
|
|
one network address per interface. By default, BIRD chooses
|
|
the lexicographically smallest address as the primary one.
|
|
|
|
This option allows to specify which network address should be
|
|
chosen as a primary one. Network addresses that match
|
|
<m/prefix/ are preferred to non-matching addresses. If more
|
|
<cf/primary/ options are used, the first one has the highest
|
|
preference. If "<m/mask/" is specified, then such
|
|
<cf/primary/ option is relevant only to matching network
|
|
interfaces.
|
|
|
|
In all cases, an address marked by operating system as
|
|
secondary cannot be chosen as the primary one.
|
|
</descrip>
|
|
|
|
<p>As the Device protocol doesn't generate any routes, it cannot have
|
|
any attributes. Example configuration looks like this:
|
|
|
|
<p><code>
|
|
protocol device {
|
|
scan time 10; # Scan the interfaces often
|
|
primary "eth0" 192.168.1.1;
|
|
primary 192.168.0.0/16;
|
|
}
|
|
</code>
|
|
|
|
<sect>Direct
|
|
|
|
<p>The Direct protocol is a simple generator of device routes for all the
|
|
directly connected networks according to the list of interfaces provided
|
|
by the kernel via the Device protocol.
|
|
|
|
<p>The question is whether it is a good idea to have such device
|
|
routes in BIRD routing table. OS kernel usually handles device routes
|
|
for directly connected networks by itself so we don't need (and don't
|
|
want) to export these routes to the kernel protocol. OSPF protocol
|
|
creates device routes for its interfaces itself and BGP protocol is
|
|
usually used for exporting aggregate routes. Although there are some
|
|
use cases that use the direct protocol (like abusing eBGP as an IGP
|
|
routing protocol), in most cases it is not needed to have these device
|
|
routes in BIRD routing table and to use the direct protocol.
|
|
|
|
<p>The only configurable thing about direct is what interfaces it watches:
|
|
|
|
<p><descrip>
|
|
<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
|
|
protocol will generate device routes for all the interfaces
|
|
available. If you want to restrict it to some subset of interfaces
|
|
(for example if you're using multiple routing tables for policy
|
|
routing and some of the policy domains don't contain all interfaces),
|
|
just use this clause.
|
|
</descrip>
|
|
|
|
<p>Direct device routes don't contain any specific attributes.
|
|
|
|
<p>Example config might look like this:
|
|
|
|
<p><code>
|
|
protocol direct {
|
|
interface "-arc*", "*"; # Exclude the ARCnets
|
|
}
|
|
</code>
|
|
|
|
<sect>Kernel
|
|
|
|
<p>The Kernel protocol is not a real routing protocol. Instead of communicating
|
|
with other routers in the network, it performs synchronization of BIRD's routing
|
|
tables with the OS kernel. Basically, it sends all routing table updates to the kernel
|
|
and from time to time it scans the kernel tables to see whether some routes have
|
|
disappeared (for example due to unnoticed up/down transition of an interface)
|
|
or whether an `alien' route has been added by someone else (depending on the
|
|
<cf/learn/ switch, such routes are either ignored or accepted to our
|
|
table).
|
|
|
|
<p>Unfortunately, there is one thing that makes the routing table
|
|
synchronization a bit more complicated. In the kernel routing table
|
|
there are also device routes for directly connected networks. These
|
|
routes are usually managed by OS itself (as a part of IP address
|
|
configuration) and we don't want to touch that. They are completely
|
|
ignored during the scan of the kernel tables and also the export of
|
|
device routes from BIRD tables to kernel routing tables is restricted
|
|
to prevent accidental interference. This restriction can be disabled using
|
|
<cf/device routes/ switch.
|
|
|
|
<p>If your OS supports only a single routing table, you can configure only one
|
|
instance of the Kernel protocol. If it supports multiple tables (in order to
|
|
allow policy routing; such an OS is for example Linux 2.2), you can run as many instances as you want, but each of
|
|
them must be connected to a different BIRD routing table and to a different
|
|
kernel table.
|
|
|
|
<sect1>Configuration
|
|
|
|
<p><descrip>
|
|
<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
|
|
routing tables when it exits (instead of cleaning them up).
|
|
<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
|
|
kernel routing table.
|
|
<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
|
|
routing tables by other routing daemons or by the system administrator.
|
|
This is possible only on systems which support identification of route
|
|
authorship.
|
|
|
|
<tag>device routes <m/switch/</tag> Enable export of device
|
|
routes to the kernel routing table. By default, such routes
|
|
are rejected (with the exception of explicitly configured
|
|
device routes from the static protocol) regardless of the
|
|
export filter to protect device routes in kernel routing table
|
|
(managed by OS itself) from accidental overwriting or erasing.
|
|
|
|
<tag>kernel table <m/number/</tag> Select which kernel table should
|
|
this particular instance of the Kernel protocol work with. Available
|
|
only on systems supporting multiple routing tables.
|
|
</descrip>
|
|
|
|
<p>The Kernel protocol doesn't define any route attributes.
|
|
<p>A simple configuration can look this way:
|
|
|
|
<p><code>
|
|
protocol kernel {
|
|
import all;
|
|
export all;
|
|
}
|
|
</code>
|
|
|
|
<p>Or for a system with two routing tables:
|
|
|
|
<p><code>
|
|
protocol kernel { # Primary routing table
|
|
learn; # Learn alien routes from the kernel
|
|
persist; # Don't remove routes on bird shutdown
|
|
scan time 10; # Scan kernel routing table every 10 seconds
|
|
import all;
|
|
export all;
|
|
}
|
|
|
|
protocol kernel { # Secondary routing table
|
|
table auxtable;
|
|
kernel table 100;
|
|
export all;
|
|
}
|
|
</code>
|
|
|
|
<sect>OSPF
|
|
|
|
<sect1>Introduction
|
|
|
|
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
|
|
protocol. The current IPv4 version (OSPFv2) is defined in RFC
|
|
2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt"> and
|
|
the current IPv6 version (OSPFv3) is defined in RFC 5340<htmlurl
|
|
url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt"> It's a link state
|
|
(a.k.a. shortest path first) protocol -- each router maintains a
|
|
database describing the autonomous system's topology. Each participating
|
|
router has an identical copy of the database and all routers run the
|
|
same algorithm calculating a shortest path tree with themselves as a
|
|
root. OSPF chooses the least cost path as the best path.
|
|
|
|
<p>In OSPF, the autonomous system can be split to several areas in order
|
|
to reduce the amount of resources consumed for exchanging the routing
|
|
information and to protect the other areas from incorrect routing data.
|
|
Topology of the area is hidden to the rest of the autonomous system.
|
|
|
|
<p>Another very important feature of OSPF is that
|
|
it can keep routing information from other protocols (like Static or BGP)
|
|
in its link state database as external routes. Each external route can
|
|
be tagged by the advertising router, making it possible to pass additional
|
|
information between routers on the boundary of the autonomous system.
|
|
|
|
<p>OSPF quickly detects topological changes in the autonomous system (such
|
|
as router interface failures) and calculates new loop-free routes after a short
|
|
period of convergence. Only a minimal amount of
|
|
routing traffic is involved.
|
|
|
|
<p>Each router participating in OSPF routing periodically sends Hello messages
|
|
to all its interfaces. This allows neighbors to be discovered dynamically.
|
|
Then the neighbors exchange theirs parts of the link state database and keep it
|
|
identical by flooding updates. The flooding process is reliable and ensures
|
|
that each router detects all changes.
|
|
|
|
<sect1>Configuration
|
|
|
|
<p>In the main part of configuration, there can be multiple definitions of
|
|
OSPF areas, each with a different id. These definitions includes many other
|
|
switches and multiple definitions of interfaces. Definition of interface
|
|
may contain many switches and constant definitions and list of neighbors
|
|
on nonbroadcast networks.
|
|
|
|
<code>
|
|
protocol ospf <name> {
|
|
rfc1583compat <switch>;
|
|
tick <num>;
|
|
ecmp <switch> [limit <num>];
|
|
area <id> {
|
|
stub cost <num>;
|
|
networks {
|
|
<prefix>;
|
|
<prefix> hidden;
|
|
}
|
|
stubnet <prefix>;
|
|
stubnet <prefix> {
|
|
hidden <switch>;
|
|
summary <switch>;
|
|
cost <num>;
|
|
}
|
|
interface <interface pattern> {
|
|
cost <num>;
|
|
stub <switch>;
|
|
hello <num>;
|
|
poll <num>;
|
|
retransmit <num>;
|
|
priority <num>;
|
|
wait <num>;
|
|
dead count <num>;
|
|
dead <num>;
|
|
rx buffer [normal|large|<num>];
|
|
type [broadcast|bcast|pointopoint|ptp|
|
|
nonbroadcast|nbma|pointomultipoint|ptmp];
|
|
strict nonbroadcast <switch>;
|
|
check link <switch>;
|
|
ecmp weight <num>;
|
|
authentication [none|simple|cryptographic];
|
|
password "<text>";
|
|
password "<text>" {
|
|
id <num>;
|
|
generate from "<date>";
|
|
generate to "<date>";
|
|
accept from "<date>";
|
|
accept to "<date>";
|
|
};
|
|
neighbors {
|
|
<ip>;
|
|
<ip> eligible;
|
|
};
|
|
};
|
|
virtual link <id> {
|
|
hello <num>;
|
|
retransmit <num>;
|
|
wait <num>;
|
|
dead count <num>;
|
|
dead <num>;
|
|
authentication [none|simple|cryptographic];
|
|
password "<text>";
|
|
};
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<descrip>
|
|
<tag>rfc1583compat <M>switch</M></tag>
|
|
This option controls compatibility of routing table
|
|
calculation with RFC 1583<htmlurl
|
|
url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
|
|
value is no.
|
|
|
|
<tag>tick <M>num</M></tag>
|
|
The routing table calculation and clean-up of areas' databases
|
|
is not performed when a single link state
|
|
change arrives. To lower the CPU utilization, it's processed later
|
|
at periodical intervals of <m/num/ seconds. The default value is 1.
|
|
|
|
<tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
|
|
This option specifies whether OSPF is allowed to generate
|
|
ECMP (equal-cost multipath) routes. Such routes are used when
|
|
there are several directions to the destination, each with
|
|
the same (computed) cost. This option also allows to specify
|
|
a limit on maximal number of nexthops in one route. By
|
|
default, ECMP is disabled. If enabled, default value of the
|
|
limit is 16.
|
|
|
|
<tag>area <M>id</M></tag>
|
|
This defines an OSPF area with given area ID (an integer or an IPv4
|
|
address, similarly to a router ID). The most important area is
|
|
the backbone (ID 0) to which every other area must be connected.
|
|
|
|
<tag>stub cost <M>num</M></tag>
|
|
No external (except default) routes are flooded into stub areas.
|
|
Setting this value marks area stub with defined cost of default route.
|
|
Default value is no. (Area is not stub.)
|
|
|
|
<tag>networks { <m/set/ }</tag>
|
|
Definition of area IP ranges. This is used in summary LSA origination.
|
|
Hidden networks are not propagated into other areas.
|
|
|
|
<tag>stubnet <m/prefix/ { <m/options/ }</tag>
|
|
Stub networks are networks that are not transit networks
|
|
between OSPF routers. They are also propagated through an
|
|
OSPF area as a part of a link state database. By default,
|
|
BIRD generates a stub network record for each primary network
|
|
address on each OSPF interface that does not have any OSPF
|
|
neighbors, and also for each non-primary network address on
|
|
each OSPF interface. This option allows to alter a set of
|
|
stub networks propagated by this router.
|
|
|
|
Each instance of this option adds a stub network with given
|
|
network prefix to the set of propagated stub network, unless
|
|
option <cf/hidden/ is used. It also suppresses default stub
|
|
networks for given network prefix. When option
|
|
<cf/summary/ is used, also default stub networks that are
|
|
subnetworks of given stub network are suppressed. This might
|
|
be used, for example, to aggregate generated stub networks.
|
|
|
|
<tag>interface <M>pattern</M></tag>
|
|
Defines that the specified interfaces belong to the area being defined.
|
|
See <ref id="dsc-iface" name="interface"> common option for detailed description.
|
|
|
|
<tag>virtual link <M>id</M></tag>
|
|
Virtual link to router with the router id. Virtual link acts as a
|
|
point-to-point interface belonging to backbone. The actual area is
|
|
used as transport area. This item cannot be in the backbone.
|
|
|
|
<tag>cost <M>num</M></tag>
|
|
Specifies output cost (metric) of an interface. Default value is 10.
|
|
|
|
<tag>stub <M>switch</M></tag>
|
|
If set to interface it does not listen to any packet and does not send
|
|
any hello. Default value is no.
|
|
|
|
<tag>hello <M>num</M></tag>
|
|
Specifies interval in seconds between sending of Hello messages. Beware, all
|
|
routers on the same network need to have the same hello interval.
|
|
Default value is 10.
|
|
|
|
<tag>poll <M>num</M></tag>
|
|
Specifies interval in seconds between sending of Hello messages for
|
|
some neighbors on NBMA network. Default value is 20.
|
|
|
|
<tag>retransmit <M>num</M></tag>
|
|
Specifies interval in seconds between retransmissions of unacknowledged updates.
|
|
Default value is 5.
|
|
|
|
<tag>priority <M>num</M></tag>
|
|
On every multiple access network (e.g., the Ethernet) Designed Router
|
|
and Backup Designed router are elected. These routers have some
|
|
special functions in the flooding process. Higher priority increases
|
|
preferences in this election. Routers with priority 0 are not
|
|
eligible. Default value is 1.
|
|
|
|
<tag>wait <M>num</M></tag>
|
|
After start, router waits for the specified number of seconds between starting
|
|
election and building adjacency. Default value is 40.
|
|
|
|
<tag>dead count <M>num</M></tag>
|
|
When the router does not receive any messages from a neighbor in
|
|
<m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
|
|
|
|
<tag>dead <M>num</M></tag>
|
|
When the router does not receive any messages from a neighbor in
|
|
<m/dead/ seconds, it will consider the neighbor down. If both directives
|
|
<m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
|
|
|
|
<tag>rx buffer <M>num</M></tag>
|
|
This sets the size of buffer used for receiving packets. The buffer should
|
|
be bigger than maximal size of any packets. Value NORMAL (default)
|
|
means 2*MTU, value LARGE means maximal allowed packet - 65535.
|
|
|
|
<tag>type broadcast|bcast</tag>
|
|
BIRD detects a type of a connected network automatically, but
|
|
sometimes it's convenient to force use of a different type
|
|
manually. On broadcast networks (like ethernet), flooding
|
|
and Hello messages are sent using multicasts (a single packet
|
|
for all the neighbors). A designated router is elected and it
|
|
is responsible for synchronizing the link-state databases and
|
|
originating network LSAs. This network type cannot be used on
|
|
physically NBMA networks and on unnumbered networks (networks
|
|
without proper IP prefix).
|
|
|
|
<tag>type pointopoint|ptp</tag>
|
|
Point-to-point networks connect just 2 routers together. No
|
|
election is performed and no network LSA is originated, which
|
|
makes it simpler and faster to establish. This network type
|
|
is useful not only for physically PtP ifaces (like PPP or
|
|
tunnels), but also for broadcast networks used as PtP links.
|
|
This network type cannot be used on physically NBMA networks.
|
|
|
|
<tag>type nonbroadcast|nbma</tag>
|
|
On NBMA networks, the packets are sent to each neighbor
|
|
separately because of lack of multicast capabilities.
|
|
Like on broadcast networks, a designated router is elected,
|
|
which plays a central role in propagation of LSAs.
|
|
This network type cannot be used on unnumbered networks.
|
|
|
|
<tag>type pointomultipoint|ptmp</tag>
|
|
This is another network type designed to handle NBMA
|
|
networks. In this case the NBMA network is treated as a
|
|
collection of PtP links. This is useful if not every pair of
|
|
routers on the NBMA network has direct communication, or if
|
|
the NBMA network is used as an (possibly unnumbered) PtP
|
|
link.
|
|
|
|
<tag>strict nonbroadcast <M>switch</M></tag>
|
|
If set, don't send hello to any undefined neighbor. This switch
|
|
is ignored on other than NBMA or PtMP networks. Default value is no.
|
|
|
|
<tag>check link <M>switch</M></tag>
|
|
If set, a hardware link state (reported by OS) is taken into
|
|
consideration. When a link disappears (e.g. an ethernet cable is
|
|
unplugged), neighbors are immediately considered unreachable
|
|
and only the address of the iface (instead of whole network
|
|
prefix) is propagated. It is possible that some hardware
|
|
drivers or platforms do not implement this feature. Default value is no.
|
|
|
|
<tag>ecmp weight <M>num</M></tag>
|
|
When ECMP (multipath) routes are allowed, this value specifies
|
|
a relative weight used for nexthops going through the iface.
|
|
Allowed values are 1-256. Default value is 1.
|
|
|
|
<tag>authentication none</tag>
|
|
No passwords are sent in OSPF packets. This is the default value.
|
|
|
|
<tag>authentication simple</tag>
|
|
Every packet carries 8 bytes of password. Received packets
|
|
lacking this password are ignored. This authentication mechanism is
|
|
very weak.
|
|
|
|
<tag>authentication cryptographic</tag>
|
|
16-byte long MD5 digest is appended to every packet. For the digest
|
|
generation 16-byte long passwords are used. Those passwords are
|
|
not sent via network, so this mechanism is quite secure.
|
|
Packets can still be read by an attacker.
|
|
|
|
<tag>password "<M>text</M>"</tag>
|
|
An 8-byte or 16-byte password used for authentication.
|
|
See <ref id="dsc-pass" name="password"> common option for detailed description.
|
|
|
|
<tag>neighbors { <m/set/ } </tag>
|
|
A set of neighbors to which Hello messages on NBMA or PtMP
|
|
networks are to be sent. For NBMA networks, some of them
|
|
could be marked as eligible.
|
|
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
|
|
<p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
|
|
Metric is ranging from 1 to infinity (65535).
|
|
External routes use <cf/metric type 1/ or <cf/metric type 2/.
|
|
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
|
|
<cf/metric of type 2/ is always longer
|
|
than any <cf/metric of type 1/ or any <cf/internal metric/.
|
|
<cf/Internal metric/ or <cf/metric of type 1/ is stored in attribute
|
|
<cf/ospf_metric1/, <cf/metric type 2/ is stored in attribute <cf/ospf_metric2/.
|
|
If you specify both metrics only metric1 is used.
|
|
|
|
Each external route can also carry attribute <cf/ospf_tag/ which is a
|
|
32-bit integer which is used when exporting routes to other protocols;
|
|
otherwise, it doesn't affect routing inside the OSPF domain at all.
|
|
The fourth attribute <cf/ospf_router_id/ is a router ID of the router
|
|
advertising that route/network. This attribute is read-only. Default
|
|
is <cf/ospf_metric2 = 10000/ and <cf/ospf_tag = 0/.
|
|
|
|
<sect1>Example
|
|
|
|
<p>
|
|
|
|
<code>
|
|
protocol ospf MyOSPF {
|
|
rfc1583compat yes;
|
|
tick 2;
|
|
export filter {
|
|
if source = RTS_BGP then {
|
|
ospf_metric1 = 100;
|
|
accept;
|
|
}
|
|
reject;
|
|
};
|
|
area 0.0.0.0 {
|
|
interface "eth*" {
|
|
cost 11;
|
|
hello 15;
|
|
priority 100;
|
|
retransmit 7;
|
|
authentication simple;
|
|
password "aaa";
|
|
};
|
|
interface "ppp*" {
|
|
cost 100;
|
|
authentication cryptographic;
|
|
password "abc" {
|
|
id 1;
|
|
generate to "22-04-2003 11:00:06";
|
|
accept from "17-01-2001 12:01:05";
|
|
};
|
|
password "def" {
|
|
id 2;
|
|
generate to "22-07-2005 17:03:21";
|
|
accept from "22-02-2001 11:34:06";
|
|
};
|
|
};
|
|
interface "arc0" {
|
|
cost 10;
|
|
stub yes;
|
|
};
|
|
interface "arc1";
|
|
};
|
|
area 120 {
|
|
stub yes;
|
|
networks {
|
|
172.16.1.0/24;
|
|
172.16.2.0/24 hidden;
|
|
}
|
|
interface "-arc0" , "arc*" {
|
|
type nonbroadcast;
|
|
authentication none;
|
|
strict nonbroadcast yes;
|
|
wait 120;
|
|
poll 40;
|
|
dead count 8;
|
|
neighbors {
|
|
192.168.120.1 eligible;
|
|
192.168.120.2;
|
|
192.168.120.10;
|
|
};
|
|
};
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<sect>Pipe
|
|
|
|
<sect1>Introduction
|
|
|
|
<p>The Pipe protocol serves as a link between two routing tables, allowing routes to be
|
|
passed from a table declared as primary (i.e., the one the pipe is connected to using the
|
|
<cf/table/ configuration keyword) to the secondary one (declared using <cf/peer table/)
|
|
and vice versa, depending on what's allowed by the filters. Export filters control export
|
|
of routes from the primary table to the secondary one, import filters control the opposite
|
|
direction.
|
|
|
|
<p>The Pipe protocol may work in the opaque mode or in the transparent
|
|
mode. In the opaque mode, the Pipe protocol retransmits optimal route
|
|
from one table to the other table in a similar way like other
|
|
protocols send and receive routes. Retransmitted route will have the
|
|
source set to the Pipe protocol, which may limit access to protocol
|
|
specific route attributes. The opaque mode is a default mode.
|
|
|
|
<p>In transparent mode, the Pipe protocol retransmits all routes from
|
|
one table to the other table, retaining their original source and
|
|
attributes. If import and export filters are set to accept, then both
|
|
tables would have the same content. The mode can be set by
|
|
<tt/mode/ option.
|
|
|
|
<p>The primary use of multiple routing tables and the Pipe protocol is for policy routing,
|
|
where handling of a single packet doesn't depend only on its destination address, but also
|
|
on its source address, source interface, protocol type and other similar parameters.
|
|
In many systems (Linux being a good example), the kernel allows to enforce routing policies
|
|
by defining routing rules which choose one of several routing tables to be used for a packet
|
|
according to its parameters. Setting of these rules is outside the scope of BIRD's work
|
|
(on Linux, you can use the <tt/ip/ command), but you can create several routing tables in BIRD,
|
|
connect them to the kernel ones, use filters to control which routes appear in which tables
|
|
and also you can employ the Pipe protocol for exporting a selected subset of one table to
|
|
another one.
|
|
|
|
<sect1>Configuration
|
|
|
|
<p><descrip>
|
|
<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
|
|
primary one is selected by the <cf/table/ keyword.
|
|
|
|
<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
|
|
<p>The Pipe protocol doesn't define any route attributes.
|
|
|
|
<sect1>Example
|
|
|
|
<p>Let's consider a router which serves as a boundary router of two different autonomous
|
|
systems, each of them connected to a subset of interfaces of the router, having its own
|
|
exterior connectivity and wishing to use the other AS as a backup connectivity in case
|
|
of outage of its own exterior line.
|
|
|
|
<p>Probably the simplest solution to this situation is to use two routing tables (we'll
|
|
call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that packets having
|
|
arrived from interfaces belonging to the first AS will be routed according to <cf/as1/
|
|
and similarly for the second AS. Thus we have split our router to two logical routers,
|
|
each one acting on its own routing table, having its own routing protocols on its own
|
|
interfaces. In order to use the other AS's routes for backup purposes, we can pass
|
|
the routes between the tables through a Pipe protocol while decreasing their preferences
|
|
and correcting their BGP paths to reflect the AS boundary crossing.
|
|
|
|
<code>
|
|
table as1; # Define the tables
|
|
table as2;
|
|
|
|
protocol kernel kern1 { # Synchronize them with the kernel
|
|
table as1;
|
|
kernel table 1;
|
|
}
|
|
|
|
protocol kernel kern2 {
|
|
table as2;
|
|
kernel table 2;
|
|
}
|
|
|
|
protocol bgp bgp1 { # The outside connections
|
|
table as1;
|
|
local as 1;
|
|
neighbor 192.168.0.1 as 1001;
|
|
export all;
|
|
import all;
|
|
}
|
|
|
|
protocol bgp bgp2 {
|
|
table as2;
|
|
local as 2;
|
|
neighbor 10.0.0.1 as 1002;
|
|
export all;
|
|
import all;
|
|
}
|
|
|
|
protocol pipe { # The Pipe
|
|
table as1;
|
|
peer table as2;
|
|
export filter {
|
|
if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks
|
|
if preference>10 then preference = preference-10;
|
|
if source=RTS_BGP then bgp_path.prepend(1);
|
|
accept;
|
|
}
|
|
reject;
|
|
};
|
|
import filter {
|
|
if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks
|
|
if preference>10 then preference = preference-10;
|
|
if source=RTS_BGP then bgp_path.prepend(2);
|
|
accept;
|
|
}
|
|
reject;
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<sect>RAdv
|
|
|
|
<sect1>Introduction
|
|
|
|
<p>The RAdv protocol is an implementation of Router Advertisements,
|
|
which are used in the IPv6 stateless autoconfiguration. IPv6 routers
|
|
send (in irregular time intervals or as an answer to a request)
|
|
advertisement packets to connected networks. These packets contain
|
|
basic information about a local network (e.g. a list of network
|
|
prefixes), which allows network hosts to autoconfigure network
|
|
addresses and choose a default route. BIRD implements router behavior
|
|
as defined in RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">.
|
|
|
|
<sect1>Configuration
|
|
|
|
<p>There are two classes of definitions in RAdv configuration --
|
|
interface definitions and prefix definitions:
|
|
|
|
<descrip>
|
|
<tag>interface <m/pattern [, ...]/ { <m/options/ }</tag>
|
|
Interface definitions specify a set of interfaces on which the
|
|
protocol is activated and contain interface specific options.
|
|
See <ref id="dsc-iface" name="interface"> common options for
|
|
detailed description.
|
|
|
|
<tag>prefix <m/prefix/ { <m/options/ }</tag>
|
|
Prefix definitions allows to modify a list of advertised
|
|
prefixes. By default, the advertised prefixes are the same as
|
|
the network prefixes assigned to the interface. For each
|
|
network prefix, the matching prefix definition is found and
|
|
its options are used. If no matching prefix definition is
|
|
found, the prefix is used with default options.
|
|
|
|
Prefix definitions can be either global or interface-specific.
|
|
The second ones are part of interface options. The prefix
|
|
definition matching is done in the first-match style, when
|
|
interface-specific definitions are processed before global
|
|
definitions. As expected, the prefix definition is matching if
|
|
the network prefix is a subnet of the prefix in prefix
|
|
definition.
|
|
</descrip>
|
|
|
|
<p>Interface specific options:
|
|
|
|
<descrip>
|
|
<tag>max ra interval <m/expr/</tag>
|
|
Unsolicited router advertisements are sent in irregular time
|
|
intervals. This option specifies the maximum length of these
|
|
intervals, in seconds. Valid values are 4-1800. Default: 600
|
|
|
|
<tag>min ra interval <m/expr/</tag>
|
|
This option specifies the minimum length of that intervals, in
|
|
seconds. Must be at least 3 and at most 3/4 * max ra interval.
|
|
Default: about 1/3 * max ra interval.
|
|
|
|
<tag>min delay <m/expr/</tag>
|
|
The minimum delay between two consecutive router advertisements,
|
|
in seconds. Default: 3
|
|
|
|
<tag>managed <m/switch/</tag>
|
|
This option specifies whether hosts should use DHCPv6 for
|
|
IP address configuration. Default: no
|
|
|
|
<tag>other config <m/switch/</tag>
|
|
This option specifies whether hosts should use DHCPv6 to
|
|
receive other configuration information. Default: no
|
|
|
|
<tag>link mtu <m/expr/</tag>
|
|
This option specifies which value of MTU should be used by
|
|
hosts. 0 means unspecified. Default: 0
|
|
|
|
<tag>reachable time <m/expr/</tag>
|
|
This option specifies the time (in milliseconds) how long
|
|
hosts should assume a neighbor is reachable (from the last
|
|
confirmation). Maximum is 3600000, 0 means unspecified.
|
|
Default 0.
|
|
|
|
<tag>retrans timer <m/expr/</tag>
|
|
This option specifies the time (in milliseconds) how long
|
|
hosts should wait before retransmitting Neighbor Solicitation
|
|
messages. 0 means unspecified. Default 0.
|
|
|
|
<tag>current hop limit <m/expr/</tag>
|
|
This option specifies which value of Hop Limit should be used
|
|
by hosts. Valid values are 0-255, 0 means unspecified. Default: 64
|
|
|
|
<tag>default lifetime <m/expr/</tag>
|
|
This option specifies the time (in seconds) how long (after
|
|
the receipt of RA) hosts may use the router as a default
|
|
router. 0 means do not use as a default router. Default: 3 *
|
|
max ra interval.
|
|
</descrip>
|
|
|
|
|
|
<p>Prefix specific options:
|
|
|
|
<descrip>
|
|
<tag>onlink <m/switch/</tag>
|
|
This option specifies whether hosts may use the advertised
|
|
prefix for onlink determination. Default: yes
|
|
|
|
<tag>autonomous <m/switch/</tag>
|
|
This option specifies whether hosts may use the advertised
|
|
prefix for stateless autoconfiguration. Default: yes
|
|
|
|
<tag>valid lifetime <m/expr/</tag>
|
|
This option specifies the time (in seconds) how long (after
|
|
the receipt of RA) the prefix information is valid, i.e.,
|
|
autoconfigured IP addresses can be assigned and hosts with
|
|
that IP addresses are considered directly reachable. 0 means
|
|
the prefix is no longer valid. Default: 86400 (1 day)
|
|
|
|
<tag>preferred lifetime <m/expr/</tag>
|
|
This option specifies the time (in seconds) how long (after
|
|
the receipt of RA) IP addresses generated from the prefix
|
|
using stateless autoconfiguration remain preferred. Default:
|
|
14400 (4 hours)
|
|
</descrip>
|
|
|
|
<sect1>Example
|
|
|
|
<p><code>
|
|
protocol radv {
|
|
interface "eth2" {
|
|
max ra interval 5; # Fast failover with more routers
|
|
managed yes; # Using DHCPv6 on eth2
|
|
prefix ::/0 {
|
|
autonomous off; # So do not autoconfigure any IP
|
|
};
|
|
};
|
|
|
|
interface "eth*"; # No need for any other options
|
|
|
|
prefix 2001:0DB8:1234::/48 {
|
|
preferred lifetime 0; # Deprecated address range
|
|
};
|
|
|
|
prefix 2001:0DB8:2000::/48 {
|
|
autonomous off; # Do not autoconfigure
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<sect>RIP
|
|
|
|
<sect1>Introduction
|
|
|
|
<p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts (to all its neighbors)
|
|
distances to all networks it can reach. When a router hears distance to another network, it increments
|
|
it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes
|
|
unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually, plus
|
|
interface metric, which is usually one). After some time, the distance reaches infinity (that's 15 in
|
|
RIP) and all routers know that network is unreachable. RIP tries to minimize situations where
|
|
counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't use
|
|
RIP on networks where maximal distance is higher than 15 hosts. You can read more about RIP at <HTMLURL
|
|
URL="http://www.ietf.org/html.charters/rip-charter.html" name="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4
|
|
(RFC 1723<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1723.txt">)
|
|
and IPv6 (RFC 2080<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2080.txt">) versions of RIP are supported by BIRD, historical RIPv1 (RFC 1058<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1058.txt">)is
|
|
not currently supported. RIPv4 MD5 authentication (RFC 2082<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2082.txt">) is supported.
|
|
|
|
<p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow
|
|
convergence, big network load and inability to handle larger networks
|
|
makes it pretty much obsolete. (It is still usable on very small networks.)
|
|
|
|
<sect1>Configuration
|
|
|
|
<p>In addition to options common for all to other protocols, RIP supports the following ones:
|
|
|
|
<descrip>
|
|
<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
|
|
packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
|
|
into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
|
|
hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
|
|
section. Default: none.
|
|
|
|
<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
|
|
be honored. (Always, when sent from a host on a directly connected
|
|
network or never.) Routing table updates are honored only from
|
|
neighbors, that is not configurable. Default: never.
|
|
</descrip>
|
|
|
|
<p>There are two options that can be specified per-interface. First is <cf>metric</cf>, with
|
|
default one. Second is <cf>mode multicast|broadcast|quiet|nolisten|version1</cf>, it selects mode for
|
|
rip to work in. If nothing is specified, rip runs in multicast mode. <cf>version1</cf> is
|
|
currently equivalent to <cf>broadcast</cf>, and it makes RIP talk to a broadcast address even
|
|
through multicast mode is possible. <cf>quiet</cf> option means that RIP will not transmit
|
|
any periodic messages to this interface and <cf>nolisten</cf> means that RIP will send to this
|
|
interface but not listen to it.
|
|
|
|
<p>The following options generally override behavior specified in RFC. If you use any of these
|
|
options, BIRD will no longer be RFC-compliant, which means it will not be able to talk to anything
|
|
other than equally configured BIRD. I have warned you.
|
|
|
|
<descrip>
|
|
<tag>port <M>number</M></tag>
|
|
selects IP port to operate on, default 520. (This is useful when testing BIRD, if you
|
|
set this to an address >1024, you will not need to run bird with UID==0).
|
|
|
|
<tag>infinity <M>number</M></tag>
|
|
selects the value of infinity, default is 16. Bigger values will make protocol convergence
|
|
even slower.
|
|
|
|
<tag>period <M>number</M>
|
|
</tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
|
|
number will mean faster convergence but bigger network
|
|
load. Do not use values lower than 10.
|
|
|
|
<tag>timeout time <M>number</M>
|
|
</tag>specifies how old route has to be to be considered unreachable. Default is 4*<cf/period/.
|
|
|
|
<tag>garbage time <M>number</M>
|
|
</tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
|
|
<p>RIP defines two route attributes:
|
|
|
|
<descrip>
|
|
<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
|
|
When routes from different RIP instances are available and all of them have the same
|
|
preference, BIRD prefers the route with lowest <cf/rip_metric/.
|
|
When importing a non-RIP route, the metric defaults to 5.
|
|
|
|
<tag>int <cf/rip_tag/</tag> RIP route tag: a 16-bit number which can be used
|
|
to carry additional information with the route (for example, an originating AS number
|
|
in case of external routes). When importing a non-RIP route, the tag defaults to 0.
|
|
</descrip>
|
|
|
|
<sect1>Example
|
|
|
|
<p><code>
|
|
protocol rip MyRIP_test {
|
|
debug all;
|
|
port 1520;
|
|
period 10;
|
|
garbage time 60;
|
|
interface "eth0" { metric 3; mode multicast; };
|
|
interface "eth*" { metric 2; mode broadcast; };
|
|
honor neighbor;
|
|
authentication none;
|
|
import filter { print "importing"; accept; };
|
|
export filter { print "exporting"; accept; };
|
|
}
|
|
</code>
|
|
|
|
<sect>Static
|
|
|
|
<p>The Static protocol doesn't communicate with other routers in the network,
|
|
but instead it allows you to define routes manually. This is often used for
|
|
specifying how to forward packets to parts of the network which don't use
|
|
dynamic routing at all and also for defining sink routes (i.e., those
|
|
telling to return packets as undeliverable if they are in your IP block,
|
|
you don't have any specific destination for them and you don't want to send
|
|
them out through the default route to prevent routing loops).
|
|
|
|
<p>There are three types of static routes: `classical' routes telling to
|
|
forward packets to a neighboring router, device routes specifying forwarding
|
|
to hosts on a directly connected network and special routes (sink, blackhole
|
|
etc.) which specify a special action to be done instead of forwarding the
|
|
packet.
|
|
|
|
<p>When the particular destination is not available (the interface is down or
|
|
the next hop of the route is not a neighbor at the moment), Static just
|
|
uninstalls the route from the table it is connected to and adds it again as soon
|
|
as the destination becomes adjacent again.
|
|
|
|
<p>The Static protocol does not have many configuration options. The
|
|
definition of the protocol contains mainly a list of static routes:
|
|
|
|
<descrip>
|
|
<tag>route <m/prefix/ via <m/ip/</tag> Static route through
|
|
a neighboring router.
|
|
<tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [via ...]</tag>
|
|
Static multipath route. Contains several nexthops (gateways), possibly
|
|
with their weights.
|
|
<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
|
|
route through an interface to hosts on a directly connected network.
|
|
<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
|
|
specifying to drop the packet, return it as unreachable or return
|
|
it as administratively prohibited.
|
|
|
|
<tag>check link <M>switch</M></tag>
|
|
The only option of the static protocol. If set, hardware link
|
|
states of network interfaces are taken into consideration.
|
|
When link disappears (e.g. ethernet cable is unplugged),
|
|
static routes directing to that interface are removed. It is
|
|
possible that some hardware drivers or platforms do not
|
|
implement this feature. Default: off.
|
|
</descrip>
|
|
|
|
<p>Static routes have no specific attributes.
|
|
|
|
<p>Example static config might look like this:
|
|
|
|
<p><code>
|
|
protocol static {
|
|
table testable; # Connect to a non-default routing table
|
|
route 0.0.0.0/0 via 62.168.0.13; # Default route
|
|
route 10.0.0.0/8 multipath # Multipath route
|
|
via 62.168.0.14 weight 2
|
|
via 62.168.1.10
|
|
via 62.168.1.11;
|
|
route 62.168.0.0/25 reject; # Sink route
|
|
route 10.2.0.0/24 via "arc0"; # Secondary network
|
|
}
|
|
</code>
|
|
|
|
<chapt>Conclusions
|
|
|
|
<sect>Future work
|
|
|
|
<p>Although BIRD supports all the commonly used routing protocols,
|
|
there are still some features which would surely deserve to be
|
|
implemented in future versions of BIRD:
|
|
|
|
<itemize>
|
|
<item>OSPF NSSA areas and opaque LSA's
|
|
<item>Route aggregation and flap dampening
|
|
<item>Generation of IPv6 router advertisements
|
|
<item>Multipath routes
|
|
<item>Multicast routing protocols
|
|
<item>Ports to other systems
|
|
</itemize>
|
|
|
|
<sect>Getting more help
|
|
|
|
<p>If you use BIRD, you're welcome to join the bird-users mailing list
|
|
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
|
|
where you can share your experiences with the other users and consult
|
|
your problems with the authors. To subscribe to the list, just send a
|
|
<tt/subscribe bird-users/ command in a body of a mail to
|
|
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
|
|
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
|
|
|
|
<p>BIRD is a relatively young system and it probably contains some
|
|
bugs. You can report any problems to the bird-users list and the authors
|
|
will be glad to solve them, but before you do so,
|
|
please make sure you have read the available documentation and that you are running the latest version (available at <HTMLURL
|
|
URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). (Of course, a patch
|
|
which fixes the bug is always welcome as an attachment.)
|
|
|
|
<p>If you want to understand what is going inside, Internet standards are
|
|
a good and interesting reading. You can get them from <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
|
|
|
|
<p><it/Good luck!/
|
|
|
|
</book>
|
|
|
|
<!--
|
|
LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
|
|
LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps
|
|
LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC
|
|
LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth
|
|
LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek
|
|
LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC
|
|
LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU
|
|
LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc
|
|
LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats
|
|
LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt
|
|
LocalWords: proto wildcard Ondrej Filip
|
|
-->
|