mirror of
https://gitlab.nic.cz/labs/bird.git
synced 2024-12-22 17:51:53 +00:00
5518 lines
248 KiB
Plaintext
5518 lines
248 KiB
Plaintext
<!doctype birddoc system>
|
|
|
|
<!--
|
|
BIRD 2.0 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 80)
|
|
|
|
Copyright 1999 - 2022 CZ.NIC, z.s.p.o , distribute under GPL version 2 or later.
|
|
|
|
-->
|
|
|
|
<book>
|
|
|
|
<title>BIRD 2.0 User's Guide
|
|
<author>
|
|
Ondrej Filip <it/<feela@network.cz>/,
|
|
Martin Mares <it/<mj@ucw.cz>/,
|
|
Maria Matejka <it/<mq@jmq.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
|
|
<label id="intro">
|
|
|
|
<sect>What is BIRD
|
|
<label id="what-is-bird">
|
|
|
|
<p>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),
|
|
<HTMLURL URL="http://www.zebra.org" name="Zebra"> and
|
|
<HTMLURL URL="http://sourceforge.net/projects/mrt" name="MRTD">,
|
|
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, RIPng)
|
|
<item>the Open Shortest Path First protocol (OSPFv2, OSPFv3)
|
|
<item>the Babel Routing Protocol
|
|
<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 1.x supported either IPv4 or IPv6 protocol, but had to be compiled separately
|
|
for each one. BIRD~2 supports both of them with a possibility of further extension.
|
|
BIRD~2 supports Linux at least 3.16, FreeBSD 10, NetBSD 7.0, and OpenBSD 5.8.
|
|
Anyway, it will probably work well also on older systems.
|
|
|
|
<sect>Installing BIRD
|
|
<label id="install">
|
|
|
|
<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/--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
|
|
<label id="argv">
|
|
|
|
<p>You can pass several command-line options to bird:
|
|
|
|
<descrip>
|
|
<tag><label id="argv-config">-c <m/config name/</tag>
|
|
use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
|
|
|
|
<tag><label id="argv-debug">-d</tag>
|
|
enable debug messages to stderr, and run bird in foreground.
|
|
|
|
<tag><label id="argv-debug-file">-D <m/filename of debug log/</tag>
|
|
enable debug messages to given file.
|
|
|
|
<tag><label id="argv-foreground">-f</tag>
|
|
run bird in foreground.
|
|
|
|
<tag><label id="argv-group">-g <m/group/</tag>
|
|
use that group ID, see the next section for details.
|
|
|
|
<tag><label id="argv-help">-h, --help</tag>
|
|
display command-line options to bird.
|
|
|
|
<tag><label id="argv-local">-l</tag>
|
|
look for a configuration file and a communication socket in the current
|
|
working directory instead of in default system locations. However, paths
|
|
specified by options <cf/-c/, <cf/-s/ have higher priority.
|
|
|
|
<tag><label id="argv-parse">-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><label id="argv-pid">-P <m/name of PID file/</tag>
|
|
create a PID file with given filename.
|
|
|
|
<tag><label id="argv-recovery">-R</tag>
|
|
apply graceful restart recovery after start.
|
|
|
|
<tag><label id="argv-socket">-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>.
|
|
|
|
<tag><label id="argv-user">-u <m/user/</tag>
|
|
drop privileges and use that user ID, see the next section for details.
|
|
|
|
<tag><label id="argv-version">--version</tag>
|
|
display bird version.
|
|
</descrip>
|
|
|
|
<p>BIRD writes messages about its work to log files or syslog (according to config).
|
|
|
|
|
|
<sect>Privileges
|
|
<label id="privileges">
|
|
|
|
<p>BIRD, as a routing daemon, uses several privileged operations (like setting
|
|
routing table and using raw sockets). Traditionally, BIRD is executed and runs
|
|
with root privileges, which may be prone to security problems. The recommended
|
|
way is to use a privilege restriction (options <cf/-u/, <cf/-g/). In that case
|
|
BIRD is executed with root privileges, but it changes its user and group ID to
|
|
an unprivileged ones, while using Linux capabilities to retain just required
|
|
privileges (capabilities CAP_NET_*). Note that the control socket is created
|
|
before the privileges are dropped, but the config file is read after that. The
|
|
privilege restriction is not implemented in BSD port of BIRD.
|
|
|
|
<p>An unprivileged user (as an argument to <cf/-u/ options) may be the user
|
|
<cf/nobody/, but it is suggested to use a new dedicated user account (like
|
|
<cf/bird/). The similar considerations apply for the group option, but there is
|
|
one more condition -- the users in the same group can use <file/birdc/ to
|
|
control BIRD.
|
|
|
|
<p>Finally, there is a possibility to use external tools to run BIRD in an
|
|
environment with restricted privileges. This may need some configuration, but it
|
|
is generally easy -- BIRD needs just the standard library, privileges to read
|
|
the config file and create the control socket and the CAP_NET_* capabilities.
|
|
|
|
|
|
<chapt>Architecture
|
|
<label id="architecture">
|
|
|
|
<sect>Routing tables
|
|
<label id="routing-tables">
|
|
|
|
<p>The heart of BIRD is a routing table. BIRD has several independent routing tables;
|
|
each of them contains routes of exactly one <m/nettype/ (see below). There are two
|
|
default tables -- <cf/master4/ for IPv4 routes and <cf/master6/ for IPv6 routes.
|
|
Other tables must be explicitly configured.
|
|
|
|
<p>
|
|
These routing tables are not kernel forwarding tables. No forwarding is done by
|
|
BIRD. If you want to forward packets using the routes in BIRD tables, you may
|
|
use the Kernel protocol (see below) to synchronize them with kernel FIBs.
|
|
|
|
<p>
|
|
Every nettype defines a (kind of) primary key on routes. Every route source can
|
|
supply one route for every possible primary key; new route announcement replaces
|
|
the old route from the same source, keeping other routes intact. BIRD always
|
|
chooses the best route for each primary key among the known routes and keeps the
|
|
others as suboptimal. When the best route is retracted, BIRD re-runs the best
|
|
route selection algorithm to find the current best route.
|
|
|
|
<p>
|
|
The global best route selection algorithm is (roughly) as follows:
|
|
|
|
<itemize>
|
|
<item>Preferences of the routes are compared.
|
|
<item>Source protocol instance preferences are compared.
|
|
<item>If source protocols are the same (e.g. BGP vs. BGP), the protocol's route selection algorithm is invoked.
|
|
<item>If source protocols are different (e.g. BGP vs. OSPF), result of the algorithm is undefined.
|
|
</itemize>
|
|
|
|
<p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected
|
|
route from a list of entries for one network. Optionally, these lists of entries
|
|
are kept completely sorted (according to preference or some protocol-dependent
|
|
metric). See <ref id="rtable-sorted" name="sorted"> table option for details.
|
|
|
|
<sect>Routes and network types
|
|
<label id="routes">
|
|
|
|
<p>BIRD works with several types of routes. Some of them are typical IP routes,
|
|
others are better described as forwarding rules. We call them all routes,
|
|
regardless of this difference.
|
|
|
|
<p>Every route consists of several attributes (read more about them in the
|
|
<ref id="route-attributes" name="Route attributes"> section); the common for all
|
|
routes are:
|
|
|
|
<itemize>
|
|
<item>IP address of router which told us about this route
|
|
<item>Source protocol instance
|
|
<item>Route preference
|
|
<item>Optional attributes defined by protocols
|
|
</itemize>
|
|
|
|
<p>Other attributes depend on nettypes. Some of them are part of the primary key, these are marked (PK).
|
|
|
|
<sect1>IPv4 and IPv6 routes
|
|
<label id="ip-routes">
|
|
|
|
<p>The traditional routes. Configuration keywords are <cf/ipv4/ and <cf/ipv6/.
|
|
|
|
<itemize>
|
|
<item>(PK) Route destination (IP prefix together with its length)
|
|
<item>Route next hops (see below)
|
|
</itemize>
|
|
|
|
<sect1>IPv6 source-specific routes
|
|
<label id="ip-sadr-routes">
|
|
|
|
<p>The IPv6 routes containing both destination and source prefix. They are used
|
|
for source-specific routing (SSR), also called source-address dependent routing
|
|
(SADR), see <rfc id="8043">. Currently limited mostly to the Babel protocol.
|
|
Configuration keyword is <cf/ipv6 sadr/.
|
|
|
|
<itemize>
|
|
<item>(PK) Route destination (IP prefix together with its length)
|
|
<item>(PK) Route source (IP prefix together with its length)
|
|
<item>Route next hops (see below)
|
|
</itemize>
|
|
|
|
<sect1>VPN IPv4 and IPv6 routes
|
|
<label id="vpn-routes">
|
|
|
|
<p>Routes for IPv4 and IPv6 with VPN Route Distinguisher (<rfc id="4364">).
|
|
Configuration keywords are <cf/vpn4/ and <cf/vpn6/.
|
|
|
|
<itemize>
|
|
<item>(PK) Route destination (IP prefix together with its length)
|
|
<item>(PK) Route distinguisher (according to <rfc id="4364">)
|
|
<item>Route next hops
|
|
</itemize>
|
|
|
|
<sect1>Route Origin Authorization for IPv4 and IPv6
|
|
<label id="roa-routes">
|
|
|
|
<p>These entries can be used to validate route origination of BGP routes.
|
|
A ROA entry specifies prefixes which could be originated by an AS number.
|
|
Their keywords are <cf/roa4/ and <cf/roa6/.
|
|
|
|
<itemize>
|
|
<item>(PK) IP prefix together with its length
|
|
<item>(PK) Matching prefix maximal length
|
|
<item>(PK) AS number
|
|
</itemize>
|
|
|
|
<sect1>Flowspec for IPv4 and IPv6
|
|
<label id="flow-routes">
|
|
|
|
<p>Flowspec rules are a form of firewall and traffic flow control rules
|
|
distributed mostly via BGP. These rules may help the operators stop various
|
|
network attacks in the beginning before eating up the whole bandwidth.
|
|
Configuration keywords are <cf/flow4/ and <cf/flow6/.
|
|
|
|
<itemize>
|
|
<item>(PK) IP prefix together with its length
|
|
<item>(PK) Flow definition data
|
|
<item>Flow action (encoded internally as BGP communities according to <rfc id="5575">)
|
|
</itemize>
|
|
|
|
<sect1>MPLS switching rules
|
|
<label id="mpls-routes">
|
|
|
|
<p>This nettype is currently a stub before implementing more support of <rfc id="3031">.
|
|
BIRD currently does not support any label distribution protocol nor any label assignment method.
|
|
Only the Kernel, Pipe and Static protocols can use MPLS tables.
|
|
Configuration keyword is <cf/mpls/.
|
|
|
|
<itemize>
|
|
<item>(PK) MPLS label
|
|
<item>Route next hops
|
|
</itemize>
|
|
|
|
<sect1>Route next hops
|
|
<label id="route-next-hop">
|
|
|
|
<p>This is not a nettype. The route next hop is a complex attribute common for many
|
|
nettypes as you can see before. Every next hop has its assigned device
|
|
(either assumed from its IP address or set explicitly). It may have also
|
|
an IP address and an MPLS stack (one or both independently).
|
|
Maximal MPLS stack depth is set (in compile time) to 8 labels.
|
|
|
|
<p>Every route (when eligible to have a next hop) can have more than one next hop.
|
|
In that case, every next hop has also its weight.
|
|
|
|
<sect>Protocols and channels
|
|
<label id="protocols-concept">
|
|
|
|
<p>BIRD protocol is an abstract class of producers and consumers of the routes.
|
|
Each protocol may run in multiple instances and bind on one side to route
|
|
tables via channels, on the other side to specified listen sockets (BGP),
|
|
interfaces (Babel, OSPF, RIP), APIs (Kernel, Direct), or nothing (Static, Pipe).
|
|
|
|
<p>There are also two protocols that do not have any channels -- BFD and Device.
|
|
Both of them are kind of service for other protocols.
|
|
|
|
<p>Each protocol is connected to a routing table through a channel. Some protocols
|
|
support only one channel (OSPF, RIP), some protocols support more channels (BGP, Direct).
|
|
Each channel has two filters which can accept, reject and modify the routes.
|
|
An <it/export/ filter is applied to routes passed from the routing table to the protocol,
|
|
an <it/import/ filter is applied to routes in the opposite direction.
|
|
|
|
<sect>Graceful restart
|
|
<label id="graceful-restart">
|
|
|
|
<p>When BIRD is started after restart or crash, it repopulates routing tables in
|
|
an uncoordinated manner, like after clean start. This may be impractical in some
|
|
cases, because if the forwarding plane (i.e. kernel routing tables) remains
|
|
intact, then its synchronization with BIRD would temporarily disrupt packet
|
|
forwarding until protocols converge. Graceful restart is a mechanism that could
|
|
help with this issue. Generally, it works by starting protocols and letting them
|
|
repopulate routing tables while deferring route propagation until protocols
|
|
acknowledge their convergence. Note that graceful restart behavior have to be
|
|
configured for all relevant protocols and requires protocol-specific support
|
|
(currently implemented for Kernel and BGP protocols), it is activated for
|
|
particular boot by option <cf/-R/.
|
|
|
|
<p>Some protocols (e.g. BGP) could be restarted gracefully after both
|
|
intentional outage and crash, while others (e.g. OSPF) after intentional outage
|
|
only. For planned graceful restart, BIRD must be shut down by
|
|
<ref id="cli-graceful-restart" name="graceful restart"> command instead of
|
|
regular <ref id="cli-down" name="down"> command. In this way routing neighbors
|
|
are notified about planned graceful restart and routes are kept in kernel table
|
|
after shutdown.
|
|
|
|
|
|
<chapt>Configuration
|
|
<label id="config">
|
|
|
|
<sect>Introduction
|
|
<label id="config-intro">
|
|
|
|
<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. There are two
|
|
ways how to name symbols (like protocol names, filter names, constants etc.).
|
|
You can either use a simple string starting with a letter (or underscore)
|
|
followed by any combination of letters, numbers and underscores (e.g. <cf/R123/,
|
|
<cf/my_filter/, <cf/bgp5/) or you can enclose the name into apostrophes (<cf/'/)
|
|
and than you can use any combination of numbers, letters, underscores, hyphens,
|
|
dots and colons (e.g. <cf/'1:strange-name'/, <cf/'-NAME-'/, <cf/'cool::name'/).
|
|
|
|
<p>Here is an example of a simple config file. It enables synchronization of
|
|
routing tables with OS kernel, learns network interfaces and runs RIP on all
|
|
network interfaces found.
|
|
|
|
<code>
|
|
protocol kernel {
|
|
ipv4 {
|
|
export all; # Default is export none
|
|
};
|
|
persist; # Don't remove routes on BIRD shutdown
|
|
}
|
|
|
|
protocol device {
|
|
}
|
|
|
|
protocol rip {
|
|
ipv4 {
|
|
import all;
|
|
export all;
|
|
};
|
|
interface "*";
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>Global options
|
|
<label id="global-opts">
|
|
|
|
<p><descrip>
|
|
<tag><label id="opt-include">include "<m/filename/";</tag>
|
|
This statement causes inclusion of a new file. The <m/filename/ could
|
|
also be a wildcard, in that case matching files are included in
|
|
alphabetic order. The maximal depth is 8. Note that this statement can
|
|
be used anywhere in the config file, even inside other options, but
|
|
always on the beginning of line. In the following example, the first
|
|
semicolon belongs to the <cf/include/, the second to <cf/ipv6 table/.
|
|
If the <file/tablename.conf/ contains exactly one token (the name of the
|
|
table), this construction is correct:
|
|
<code>
|
|
ipv6 table
|
|
include "tablename.conf";;
|
|
</code>
|
|
|
|
<tag><label id="opt-log">log "<m/filename/" [<m/limit/ "<m/backup/"] | 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 [, <m/.../] }</cf> etc.) into selected destination - a file
|
|
specified as a filename string (with optional log rotation information),
|
|
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.
|
|
|
|
Logging directly to file supports basic log rotation -- there is an
|
|
optional log file limit and a backup filename, when log file reaches the
|
|
limit, the current log file is renamed to the backup filename and a new
|
|
log file is created.
|
|
|
|
You may specify more than one <cf/log/ line to establish logging to
|
|
multiple destinations. Default: log everything to the system log, or
|
|
to the debug output if debugging is enabled by <cf/-d//<cf/-D/
|
|
command-line option.
|
|
|
|
<tag><label id="opt-debug-protocols">debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag>
|
|
Set global defaults of protocol debugging options.
|
|
See <ref id="proto-debug" name="debug"> in the following section.
|
|
Default: off.
|
|
|
|
<tag><label id="opt-debug-channels">debug channels all|off|{ states|routes|filters|events [, <m/.../] }</tag>
|
|
Set global defaults of channel debugging options.
|
|
See <ref id="channel-debug" name="debug"> in the channel section.
|
|
Default: off.
|
|
|
|
<tag><label id="opt-debug-commands">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><label id="opt-debug-latency">debug latency <m/switch/</tag>
|
|
Activate tracking of elapsed time for internal events. Recent events
|
|
could be examined using <cf/dump events/ command. Default: off.
|
|
|
|
<tag><label id="opt-debug-latency-limit">debug latency limit <m/time/</tag>
|
|
If <cf/debug latency/ is enabled, this option allows to specify a limit
|
|
for elapsed time. Events exceeding the limit are logged. Default: 1 s.
|
|
|
|
<tag><label id="opt-watchdog-warn">watchdog warning <m/time/</tag>
|
|
Set time limit for I/O loop cycle. If one iteration took more time to
|
|
complete, a warning is logged. Default: 5 s.
|
|
|
|
<tag><label id="opt-watchdog-timeout">watchdog timeout <m/time/</tag>
|
|
Set time limit for I/O loop cycle. If the limit is breached, BIRD is
|
|
killed by abort signal. The timeout has effective granularity of
|
|
seconds, zero means disabled. Default: disabled (0).
|
|
|
|
<tag><label id="opt-mrtdump">mrtdump "<m/filename/"</tag>
|
|
Set MRTdump file name. This option must be specified to allow MRTdump
|
|
feature. Default: no dump file.
|
|
|
|
<tag><label id="opt-mrtdump-protocols">mrtdump protocols all|off|{ states|messages [, <m/.../] }</tag>
|
|
Set global defaults of MRTdump options. See <cf/mrtdump/ in the
|
|
following section. Default: off.
|
|
|
|
<tag><label id="opt-filter">filter <m/name local variables/{ <m/commands/ }</tag>
|
|
Define a filter. You can learn more about filters in the following
|
|
chapter.
|
|
|
|
<tag><label id="opt-function">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><label id="opt-protocol">protocol rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <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. When <cf>from <m/name2/</cf> expression is used,
|
|
initial protocol options are taken from protocol or template
|
|
<cf><m/name2/</cf> You can run more than one instance of most protocols
|
|
(like RIP or BGP). By default, no instances are configured.
|
|
|
|
<tag><label id="opt-template">template rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
|
|
Define a protocol template instance called <m/name/ (or with a name like
|
|
"bgp1" generated automatically if you don't specify any <m/name/).
|
|
Protocol templates can be used to group common options when many
|
|
similarly configured protocol instances are to be defined. Protocol
|
|
instances (and other templates) can use templates by using <cf/from/
|
|
expression and the name of the template. At the moment templates (and
|
|
<cf/from/ expression) are not implemented for OSPF protocol.
|
|
|
|
<tag><label id="opt-define">define <m/constant/ = <m/expression/</tag>
|
|
Define a constant. You can use it later in every place you could use a
|
|
value of the same type. Besides, there are some predefined numeric
|
|
constants based on /etc/iproute2/rt_* files. A list of defined constants
|
|
can be seen (together with other symbols) using 'show symbols' command.
|
|
|
|
<tag><label id="opt-attribute">attribute <m/type/ <m/name/</tag>
|
|
Declare a custom route attribute. You can set and get it in filters like
|
|
any other route attribute. This feature is intended for marking routes
|
|
in import filters for export filtering purposes instead of locally
|
|
assigned BGP communities which have to be deleted in export filters.
|
|
|
|
<tag><label id="opt-router-id">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: the lowest
|
|
IPv4 address of a non-loopback interface.
|
|
|
|
<tag><label id="opt-router-id-from">router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../]</tag>
|
|
Set BIRD's router ID based on an IPv4 address of an interface specified by
|
|
an interface pattern.
|
|
See <ref id="proto-iface" name="interface"> section for detailed
|
|
description of interface patterns with extended clauses.
|
|
|
|
<tag><label id="opt-hostname">hostname "<m/name/"</tag>
|
|
Set hostname. Default: node name as returned by `uname -n'.
|
|
|
|
<tag><label id="opt-graceful-restart">graceful restart wait <m/number/</tag>
|
|
During graceful restart recovery, BIRD waits for convergence of routing
|
|
protocols. This option allows to specify a timeout for the recovery to
|
|
prevent waiting indefinitely if some protocols cannot converge. Default:
|
|
240 seconds.
|
|
|
|
<tag><label id="opt-timeformat">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). It is extended to support sub-second
|
|
time part with variable precision (up to microseconds) using "%f"
|
|
conversion code (e.g., "%T.%3f" is hh:mm:ss.sss time). <m/limit/ and
|
|
"<m/format2/" allow to specify the second format string for times in
|
|
past deeper than <m/limit/ seconds.
|
|
|
|
There are several 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"/. Similarly, <cf/iso long ms/ and <cf/iso long us/ are ISO 8601
|
|
date/time formats with millisecond or microsecond precision.
|
|
<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"/. And there are also <cf/iso short ms/ and <cf/iso short us/
|
|
high-precision variants of that.
|
|
|
|
By default, BIRD uses the <cf/iso short ms/ format for <cf/route/ and
|
|
<cf/protocol/ times, and the <cf/iso long ms/ format for <cf/base/ and
|
|
<cf/log/ times.
|
|
|
|
<tag><label id="opt-table"><m/nettype/ table <m/name/ [ { <m/option/; [<m/.../] } ]</tag>
|
|
Define a new routing table. The default routing tables <cf/master4/ and
|
|
<cf/master6/ are defined implicitly, other routing tables have to be
|
|
defined by this option. See the <ref id="rtable-opts"
|
|
name="routing table configuration section"> for routing table options.
|
|
|
|
<tag><label id="opt-eval">eval <m/expr/</tag>
|
|
Evaluates given filter expression. It is used by the developers for testing of filters.
|
|
</descrip>
|
|
|
|
|
|
<sect>Routing table options
|
|
<label id="rtable-opts">
|
|
|
|
<p>Most routing tables do not need any options and are defined without an option
|
|
block, but there are still some options to tweak routing table behavior. Note
|
|
that implicit tables (<cf/master4/ and <cf/master6/) can be redefined in order
|
|
to set options.
|
|
|
|
<descrip>
|
|
<tag><label id="rtable-sorted">sorted <m/switch/</tag>
|
|
Usually, a routing table just chooses the selected (best) route from a
|
|
list of routes for each network, while keeping remaining routes unsorted.
|
|
If enabled, these lists of routes are kept completely sorted (according
|
|
to preference or some protocol-dependent metric).
|
|
|
|
This is needed for some protocol features (e.g. <cf/secondary/ option of
|
|
BGP protocol, which allows to accept not just a selected route, but the
|
|
first route (in the sorted list) that is accepted by filters), but it is
|
|
incompatible with some other features (e.g. <cf/deterministic med/
|
|
option of BGP protocol, which activates a way of choosing selected route
|
|
that cannot be described using comparison and ordering). Minor advantage
|
|
is that routes are shown sorted in <cf/show route/, minor disadvantage
|
|
is that it is slightly more computationally expensive. Default: off.
|
|
|
|
<tag><label id="rtable-trie">trie <m/switch/</tag>
|
|
BIRD routing tables are implemented with hash tables, which is efficient
|
|
for exact-match lookups, but inconvenient for longest-match lookups or
|
|
interval lookups (finding superprefix or subprefixes). This option
|
|
activates additional trie structure that is used to accelerate these
|
|
lookups, while using the hash table for exact-match lookups.
|
|
|
|
This has advantage for <ref id="rpki" name="RPKI"> (on ROA tables),
|
|
for <ref id="bgp-gateway" name="recursive next-hops"> (on IGP tables),
|
|
and is required for <ref id="bgp-validate" name="flowspec validation">
|
|
(on base IP tables). Another advantage is that interval results (like
|
|
from <cf/show route in .../ command) are lexicographically sorted. The
|
|
disadvantage is that trie-enabled routing tables require more memory,
|
|
which may be an issue especially in multi-table setups. Default: off.
|
|
|
|
<tag><label id="rtable-min-settle-time">min settle time <m/time/</tag>
|
|
Specify a minimum value of the settle time. When a ROA table changes,
|
|
automatic <ref id="proto-rpki-reload" name="RPKI reload"> may be
|
|
triggered, after a short settle time. Minimum settle time is a delay
|
|
from the last ROA table change to wait for more updates. Default: 1 s.
|
|
|
|
|
|
<tag><label id="rtable-max-settle-time">max settle time <m/time/</tag>
|
|
Specify a maximum value of the settle time. When a ROA table changes,
|
|
automatic <ref id="proto-rpki-reload" name="RPKI reload"> may be
|
|
triggered, after a short settle time. Maximum settle time is an upper
|
|
limit to the settle time from the initial ROA table change even if
|
|
there are consecutive updates gradually renewing the settle time.
|
|
Default: 20 s.
|
|
|
|
<tag><label id="rtable-gc-threshold">gc threshold <m/number/</tag>
|
|
Specify a minimum amount of removed networks that triggers a garbage
|
|
collection (GC) cycle. Default: 1000.
|
|
|
|
<tag><label id="rtable-gc-period">gc period <m/time/</tag>
|
|
Specify a period of time between consecutive GC cycles. When there is a
|
|
significant amount of route withdraws, GC cycles are executed repeatedly
|
|
with given period time (with some random factor). When there is just
|
|
small amount of changes, GC cycles are not executed. In extensive route
|
|
server setups, running GC on hundreds of full BGP routing tables can
|
|
take significant amount of time, therefore they should use higher GC
|
|
periods. Default: adaptive, based on number of routing tables in the
|
|
configuration. From 10 s (with <= 25 routing tables) up to 600 s (with
|
|
>= 1500 routing tables).
|
|
</descrip>
|
|
|
|
|
|
<sect>Protocol options
|
|
<label id="protocol-opts">
|
|
|
|
<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 <m/switch/ 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 <m/switch/ is equivalent to <cf/on/ ("silence means
|
|
agreement").
|
|
|
|
<descrip>
|
|
<tag><label id="proto-disabled">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><label id="proto-debug">debug all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</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 selected types: <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. Classes
|
|
<cf/routes/ and <cf/filters/ can be also set per-channel using
|
|
<ref id="channel-debug" name="channel debugging option">) Default: off.
|
|
|
|
<tag><label id="proto-mrtdump">mrtdump all|off|{ states|messages [, <m/.../] }</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><label id="proto-router-id">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><label id="proto-description">description "<m/text/"</tag>
|
|
This is an optional description of the protocol. It is displayed as a
|
|
part of the output of 'show protocols all' command.
|
|
|
|
<tag><label id="proto-vrf">vrf "<m/text/"|default</tag>
|
|
Associate the protocol with specific VRF. The protocol will be
|
|
restricted to interfaces assigned to the VRF and will use sockets bound
|
|
to the VRF. A corresponding VRF interface must exist on OS level. For
|
|
kernel protocol, an appropriate table still must be explicitly selected
|
|
by <cf/table/ option.
|
|
|
|
By selecting <cf/default/, the protocol is associated with the default
|
|
VRF; i.e., it will be restricted to interfaces not assigned to any
|
|
regular VRF. That is different from not specifying <cf/vrf/ at all, in
|
|
which case the protocol may use any interface regardless of its VRF
|
|
status.
|
|
|
|
Note that for proper VRF support it is necessary to use Linux kernel
|
|
version at least 4.14, older versions have limited VRF implementation.
|
|
Before Linux kernel 5.0, a socket bound to a port in default VRF collide
|
|
with others in regular VRFs. In BGP, this can be avoided by using
|
|
<ref id="bgp-strict-bind" name="strict bind"> option.
|
|
|
|
<tag><label id="proto-channel"><m/channel name/ [{<m/channel config/}]</tag>
|
|
Every channel must be explicitly stated. See the protocol-specific
|
|
configuration for the list of supported channel names. See the
|
|
<ref id="channel-opts" name="channel configuration section"> for channel
|
|
definition.
|
|
</descrip>
|
|
|
|
<p>There are several options that give sense only with certain protocols:
|
|
|
|
<descrip>
|
|
<tag><label id="proto-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../] [ { <m/option/; [<m/.../] } ]</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 is a mask specified as a shell-like pattern. Interfaces are
|
|
matched by their name.
|
|
|
|
An interface matches the pattern if it matches any of its clauses. If
|
|
the clause begins with <cf/-/, matching interfaces are excluded. Patterns
|
|
are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/
|
|
means eth0 and all non-ethernets.
|
|
|
|
Some protocols (namely OSPFv2 and Direct) support extended clauses that
|
|
may contain a mask, a prefix, or both of them. An interface matches such
|
|
clause if its name matches the mask (if specified) and its address
|
|
matches the prefix (if specified). Extended clauses are used when the
|
|
protocol handles multiple addresses on an interface independently.
|
|
|
|
An interface option can be used more times with different interface-specific
|
|
options, in that case for given interface the first matching interface
|
|
option is used.
|
|
|
|
This option is allowed in Babel, BFD, Device, Direct, OSPF, RAdv and RIP
|
|
protocols. In OSPF protocol it is used in the <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 "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="proto-tx-class">tx class|dscp <m/num/</tag>
|
|
This option specifies the value of ToS/DS/Class field in IP headers of
|
|
the outgoing protocol packets. This may affect how the protocol packets
|
|
are processed by the network relative to the other network traffic. With
|
|
<cf/class/ keyword, the value (0-255) is used for the whole ToS/Class
|
|
octet (but two bits reserved for ECN are ignored). With <cf/dscp/
|
|
keyword, the value (0-63) is used just for the DS field in the octet.
|
|
Default value is 0xc0 (DSCP 0x30 - CS6).
|
|
|
|
<tag><label id="proto-tx-priority">tx priority <m/num/</tag>
|
|
This option specifies the local packet priority. This may affect how the
|
|
protocol packets are processed in the local TX queues. This option is
|
|
Linux specific. Default value is 7 (highest priority, privileged traffic).
|
|
|
|
<tag><label id="proto-pass">password "<m/password/" | <m/hex_key/ [ { <m>password options</m> } ] </tag>
|
|
Specifies a password that can be used by the protocol as a shared secret
|
|
key. Password option can be used more times to specify more passwords.
|
|
If more passwords are specified, it is a protocol-dependent decision
|
|
which one is really used. Specifying passwords does not mean that
|
|
authentication is enabled, authentication can be enabled by separate,
|
|
protocol-dependent <cf/authentication/ option.
|
|
|
|
A password can also be specified as a hexadecimal key. <m/hex_key/ is a
|
|
sequence of hexadecimal digit pairs, optionally colon-separated. A key
|
|
specified this way must be at least 16 bytes (32 digits) long (although
|
|
specific algorithms can impose other restrictions).
|
|
|
|
This option is allowed in BFD, OSPF, RIP, and Babel 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><label id="proto-pass-id">id <M>num</M></tag>
|
|
ID of the password, (0-255). If it is not specified, BIRD will choose ID
|
|
based on an order of the password item in the interface, starting from
|
|
1. For example, second password item in one interface will have default
|
|
ID 2. ID 0 is allowed by BIRD, but some other implementations may not
|
|
allow it. ID is used by some routing protocols to identify which
|
|
password was used to authenticate protocol packets.
|
|
|
|
<tag><label id="proto-pass-gen-from">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><label id="proto-pass-gen-to">generate to "<m/time/"</tag>
|
|
The last time of the usage of the password for packet signing.
|
|
|
|
<tag><label id="proto-pass-accept-from">accept from "<m/time/"</tag>
|
|
The start time of the usage of the password for packet verification.
|
|
|
|
<tag><label id="proto-pass-accept-to">accept to "<m/time/"</tag>
|
|
The last time of the usage of the password for packet verification.
|
|
|
|
<tag><label id="proto-pass-from">from "<m/time/"</tag>
|
|
Shorthand for setting both <cf/generate from/ and <cf/accept from/.
|
|
|
|
<tag><label id="proto-pass-to">to "<m/time/"</tag>
|
|
Shorthand for setting both <cf/generate to/ and <cf/accept to/.
|
|
|
|
<tag><label id="proto-pass-algorithm">algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 | blake2s128 | blake2s256 | blake2b256 | blake2b512 )</tag>
|
|
The message authentication algorithm for the password when cryptographic
|
|
authentication is enabled. The default value depends on the protocol.
|
|
For RIP and OSPFv2 it is Keyed-MD5 (for compatibility), for OSPFv3 and
|
|
Babel it is HMAC-SHA-256.
|
|
|
|
</descrip>
|
|
|
|
|
|
<sect>Channel options
|
|
<label id="channel-opts">
|
|
|
|
<p>Every channel belongs to a protocol and is configured inside its block. The
|
|
minimal channel config is empty, then it uses default values. The name of the
|
|
channel implies its nettype. Channel definitions can be inherited from protocol
|
|
templates. Multiple definitions of the same channel are forbidden, but channels
|
|
inherited from templates can be updated by new definitions.
|
|
|
|
<descrip>
|
|
<tag><label id="channel-debug">debug all|off|{ states|routes|filters [, <m/.../] }</tag>
|
|
Set channel debugging options. Like in <ref id="proto-debug"
|
|
name="protocol debugging">, channels are 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
|
|
selected types: <cf/states/ for channel state changes (channel going up,
|
|
down, feeding, reloading etc.), <cf/routes/ for routes propagated
|
|
through the channel, <cf/filters/ for details on route filtering,
|
|
remaining debug flags are not used in channel debug. Default: off.
|
|
|
|
<tag><label id="proto-table">table <m/name/</tag>
|
|
Specify a table to which the channel is connected. Default: the first
|
|
table of given nettype.
|
|
|
|
<tag><label id="proto-preference">preference <m/expr/</tag>
|
|
Sets the preference of routes generated by the protocol and imported
|
|
through this channel. Default: protocol dependent.
|
|
|
|
<tag><label id="proto-import">import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/boolean filter expression/</tag>
|
|
Specify a filter to be used for filtering routes coming from the
|
|
protocol to the routing table. <cf/all/ is for keeping all routes,
|
|
<cf/none/ is for dropping all routes. Default: <cf/all/ (except for
|
|
EBGP).
|
|
|
|
<tag><label id="proto-export">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/
|
|
(except for EBGP).
|
|
|
|
<tag><label id="proto-import-keep-filtered">import keep filtered <m/switch/</tag>
|
|
Usually, if an import filter rejects a route, the route is forgotten.
|
|
When this option is active, these routes are kept in the routing table,
|
|
but they are hidden and not propagated to other protocols. But it is
|
|
possible to show them using <cf/show route filtered/. Note that this
|
|
option does not work for the pipe protocol. Default: off.
|
|
|
|
<tag><label id="proto-rpki-reload">rpki reload <m/switch/</tag>
|
|
Import or export filters may depend on route RPKI status (using
|
|
<cf/roa_check()/ operator). In contrast to to other filter operators,
|
|
this status for the same route may change as the content of ROA tables
|
|
changes. When this option is active, BIRD activates automatic reload of
|
|
affected channels whenever ROA tables are updated (after a short settle
|
|
time). When disabled, route reloads have to be requested manually. The
|
|
option is ignored if <cf/roa_check()/ is not used in channel filters.
|
|
Note that for BGP channels, automatic reload requires
|
|
<ref id="bgp-import-table" name="import table"> or
|
|
<ref id="bgp-export-table" name="export table"> (for respective
|
|
direction). Default: on.
|
|
|
|
<tag><label id="proto-import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
|
|
Specify an import route limit (a maximum number of routes imported from
|
|
the protocol) and optionally the action to be taken when the limit is
|
|
hit. Warn action just prints warning log message. Block action discards
|
|
new routes coming from the protocol. Restart and disable actions shut
|
|
the protocol down like appropriate commands. Disable is the default
|
|
action if an action is not explicitly specified. Note that limits are
|
|
reset during protocol reconfigure, reload or restart. Default: <cf/off/.
|
|
|
|
<tag><label id="proto-receive-limit">receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
|
|
Specify an receive route limit (a maximum number of routes received from
|
|
the protocol and remembered). It works almost identically to <cf>import
|
|
limit</cf> option, the only difference is that if <cf/import keep
|
|
filtered/ option is active, filtered routes are counted towards the
|
|
limit and blocked routes are forgotten, as the main purpose of the
|
|
receive limit is to protect routing tables from overflow. Import limit,
|
|
on the contrary, counts accepted routes only and routes blocked by the
|
|
limit are handled like filtered routes. Default: <cf/off/.
|
|
|
|
<tag><label id="proto-export-limit">export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
|
|
Specify an export route limit, works similarly to the <cf>import
|
|
limit</cf> option, but for the routes exported to the protocol. This
|
|
option is experimental, there are some problems in details of its
|
|
behavior -- the number of exported routes can temporarily exceed the
|
|
limit without triggering it during protocol reload, exported routes
|
|
counter ignores route blocking and block action also blocks route
|
|
updates of already accepted routes -- and these details will probably
|
|
change in the future. Default: <cf/off/.
|
|
</descrip>
|
|
|
|
<p>This is a trivial example of RIP configured for IPv6 on all interfaces:
|
|
<code>
|
|
protocol rip ng {
|
|
ipv6;
|
|
interface "*";
|
|
}
|
|
</code>
|
|
|
|
<p>This is a non-trivial example.
|
|
<code>
|
|
protocol rip ng {
|
|
ipv6 {
|
|
table mytable6;
|
|
import filter { ... };
|
|
export filter { ... };
|
|
import limit 50;
|
|
};
|
|
interface "*";
|
|
}
|
|
</code>
|
|
|
|
<p>And this is even more complicated example using templates.
|
|
<code>
|
|
template bgp {
|
|
local 198.51.100.14 as 65000;
|
|
|
|
ipv4 {
|
|
table mytable4;
|
|
import filter { ... };
|
|
export none;
|
|
};
|
|
ipv6 {
|
|
table mytable6;
|
|
import filter { ... };
|
|
export none;
|
|
};
|
|
}
|
|
|
|
protocol bgp from {
|
|
neighbor 198.51.100.130 as 64496;
|
|
|
|
# IPv4 channel is inherited as-is, while IPv6
|
|
# channel is adjusted by export filter option
|
|
ipv6 {
|
|
export filter { ... };
|
|
};
|
|
}
|
|
</code>
|
|
|
|
|
|
<chapt>Remote control
|
|
<label id="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).
|
|
|
|
<p>There is also lightweight variant of BIRD client called <file/birdcl/, which
|
|
does not support command line editing and history and has minimal dependencies.
|
|
This is useful for running BIRD in resource constrained environments, where
|
|
Readline library (required for regular BIRD client) is not available.
|
|
|
|
<p>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><label id="cli-show-status">show status</tag>
|
|
Show router status, that is BIRD version, uptime and time from last
|
|
reconfiguration.
|
|
|
|
<tag><label id="cli-show-interfaces">show interfaces [summary]</tag>
|
|
Show the list of interfaces. For each interface, print its type, state,
|
|
MTU and addresses assigned.
|
|
|
|
<tag><label id="cli-show-protocols">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.
|
|
|
|
<!-- TODO: Move these protocol-specific remote control commands to the protocol sections -->
|
|
<tag><label id="cli-show-ospf-iface">show ospf interface [<m/name/] ["<m/interface/"]</tag>
|
|
Show detailed information about OSPF interfaces.
|
|
|
|
<tag><label id="cli-show-ospf-neighbors">show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
|
|
Show a list of OSPF neighbors and a state of adjacency to them.
|
|
|
|
<tag><label id="cli-show-ospf-state">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><label id="cli-show-ospf-topology">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><label id="cli-show-ospf-lsadb">show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag>
|
|
Show contents of an OSPF LSA database. Options could be used to filter
|
|
entries.
|
|
|
|
<tag><label id="cli-show-rip-interfaces">show rip interfaces [<m/name/] ["<m/interface/"]</tag>
|
|
Show detailed information about RIP interfaces.
|
|
|
|
<tag><label id="cli-show-rip-neighbors">show rip neighbors [<m/name/] ["<m/interface/"]</tag>
|
|
Show a list of RIP neighbors and associated state.
|
|
|
|
<tag><label id="cli-show-static">show static [<m/name/]</tag>
|
|
Show detailed information about static routes.
|
|
|
|
<tag><label id="cli-show-bfd-sessions">show bfd sessions [<m/name/]</tag>
|
|
Show information about BFD sessions.
|
|
|
|
<tag><label id="cli-show-symbols">show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
|
|
Show the list of symbols defined in the configuration (names of
|
|
protocols, routing tables etc.).
|
|
|
|
<tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table (<m/t/ | all)] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [(stats|count)] [<m/options/]</tag>
|
|
Show contents of specified routing tables, 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>The <cf/show route/ command can process one or multiple routing
|
|
tables. The set of selected tables is determined on three levels: First,
|
|
tables can be explicitly selected by <cf/table/ switch, which could be
|
|
used multiple times, all tables are specified by <cf/table all/. Second,
|
|
tables can be implicitly selected by channels or protocols that are
|
|
arguments of several other switches (e.g., <cf/export/, <cf/protocol/).
|
|
Last, the set of default tables is used: <cf/master4/, <cf/master6/ and
|
|
each first table of any other network type.
|
|
|
|
<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/, <cf/preexport/ and <cf/noexport/ switches ask for
|
|
printing of routes that are exported to the specified protocol or
|
|
channel. With <cf/preexport/, the export filter of the channel is
|
|
skipped. With <cf/noexport/, routes rejected by the export filter are
|
|
printed instead. Note that routes not exported for other reasons
|
|
(e.g. secondary routes or routes imported from that protocol) are not
|
|
printed even with <cf/noexport/. These switches also imply that
|
|
associated routing tables are selected instead of default ones.
|
|
|
|
<p>You can also select just routes added by a specific protocol.
|
|
<cf>protocol <m/p/</cf>. This switch also implies that associated
|
|
routing tables are selected instead of default ones.
|
|
|
|
<p>If BIRD is configured to keep filtered routes (see <cf/import keep
|
|
filtered/ option), you can show them instead of routes by using
|
|
<cf/filtered/ switch.
|
|
|
|
<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><label id="cli-mrt-dump">mrt dump table <m/name/|"<m/pattern/" to "<m/filename/" [filter <m/f/|where <m/c/]</tag>
|
|
Dump content of a routing table to a specified file in MRT table dump
|
|
format. See <ref id="mrt" name="MRT protocol"> for details.
|
|
|
|
<tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</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.
|
|
|
|
If <cf/timeout/ option is used, config timer is activated. The new
|
|
configuration could be either confirmed using <cf/configure confirm/
|
|
command, or it will be reverted to the old one when the config timer
|
|
expires. This is useful for cases when reconfiguration breaks current
|
|
routing and a router becomes inaccessible for an administrator. The
|
|
config timeout expiration is equivalent to <cf/configure undo/
|
|
command. The timeout duration could be specified, default is 300 s.
|
|
|
|
<tag><label id="cli-configure-confirm">configure confirm</tag>
|
|
Deactivate the config undo timer and therefore confirm the current
|
|
configuration.
|
|
|
|
<tag><label id="cli-configure-undo">configure undo</tag>
|
|
Undo the last configuration change and smoothly switch back to the
|
|
previous (stored) configuration. If the last configuration change was
|
|
soft, the undo change is also soft. There is only one level of undo, but
|
|
in some specific cases when several reconfiguration requests are given
|
|
immediately in a row and the intermediate ones are skipped then the undo
|
|
also skips them back.
|
|
|
|
<tag><label id="cli-configure-check">configure check ["<m/config file/"]</tag>
|
|
Read and parse given config file, but do not use it. useful for checking
|
|
syntactic and some semantic validity of an config file.
|
|
|
|
<tag><label id="cli-enable-disable-restart">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><label id="cli-reload">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><label id="cli-down">down</tag>
|
|
Shut BIRD down.
|
|
|
|
<tag><label id="cli-graceful-restart">graceful restart</tag>
|
|
Shut BIRD down for graceful restart. See <ref id="graceful-restart"
|
|
name="graceful restart"> section for details.
|
|
|
|
<tag><label id="cli-debug">debug <m/protocol/|<m/pattern/|all all|off|{ states|routes|filters|events|packets [, <m/.../] }</tag>
|
|
Control protocol debugging.
|
|
|
|
<tag><label id="cli-dump">dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
|
|
Dump contents of internal data structures to the debugging output.
|
|
|
|
<tag><label id="cli-echo">echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
|
|
Control echoing of log messages to the command-line output.
|
|
See <ref id="opt-log" name="log option"> for a list of log classes.
|
|
|
|
<tag><label id="cli-eval">eval <m/expr/</tag>
|
|
Evaluate given expression.
|
|
</descrip>
|
|
|
|
|
|
<chapt>Filters
|
|
<label id="filters">
|
|
|
|
<sect>Introduction
|
|
<label id="filters-intro">
|
|
|
|
<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 declares 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;
|
|
int another_variable = 5;
|
|
}
|
|
|
|
function with_parameters (int parameter)
|
|
{
|
|
print parameter;
|
|
}
|
|
</code>
|
|
|
|
<p>Like in C programming language, variables are declared inside function body,
|
|
either at the beginning, or mixed with other statements. Declarations may
|
|
contain initialization. You can also declare variables in nested blocks, such
|
|
variables have scope restricted to such block. There is a deprecated syntax to
|
|
declare variables after the <cf/function/ line, but before the first <cf/{/.
|
|
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 defined in a way similar to functions except they cannot 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 is 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
|
|
<label id="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 oneself
|
|
in the foot).
|
|
|
|
<descrip>
|
|
<tag><label id="type-bool">bool</tag>
|
|
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><label id="type-int">int</tag>
|
|
This is a general integer type. It is an unsigned 32bit type; i.e., you
|
|
can expect it to store values from 0 to 4294967295. Overflows are not
|
|
checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
|
|
|
|
<tag><label id="type-pair">pair</tag>
|
|
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)/).
|
|
|
|
Operators <cf/.asn/ and <cf/.data/ can be used to extract corresponding
|
|
components of a pair: <cf>(<m/asn/, <m/data/)</cf>.
|
|
|
|
<tag><label id="type-quad">quad</tag>
|
|
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><label id="type-string">string</tag>
|
|
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, use standard string
|
|
comparison operations (e.g. <cf/=, !=, <, >, <=, >=/), but
|
|
you can't concatenate two strings. String literals are written as
|
|
<cf/"This is a string constant"/. Additionally matching (<cf/˜,
|
|
!˜/) operators could be used to match a string value against
|
|
a shell pattern (represented also as a string).
|
|
|
|
<tag><label id="type-ip">ip</tag>
|
|
This type can hold a single IP address. The IPv4 addresses are stored as
|
|
IPv4-Mapped IPv6 addresses so one data type for both of them is used.
|
|
Whether the address is IPv4 or not may be checked by <cf>.is_v4</cf>
|
|
which returns a <cf/bool/. 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><label id="type-prefix">prefix</tag>
|
|
This type can hold a network prefix consisting of IP address, prefix
|
|
length and several other values. This is the key in route tables.
|
|
|
|
Prefixes may be of several types, which can be determined by the special
|
|
operator <cf/.type/. The type may be:
|
|
|
|
<cf/NET_IP4/ and <cf/NET_IP6/ prefixes hold an IP prefix. The literals
|
|
are written as <cf><m/ipaddress//<m/pxlen/</cf>. There are two special
|
|
operators on these: <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.len = 16</cf> is true.
|
|
|
|
<cf/NET_IP6_SADR/ nettype holds both destination and source IPv6
|
|
prefix. The literals are written as <cf><m/ipaddress//<m/pxlen/ from
|
|
<m/ipaddress//<m/pxlen/</cf>, where the first part is the destination
|
|
prefix and the second art is the source prefix. They support the same
|
|
operators as IP prefixes, but just for the destination part. They also
|
|
support <cf/.src/ and <cf/.dst/ operators to get respective parts of the
|
|
address as separate <cf/NET_IP6/ values.
|
|
|
|
<cf/NET_VPN4/ and <cf/NET_VPN6/ prefixes hold an IP prefix with VPN
|
|
Route Distinguisher (<rfc id="4364">). They support the same special
|
|
operators as IP prefixes, and also <cf/.rd/ which extracts the Route
|
|
Distinguisher. Their literals are written
|
|
as <cf><m/vpnrd/ <m/ipprefix/</cf>
|
|
|
|
<cf/NET_ROA4/ and <cf/NET_ROA6/ prefixes hold an IP prefix range
|
|
together with an ASN. They support the same special operators as IP
|
|
prefixes, and also <cf/.maxlen/ which extracts maximal prefix length,
|
|
and <cf/.asn/ which extracts the ASN.
|
|
|
|
<cf/NET_FLOW4/ and <cf/NET_FLOW6/ hold an IP prefix together with a
|
|
flowspec rule. Filters currently do not support much flowspec parsing,
|
|
only <cf/.src/ and <cf/.dst/ operators to get source and destination
|
|
parts of the flowspec as separate <cf/NET_IP4/ / <cf/NET_IP6/ values.
|
|
|
|
<cf/NET_MPLS/ holds a single MPLS label and its handling is currently
|
|
not implemented.
|
|
|
|
<tag><label id="type-vpnrd">vpnrd</tag>
|
|
This is a route distinguisher according to <rfc id="4364">. There are
|
|
three kinds of RD's: <cf><m/asn/:<m/32bit int/</cf>, <cf><m/asn4/:<m/16bit int/</cf>
|
|
and <cf><m/IPv4 address/:<m/32bit int/</cf>
|
|
|
|
<tag><label id="type-ec">ec</tag>
|
|
This is a specialized type used to represent BGP extended community
|
|
values. It is essentially a 64bit value, literals of this type are
|
|
usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>, where
|
|
<cf/kind/ is a kind of extended community (e.g. <cf/rt/ / <cf/ro/ for a
|
|
route target / route origin communities), the format and possible values
|
|
of <cf/key/ and <cf/value/ are usually integers, but it depends on the
|
|
used kind. Similarly to pairs, ECs can be constructed using expressions
|
|
for <cf/key/ and <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
|
|
<cf/myas/ is an integer variable).
|
|
|
|
<tag><label id="type-lc">lc</tag>
|
|
This is a specialized type used to represent BGP large community
|
|
values. It is essentially a triplet of 32bit values, where the first
|
|
value is reserved for the AS number of the issuer, while meaning of
|
|
remaining parts is defined by the issuer. Literals of this type are
|
|
written as <cf/(123, 456, 789)/, with any integer values. Similarly to
|
|
pairs, LCs can be constructed using expressions for its parts, (e.g.
|
|
<cf/(myas, 10+20, 3*10)/, where <cf/myas/ is an integer variable).
|
|
|
|
Operators <cf/.asn/, <cf/.data1/, and <cf/.data2/ can be used
|
|
to extract corresponding components of LCs:
|
|
<cf>(<m/asn/, <m/data1/, <m/data2/)</cf>.
|
|
|
|
<tag><label id="type-set">int|pair|quad|ip|prefix|ec|lc|enum set</tag>
|
|
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/*/ and <cf/a..b/ expressions in the first part of a pair, note that
|
|
such expressions are translated to a set of intervals, which may be
|
|
memory intensive. E.g. <cf/(*,4..20)/ is translated to <cf/(0,4..20),
|
|
(1,4..20), (2,4..20), ... (65535, 4..20)/.
|
|
|
|
EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123,
|
|
10..20)/ or <cf/(ro, 123, *)/. Expressions requiring the translation
|
|
(like <cf/(rt, *, 3)/) are not allowed (as they usually have 4B range
|
|
for ASNs).
|
|
|
|
Also LC sets use similar expressions like pair sets. You can use ranges
|
|
and wildcards, but if one field uses that, more specific (later) fields
|
|
must be wildcards. E.g., <cf/(10, 20..30, *)/ or <cf/(10, 20, 30..40)/
|
|
is valid, while <cf/(10, *, 20..30)/ or <cf/(10, 20..30, 40)/ is not
|
|
valid.
|
|
|
|
You can also use expressions for int, pair, EC and LC set values.
|
|
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;
|
|
define myas=64500;
|
|
int set odds;
|
|
pair set ps;
|
|
ec set es;
|
|
|
|
odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
|
|
ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
|
|
es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
|
|
</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/len/+</cf>
|
|
is a shorthand for <cf><m/address//<m/len/{<m/len/,<m/maxlen/}</cf>
|
|
(where <cf><m/maxlen/</cf> is 32 for IPv4 and 128 for IPv6), that means
|
|
network prefix <cf><m/address//<m/len/</cf> and all its subnets.
|
|
<cf><m/address//<m/len/-</cf> is a shorthand for
|
|
<cf><m/address//<m/len/{0,<m/len/}</cf>, that means network prefix
|
|
<cf><m/address//<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>.
|
|
|
|
It is not possible to mix IPv4 and IPv6 prefixes in a prefix set. It is
|
|
currently possible to mix IPv4 and IPv6 addresses in an ip set, but that
|
|
behavior may change between versions without any warning; don't do it
|
|
unless you are more than sure what you are doing. (Really, don't do it.)
|
|
|
|
<tag><label id="type-enum">enum</tag>
|
|
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><label id="type-bgppath">bgppath</tag>
|
|
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/.
|
|
|
|
<cf><m/P/.last_nonaggregated</cf> returns the last ASN in the non-aggregated part of the 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. If the path ends with an AS set, <cf/last_nonaggregated/
|
|
may be used to get last ASN before any AS set.
|
|
|
|
<cf><m/P/.len</cf> returns the length of path <m/P/.
|
|
|
|
<cf><m/P/.empty</cf> makes the path <m/P/ empty.
|
|
|
|
<cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and
|
|
returns the result.
|
|
|
|
<cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN <m/A/ from
|
|
from path <m/P/ and returns the result. <m/A/ may also be an integer
|
|
set, in that case the operator deletes all ASNs from path <m/P/ that are
|
|
also members of set <m/A/.
|
|
|
|
<cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path <m/P/ that are
|
|
not members of integer set <m/A/. I.e., <cf/filter/ do the same as
|
|
<cf/delete/ with inverted set <m/A/.
|
|
|
|
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/). Similarly for <cf/delete/ and <cf/filter/.
|
|
|
|
<tag><label id="type-bgpmask">bgpmask</tag>
|
|
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. There is also
|
|
<cf/+/ operator which matches one or multiple instances of previous
|
|
expression, e.g. <tt>[= 1 2+ 3 =]</tt> matches both path 1 2 3 and path
|
|
1 2 2 2 3, but not 1 3 nor 1 2 4 3. Note that while <cf/*/ and <cf/?/
|
|
are wildcard-style operators, <cf/+/ is regex-style operator.
|
|
|
|
BGP mask expressions can also contain integer expressions enclosed in
|
|
parenthesis and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
|
|
You can also use ranges (e.g. <tt>[= * 3..5 2 100..200 * =]</tt>)
|
|
and sets (e.g. <tt>[= 1 2 [3, 5, 7] * =]</tt>).
|
|
|
|
<tag><label id="type-clist">clist</tag>
|
|
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 special operators on clists:
|
|
|
|
<cf><m/C/.len</cf> returns the length of clist <m/C/.
|
|
|
|
<cf><m/C/.empty</cf> makes the list <m/C/ empty.
|
|
|
|
<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. <m/P/ may also be a clist, in that case all its members are
|
|
added; i.e., it works as clist union.
|
|
|
|
<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/. Moreover, <m/P/ may also be a clist, which works
|
|
analogously; i.e., it works as clist difference.
|
|
|
|
<cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist <m/C/ that are
|
|
not members of pair (or quad) set <m/P/. I.e., <cf/filter/ do the same
|
|
as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which
|
|
works analogously; i.e., it works as clist intersection.
|
|
|
|
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/ and <cf/filter/.
|
|
|
|
<cf><m/C/.min</cf> returns the minimum element of clist <m/C/.
|
|
|
|
<cf><m/C/.max</cf> returns the maximum element of clist <m/C/.
|
|
|
|
Operators <cf/.min/, <cf/.max/ can be used together with <cf/filter/
|
|
to extract the community from the specific subset of communities
|
|
(e.g. localpref or prepend) without the need to check every possible
|
|
value (e.g. <cf/filter(bgp_community, [(23456, 1000..1099)]).min/).
|
|
|
|
<tag><label id="type-eclist">eclist</tag>
|
|
Eclist is a data type used for BGP extended community lists. Eclists
|
|
are very similar to clists, but they are sets of ECs instead of pairs.
|
|
The same operations (like <cf/add/, <cf/delete/ or <cf/˜/ and
|
|
<cf/!˜/ membership operators) can be used to modify or test
|
|
eclists, with ECs instead of pairs as arguments.
|
|
|
|
<tag><label id="type-lclist">lclist</tag>
|
|
Lclist is a data type used for BGP large community lists. Like eclists,
|
|
lclists are very similar to clists, but they are sets of LCs instead of
|
|
pairs. The same operations (like <cf/add/, <cf/delete/ or <cf/˜/
|
|
and <cf/!˜/ membership operators) can be used to modify or test
|
|
lclists, with LCs instead of pairs as arguments.
|
|
</descrip>
|
|
|
|
|
|
<sect>Operators
|
|
<label id="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/˜/,
|
|
<cf/!˜/) for "is (not) 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
|
|
number and bgppath (returning true if the number is in the path) or on bgppath
|
|
and int (number) set (returning true if any ASN from the path is in the set) 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).
|
|
|
|
<p>There is one operator related to ROA infrastructure - <cf/roa_check()/. It
|
|
examines a ROA table and does <rfc id="6483"> route origin validation for a
|
|
given network prefix. The basic usage is <cf>roa_check(<m/table/)</cf>, which
|
|
checks the current route (which should be from BGP to have AS_PATH argument) in
|
|
the specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA,
|
|
ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant
|
|
ROAs but none of them match. There is also an extended variant
|
|
<cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to specify a
|
|
prefix and an ASN as arguments.
|
|
|
|
|
|
<sect>Control structures
|
|
<label id="control-structures">
|
|
|
|
<p>Filters support several control structures: conditions, for loops and case
|
|
switches.
|
|
|
|
<p>Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/commandT/;
|
|
else <m/commandF/;</cf> and you can use <cf>{ <m/command1/; <m/command2/;
|
|
<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, <m/commandT/ is
|
|
executed, otherwise <m/commandF/ is executed.
|
|
|
|
<p>For loops allow to iterate over elements in compound data like BGP paths or
|
|
community lists. The syntax is: <cf>for [ <m/type/ ] <m/variable/ in <m/expr/
|
|
do <m/command/;</cf> and you can also use compound command like in conditions.
|
|
The expression is evaluated to a compound data, then for each element from such
|
|
data the command is executed with the item assigned to the variable. A variable
|
|
may be an existing one (when just name is used) or a locally defined (when type
|
|
and name is used). In both cases, it must have the same type as elements.
|
|
|
|
<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>
|
|
if 1234 = i then printn "."; else {
|
|
print "not 1234";
|
|
print "You need {} around multiple commands";
|
|
}
|
|
|
|
for int asn in bgp_path do {
|
|
printn "ASN: ", asn;
|
|
if asn < 65536 then print " (2B)"; else print " (4B)";
|
|
}
|
|
|
|
case arg1 {
|
|
2: print "two"; print "I can do more commands without {}";
|
|
3 .. 5: print "three to five";
|
|
else: print "something else";
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>Route attributes
|
|
<label id="route-attributes">
|
|
|
|
<p>A filter is implicitly passed a route, and it can access its attributes just
|
|
like it accesses variables. There are common route attributes, protocol-specific
|
|
route attributes and custom route attributes. Most common attributes are
|
|
mandatory (always defined), while remaining are optional. 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 bgppath and *clist types, where
|
|
undefined value is regarded as empty bgppath/*clist for most purposes.
|
|
|
|
Attributes can be defined by just setting them in filters. Custom attributes
|
|
have to be first declared by <ref id="opt-attribute" name="attribute"> global
|
|
option. You can also undefine optional attribute back to non-existence by using
|
|
the <cf>unset( <m/attribute/ )</cf> operator.
|
|
|
|
Common route attributes are:
|
|
|
|
<descrip>
|
|
<tag><label id="rta-net"><m/prefix/ net</tag>
|
|
The network prefix or anything else the route is talking about. The
|
|
primary key of the routing table. Read-only. (See the <ref id="routes"
|
|
name="chapter about routes">.)
|
|
|
|
<tag><label id="rta-scope"><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><label id="rta-preference"><m/int/ preference</tag>
|
|
Preference of the route. Valid values are 0-65535. (See the chapter
|
|
about routing tables.)
|
|
|
|
<tag><label id="rta-from"><m/ip/ from</tag>
|
|
The router which the route has originated from.
|
|
|
|
<tag><label id="rta-gw"><m/ip/ gw</tag>
|
|
Next hop packets routed using this route should be forwarded to.
|
|
|
|
<tag><label id="rta-proto"><m/string/ proto</tag>
|
|
The name of the protocol which the route has been imported from.
|
|
Read-only.
|
|
|
|
<tag><label id="rta-source"><m/enum/ source</tag>
|
|
what protocol has told me about this route. Possible values:
|
|
<cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/,
|
|
<cf/RTS_RIP/, <cf/RTS_OSPF/, <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/,
|
|
<cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/, <cf/RTS_PIPE/, <cf/RTS_BABEL/.
|
|
|
|
<tag><label id="rta-dest"><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_MULTIPATH/ for multipath destinations,
|
|
<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). Can be changed, but only to <cf/RTD_BLACKHOLE/,
|
|
<cf/RTD_UNREACHABLE/ or <cf/RTD_PROHIBIT/.
|
|
|
|
<tag><label id="rta-ifname"><m/string/ ifname</tag>
|
|
Name of the outgoing interface. Sink routes (like blackhole, unreachable
|
|
or prohibit) and multipath routes have no interface associated with
|
|
them, so <cf/ifname/ returns an empty string for such routes. Setting it
|
|
would also change route to a direct one (remove gateway).
|
|
|
|
<tag><label id="rta-ifindex"><m/int/ ifindex</tag>
|
|
Index of the outgoing interface. System wide index of the interface. May
|
|
be used for interface matching, however indexes might change on interface
|
|
creation/removal. Zero is returned for routes with undefined outgoing
|
|
interfaces. Read-only.
|
|
|
|
<tag><label id="rta-weight"><m/int/ weight</tag>
|
|
Multipath weight of route next hops. Valid values are 1-256. Reading
|
|
returns the weight of the first next hop, setting it sets weights of all
|
|
next hops to the specified value. Therefore, this attribute is not much
|
|
useful for manipulating individual next hops of an ECMP route, but can
|
|
be used in BGP multipath setup to set weights of individual routes that
|
|
are merged to one ECMP route during export to the Kernel protocol
|
|
(with active <ref id="krt-merge-paths" name="marge paths"> option).
|
|
|
|
<tag><label id="rta-gw-mpls"><m/int/ gw_mpls</tag>
|
|
Outgoing MPLS label attached to route (i.e., incoming MPLS label on the
|
|
next hop router for this label-switched path). Reading returns the label
|
|
value and setting it sets it to the start of the label stack. Setting
|
|
implicit-NULL label (3) disables the MPLS label stack. Only the first
|
|
next hop and only one label in the label stack supported right now. This
|
|
is experimental option, will be likely changed in the future to handle
|
|
full MPLS label stack.
|
|
|
|
<tag><label id="rta-igp-metric"><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).
|
|
</descrip>
|
|
|
|
<p>Protocol-specific route attributes are described in the corresponding
|
|
protocol sections.
|
|
|
|
|
|
<sect>Other statements
|
|
<label id="other-statements">
|
|
|
|
<p>The following statements are available:
|
|
|
|
<descrip>
|
|
<tag><label id="assignment"><m/variable/ = <m/expr/</tag>
|
|
Set variable (or route attribute) to a given value.
|
|
|
|
<tag><label id="filter-accept-reject">accept|reject [ <m/expr/ ]</tag>
|
|
Accept or reject the route, possibly printing <cf><m>expr</m></cf>.
|
|
|
|
<tag><label id="return">return <m/expr/</tag>
|
|
Return <cf><m>expr</m></cf> from the current function, the function ends
|
|
at this point.
|
|
|
|
<tag><label id="print">print|printn <m/expr/ [<m/, expr.../]</tag>
|
|
Prints given expressions; useful mainly while debugging filters. The
|
|
<cf/printn/ variant does not terminate the line.
|
|
</descrip>
|
|
|
|
|
|
<chapt>Protocols
|
|
<label id="protocols">
|
|
|
|
<sect>Babel
|
|
<label id="babel">
|
|
|
|
<sect1>Introduction
|
|
<label id="babel-intro">
|
|
|
|
<p>The Babel protocol
|
|
(<rfc id="6126">) is a loop-avoiding distance-vector routing protocol that is
|
|
robust and efficient both in ordinary wired networks and in wireless mesh
|
|
networks. Babel is conceptually very simple in its operation and "just works"
|
|
in its default configuration, though some configuration is possible and in some
|
|
cases desirable.
|
|
|
|
<p>The Babel protocol is dual stack; i.e., it can carry both IPv4 and IPv6
|
|
routes over the same IPv6 transport. For sending and receiving Babel packets,
|
|
only a link-local IPv6 address is needed.
|
|
|
|
<p>BIRD implements an extension for IPv6 source-specific routing (SSR or SADR),
|
|
but must be configured accordingly to use it. SADR-enabled Babel router can
|
|
interoperate with non-SADR Babel router, but the later would ignore routes
|
|
with specific (non-zero) source prefix.
|
|
|
|
<sect1>Configuration
|
|
<label id="babel-config">
|
|
|
|
<p>The Babel protocol support both IPv4 and IPv6 channels; both can be
|
|
configured simultaneously. It can also be configured with <ref
|
|
id="ip-sadr-routes" name="IPv6 SADR"> channel instead of regular IPv6
|
|
channel, in such case SADR support is enabled. Babel supports no global
|
|
configuration options apart from those common to all other protocols, but
|
|
supports the following per-interface configuration options:
|
|
|
|
<code>
|
|
protocol babel [<name>] {
|
|
ipv4 { <channel config> };
|
|
ipv6 [sadr] { <channel config> };
|
|
randomize router id <switch>;
|
|
interface <interface pattern> {
|
|
type <wired|wireless>;
|
|
rxcost <number>;
|
|
limit <number>;
|
|
hello interval <time>;
|
|
update interval <time>;
|
|
port <number>;
|
|
tx class|dscp <number>;
|
|
tx priority <number>;
|
|
rx buffer <number>;
|
|
tx length <number>;
|
|
check link <switch>;
|
|
next hop ipv4 <address>;
|
|
next hop ipv6 <address>;
|
|
authentication none|mac [permissive];
|
|
password "<text>";
|
|
password "<text>" {
|
|
id <num>;
|
|
generate from "<date>";
|
|
generate to "<date>";
|
|
accept from "<date>";
|
|
accept to "<date>";
|
|
from "<date>";
|
|
to "<date>";
|
|
algorithm ( hmac sha1 | hmac sha256 | hmac sha384 |
|
|
hmac sha512 | blake2s128 | blake2s256 | blake2b256 | blake2b512 );
|
|
};
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<descrip>
|
|
<tag><label id="babel-channel">ipv4 | ipv6 [sadr] <m/channel config/</tag>
|
|
The supported channels are IPv4, IPv6, and IPv6 SADR.
|
|
|
|
<tag><label id="babel-random-router-id">randomize router id <m/switch/</tag>
|
|
If enabled, Bird will randomize the top 32 bits of its router ID whenever
|
|
the protocol instance starts up. If a Babel node restarts, it loses its
|
|
sequence number, which can cause its routes to be rejected by peers until
|
|
the state is cleared out by other nodes in the network (which can take on
|
|
the order of minutes). Enabling this option causes Bird to pick a random
|
|
router ID every time it starts up, which avoids this problem at the cost
|
|
of not having stable router IDs in the network. Default: no.
|
|
|
|
<tag><label id="babel-type">type wired|wireless </tag>
|
|
This option specifies the interface type: Wired or wireless. On wired
|
|
interfaces a neighbor is considered unreachable after a small number of
|
|
Hello packets are lost, as described by <cf/limit/ option. On wireless
|
|
interfaces the ETX link quality estimation technique is used to compute
|
|
the metrics of routes discovered over this interface. This technique will
|
|
gradually degrade the metric of routes when packets are lost rather than
|
|
the more binary up/down mechanism of wired type links. Default:
|
|
<cf/wired/.
|
|
|
|
<tag><label id="babel-rxcost">rxcost <m/num/</tag>
|
|
This option specifies the nominal RX cost of the interface. The effective
|
|
neighbor costs for route metrics will be computed from this value with a
|
|
mechanism determined by the interface <cf/type/. Note that in contrast to
|
|
other routing protocols like RIP or OSPF, the <cf/rxcost/ specifies the
|
|
cost of RX instead of TX, so it affects primarily neighbors' route
|
|
selection and not local route selection. Default: 96 for wired interfaces,
|
|
256 for wireless.
|
|
|
|
<tag><label id="babel-limit">limit <m/num/</tag>
|
|
BIRD keeps track of received Hello messages from each neighbor to
|
|
establish neighbor reachability. For wired type interfaces, this option
|
|
specifies how many of last 16 hellos have to be correctly received in
|
|
order to neighbor is assumed to be up. The option is ignored on wireless
|
|
type interfaces, where gradual cost degradation is used instead of sharp
|
|
limit. Default: 12.
|
|
|
|
<tag><label id="babel-hello">hello interval <m/time/ s|ms</tag>
|
|
Interval at which periodic Hello messages are sent on this interface,
|
|
with time units. Default: 4 seconds.
|
|
|
|
<tag><label id="babel-update">update interval <m/time/ s|ms</tag>
|
|
Interval at which periodic (full) updates are sent, with time
|
|
units. Default: 4 times the hello interval.
|
|
|
|
<tag><label id="babel-port">port <m/number/</tag>
|
|
This option selects an UDP port to operate on. The default is to operate
|
|
on port 6696 as specified in the Babel RFC.
|
|
|
|
<tag><label id="babel-tx-class">tx class|dscp|priority <m/number/</tag>
|
|
These options specify the ToS/DiffServ/Traffic class/Priority of the
|
|
outgoing Babel packets. See <ref id="proto-tx-class" name="tx class"> common
|
|
option for detailed description.
|
|
|
|
<tag><label id="babel-rx-buffer">rx buffer <m/number/</tag>
|
|
This option specifies the size of buffers used for packet processing.
|
|
The buffer size should be bigger than maximal size of received packets.
|
|
The default value is the interface MTU, and the value will be clamped to a
|
|
minimum of 512 bytes + IP packet overhead.
|
|
|
|
<tag><label id="babel-tx-length">tx length <m/number/</tag>
|
|
This option specifies the maximum length of generated Babel packets. To
|
|
avoid IP fragmentation, it should not exceed the interface MTU value.
|
|
The default value is the interface MTU value, and the value will be
|
|
clamped to a minimum of 512 bytes + IP packet overhead.
|
|
|
|
<tag><label id="babel-check-link">check link <m/switch/</tag>
|
|
If set, the hardware link state (as reported by OS) is taken into
|
|
consideration. When the link disappears (e.g. an ethernet cable is
|
|
unplugged), neighbors are immediately considered unreachable and all
|
|
routes received from them are withdrawn. It is possible that some
|
|
hardware drivers or platforms do not implement this feature. Default:
|
|
yes.
|
|
|
|
<tag><label id="babel-next-hop-ipv4">next hop ipv4 <m/address/</tag>
|
|
Set the next hop address advertised for IPv4 routes advertised on this
|
|
interface. Default: the preferred IPv4 address of the interface.
|
|
|
|
<tag><label id="babel-next-hop-ipv6">next hop ipv6 <m/address/</tag>
|
|
Set the next hop address advertised for IPv6 routes advertised on this
|
|
interface. If not set, the same link-local address that is used as the
|
|
source for Babel packets will be used. In normal operation, it should not
|
|
be necessary to set this option.
|
|
|
|
<tag><label id="babel-authentication">authentication none|mac [permissive]</tag>
|
|
Selects authentication method to be used. <cf/none/ means that packets
|
|
are not authenticated at all, <cf/mac/ means MAC authentication is
|
|
performed as described in <rfc id="8967">. If MAC authentication is
|
|
selected, the <cf/permissive/ suffix can be used to select an operation
|
|
mode where outgoing packets are signed, but incoming packets will be
|
|
accepted even if they fail authentication. This can be useful for
|
|
incremental deployment of MAC authentication across a network. If MAC
|
|
authentication is selected, a key must be specified with the
|
|
<cf/password/ configuration option. Default: none.
|
|
|
|
<tag><label id="babel-password">password "<m/text/"</tag>
|
|
Specifies a password used for authentication. See the <ref id="proto-pass"
|
|
name="password"> common option for a detailed description. The Babel
|
|
protocol will only accept HMAC-based algorithms or one of the Blake
|
|
algorithms, and the length of the supplied password string must match the
|
|
key size used by the selected algorithm.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
<label id="babel-attr">
|
|
|
|
<p>Babel defines just one attribute: the internal babel metric of the route. It
|
|
is exposed as the <cf/babel_metric/ attribute and has range from 1 to infinity
|
|
(65535).
|
|
|
|
<sect1>Example
|
|
<label id="babel-exam">
|
|
|
|
<p><code>
|
|
protocol babel {
|
|
interface "eth*" {
|
|
type wired;
|
|
};
|
|
interface "wlan0", "wlan1" {
|
|
type wireless;
|
|
hello interval 1;
|
|
rxcost 512;
|
|
};
|
|
interface "tap0";
|
|
|
|
# This matches the default of babeld: redistribute all addresses
|
|
# configured on local interfaces, plus re-distribute all routes received
|
|
# from other babel peers.
|
|
|
|
ipv4 {
|
|
export where (source = RTS_DEVICE) || (source = RTS_BABEL);
|
|
};
|
|
ipv6 {
|
|
export where (source = RTS_DEVICE) || (source = RTS_BABEL);
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<sect1>Known issues
|
|
<label id="babel-issues">
|
|
|
|
<p>When retracting a route, Babel generates an unreachable route for a little
|
|
while (according to RFC). The interaction of this behavior with other protocols
|
|
is not well tested and strange things may happen.
|
|
|
|
|
|
<sect>BFD
|
|
<label id="bfd">
|
|
|
|
<sect1>Introduction
|
|
<label id="bfd-intro">
|
|
|
|
<p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it
|
|
is an independent tool providing liveness and failure detection. Routing
|
|
protocols like OSPF and BGP use integrated periodic "hello" messages to monitor
|
|
liveness of neighbors, but detection times of these mechanisms are high (e.g. 40
|
|
seconds by default in OSPF, could be set down to several seconds). BFD offers
|
|
universal, fast and low-overhead mechanism for failure detection, which could be
|
|
attached to any routing protocol in an advisory role.
|
|
|
|
<p>BFD consists of mostly independent BFD sessions. Each session monitors an
|
|
unicast bidirectional path between two BFD-enabled routers. This is done by
|
|
periodically sending control packets in both directions. BFD does not handle
|
|
neighbor discovery, BFD sessions are created on demand by request of other
|
|
protocols (like OSPF or BGP), which supply appropriate information like IP
|
|
addresses and associated interfaces. When a session changes its state, these
|
|
protocols are notified and act accordingly (e.g. break an OSPF adjacency when
|
|
the BFD session went down).
|
|
|
|
<p>BIRD implements basic BFD behavior as defined in <rfc id="5880"> (some
|
|
advanced features like the echo mode or authentication are not implemented), IP
|
|
transport for BFD as defined in <rfc id="5881"> and <rfc id="5883"> and
|
|
interaction with client protocols as defined in <rfc id="5882">.
|
|
|
|
<p>BFD packets are sent with a dynamic source port number. Linux systems use by
|
|
default a bit different dynamic port range than the IANA approved one
|
|
(49152-65535). If you experience problems with compatibility, please adjust
|
|
<cf>/proc/sys/net/ipv4/ip_local_port_range</cf>.
|
|
|
|
<sect1>Configuration
|
|
<label id="bfd-config">
|
|
|
|
<p>BFD configuration consists mainly of multiple definitions of interfaces.
|
|
Most BFD config options are session specific. When a new session is requested
|
|
and dynamically created, it is configured from one of these definitions. For
|
|
sessions to directly connected neighbors, <cf/interface/ definitions are chosen
|
|
based on the interface associated with the session, while <cf/multihop/
|
|
definition is used for multihop sessions. If no definition is relevant, the
|
|
session is just created with the default configuration. Therefore, an empty BFD
|
|
configuration is often sufficient.
|
|
|
|
<p>Note that to use BFD for other protocols like OSPF or BGP, these protocols
|
|
also have to be configured to request BFD sessions, usually by <cf/bfd/ option.
|
|
In BGP case, it is also possible to specify per-peer BFD session options (e.g.
|
|
rx/tx intervals) as a part of the <cf/bfd/ option.
|
|
|
|
<p>A BFD instance not associated with any VRF handles session requests from all
|
|
other protocols, even ones associated with a VRF. Such setup would work for
|
|
single-hop BFD sessions if <cf/net.ipv4.udp_l3mdev_accept/ sysctl is enabled,
|
|
but does not currently work for multihop sessions. Another approach is to
|
|
configure multiple BFD instances, one for each VRF (including the default VRF).
|
|
Each BFD instance associated with a VRF (regular or default) only handles
|
|
session requests from protocols in the same VRF.
|
|
|
|
<p>Some of BFD session options require <m/time/ value, which has to be specified
|
|
with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds
|
|
are allowed as units, practical minimum values are usually in order of tens of
|
|
milliseconds.
|
|
|
|
<code>
|
|
protocol bfd [<name>] {
|
|
accept [ipv4|ipv6] [direct|multihop];
|
|
interface <interface pattern> {
|
|
interval <time>;
|
|
min rx interval <time>;
|
|
min tx interval <time>;
|
|
idle tx interval <time>;
|
|
multiplier <num>;
|
|
passive <switch>;
|
|
authentication none;
|
|
authentication simple;
|
|
authentication [meticulous] keyed md5|sha1;
|
|
password "<text>";
|
|
password "<text>" {
|
|
id <num>;
|
|
generate from "<date>";
|
|
generate to "<date>";
|
|
accept from "<date>";
|
|
accept to "<date>";
|
|
from "<date>";
|
|
to "<date>";
|
|
};
|
|
};
|
|
multihop {
|
|
interval <time>;
|
|
min rx interval <time>;
|
|
min tx interval <time>;
|
|
idle tx interval <time>;
|
|
multiplier <num>;
|
|
passive <switch>;
|
|
};
|
|
neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>];
|
|
}
|
|
</code>
|
|
|
|
<descrip>
|
|
<tag><label id="bfd-accept">accept [ipv4|ipv6] [direct|multihop]</tag>
|
|
A BFD protocol instance accepts (by default) all BFD session requests
|
|
(with regard to VRF restrictions, see above). This option controls
|
|
whether IPv4 / IPv6 and direct / multihop session requests are accepted
|
|
(and which listening sockets are opened). It can be used, for example,
|
|
to configure separate BFD protocol instances for IPv4 and for IPv6
|
|
sessions.
|
|
|
|
<tag><label id="bfd-strict-bind">strict bind <m/switch/</tag>
|
|
Specify whether each BFD interface should use a separate listening
|
|
socket bound to its local address, or just use a shared listening socket
|
|
accepting all addresses. Binding to a specific address could be useful
|
|
in cases like running multiple BIRD instances on a machine, each
|
|
handling a different set of interfaces. Default: disabled.
|
|
|
|
<tag><label id="bfd-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag>
|
|
Interface definitions allow to specify options for sessions associated
|
|
with such interfaces and also may contain interface specific options.
|
|
See <ref id="proto-iface" name="interface"> common option for a detailed
|
|
description of interface patterns. Note that contrary to the behavior of
|
|
<cf/interface/ definitions of other protocols, BFD protocol would accept
|
|
sessions (in default configuration) even on interfaces not covered by
|
|
such definitions.
|
|
|
|
<tag><label id="bfd-multihop">multihop { <m/options/ }</tag>
|
|
Multihop definitions allow to specify options for multihop BFD sessions,
|
|
in the same manner as <cf/interface/ definitions are used for directly
|
|
connected sessions. Currently only one such definition (for all multihop
|
|
sessions) could be used.
|
|
|
|
<tag><label id="bfd-neighbor">neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag>
|
|
BFD sessions are usually created on demand as requested by other
|
|
protocols (like OSPF or BGP). This option allows to explicitly add
|
|
a BFD session to the specified neighbor regardless of such requests.
|
|
|
|
The session is identified by the IP address of the neighbor, with
|
|
optional specification of used interface and local IP. By default
|
|
the neighbor must be directly connected, unless the session is
|
|
configured as multihop. Note that local IP must be specified for
|
|
multihop sessions.
|
|
</descrip>
|
|
|
|
<p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions):
|
|
|
|
<descrip>
|
|
<tag><label id="bfd-interval">interval <m/time/</tag>
|
|
BFD ensures availability of the forwarding path associated with the
|
|
session by periodically sending BFD control packets in both
|
|
directions. The rate of such packets is controlled by two options,
|
|
<cf/min rx interval/ and <cf/min tx interval/ (see below). This option
|
|
is just a shorthand to set both of these options together.
|
|
|
|
<tag><label id="bfd-min-rx-interval">min rx interval <m/time/</tag>
|
|
This option specifies the minimum RX interval, which is announced to the
|
|
neighbor and used there to limit the neighbor's rate of generated BFD
|
|
control packets. Default: 10 ms.
|
|
|
|
<tag><label id="bfd-min-tx-interval">min tx interval <m/time/</tag>
|
|
This option specifies the desired TX interval, which controls the rate
|
|
of generated BFD control packets (together with <cf/min rx interval/
|
|
announced by the neighbor). Note that this value is used only if the BFD
|
|
session is up, otherwise the value of <cf/idle tx interval/ is used
|
|
instead. Default: 100 ms.
|
|
|
|
<tag><label id="bfd-idle-tx-interval">idle tx interval <m/time/</tag>
|
|
In order to limit unnecessary traffic in cases where a neighbor is not
|
|
available or not running BFD, the rate of generated BFD control packets
|
|
is lower when the BFD session is not up. This option specifies the
|
|
desired TX interval in such cases instead of <cf/min tx interval/.
|
|
Default: 1 s.
|
|
|
|
<tag><label id="bfd-multiplier">multiplier <m/num/</tag>
|
|
Failure detection time for BFD sessions is based on established rate of
|
|
BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this
|
|
multiplier, which is essentially (ignoring jitter) a number of missed
|
|
packets after which the session is declared down. Note that rates and
|
|
multipliers could be different in each direction of a BFD session.
|
|
Default: 5.
|
|
|
|
<tag><label id="bfd-passive">passive <m/switch/</tag>
|
|
Generally, both BFD session endpoints try to establish the session by
|
|
sending control packets to the other side. This option allows to enable
|
|
passive mode, which means that the router does not send BFD packets
|
|
until it has received one from the other side. Default: disabled.
|
|
|
|
<tag>authentication none</tag>
|
|
No passwords are sent in BFD packets. This is the default value.
|
|
|
|
<tag>authentication simple</tag>
|
|
Every packet carries 16 bytes of password. Received packets lacking this
|
|
password are ignored. This authentication mechanism is very weak.
|
|
|
|
<tag>authentication [meticulous] keyed md5|sha1</tag>
|
|
An authentication code is appended to each packet. The cryptographic
|
|
algorithm is keyed MD5 or keyed SHA-1. Note that the algorithm is common
|
|
for all keys (on one interface), in contrast to OSPF or RIP, where it
|
|
is a per-key option. Passwords (keys) are not sent open via network.
|
|
|
|
The <cf/meticulous/ variant means that cryptographic sequence numbers
|
|
are increased for each sent packet, while in the basic variant they are
|
|
increased about once per second. Generally, the <cf/meticulous/ variant
|
|
offers better resistance to replay attacks but may require more
|
|
computation.
|
|
|
|
<tag>password "<M>text</M>"</tag>
|
|
Specifies a password used for authentication. See <ref id="proto-pass"
|
|
name="password"> common option for detailed description. Note that
|
|
password option <cf/algorithm/ is not available in BFD protocol. The
|
|
algorithm is selected by <cf/authentication/ option for all passwords.
|
|
|
|
</descrip>
|
|
|
|
<sect1>Example
|
|
<label id="bfd-exam">
|
|
|
|
<p><code>
|
|
protocol bfd {
|
|
interface "eth*" {
|
|
min rx interval 20 ms;
|
|
min tx interval 50 ms;
|
|
idle tx interval 300 ms;
|
|
};
|
|
interface "gre*" {
|
|
interval 200 ms;
|
|
multiplier 10;
|
|
passive;
|
|
};
|
|
multihop {
|
|
interval 200 ms;
|
|
multiplier 10;
|
|
};
|
|
|
|
neighbor 192.168.1.10;
|
|
neighbor 192.168.2.2 dev "eth2";
|
|
neighbor 192.168.10.1 local 192.168.1.1 multihop;
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>BGP
|
|
<label id="bgp">
|
|
|
|
<p>The Border Gateway Protocol is the routing protocol used for backbone level
|
|
routing in the today's Internet. Contrary to other protocols, its convergence
|
|
does not 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.
|
|
|
|
<sect1>Supported standards
|
|
<label id="bgp-standards">
|
|
|
|
<p>
|
|
<itemize>
|
|
<item> <rfc id="4271"> - Border Gateway Protocol 4 (BGP)
|
|
<item> <rfc id="1997"> - BGP Communities Attribute
|
|
<item> <rfc id="2385"> - Protection of BGP Sessions via TCP MD5 Signature
|
|
<item> <rfc id="2545"> - Use of BGP Multiprotocol Extensions for IPv6
|
|
<item> <rfc id="2918"> - Route Refresh Capability
|
|
<item> <rfc id="3107"> - Carrying Label Information in BGP
|
|
<item> <rfc id="4360"> - BGP Extended Communities Attribute
|
|
<item> <rfc id="4364"> - BGP/MPLS IPv4 Virtual Private Networks
|
|
<item> <rfc id="4456"> - BGP Route Reflection
|
|
<item> <rfc id="4486"> - Subcodes for BGP Cease Notification Message
|
|
<item> <rfc id="4659"> - BGP/MPLS IPv6 Virtual Private Networks
|
|
<item> <rfc id="4724"> - Graceful Restart Mechanism for BGP
|
|
<item> <rfc id="4760"> - Multiprotocol extensions for BGP
|
|
<item> <rfc id="4798"> - Connecting IPv6 Islands over IPv4 MPLS
|
|
<item> <rfc id="5065"> - AS confederations for BGP
|
|
<item> <rfc id="5082"> - Generalized TTL Security Mechanism
|
|
<item> <rfc id="5492"> - Capabilities Advertisement with BGP
|
|
<item> <rfc id="5549"> - Advertising IPv4 NLRI with an IPv6 Next Hop
|
|
<item> <rfc id="5575"> - Dissemination of Flow Specification Rules
|
|
<item> <rfc id="5668"> - 4-Octet AS Specific BGP Extended Community
|
|
<item> <rfc id="6286"> - AS-Wide Unique BGP Identifier
|
|
<item> <rfc id="6608"> - Subcodes for BGP Finite State Machine Error
|
|
<item> <rfc id="6793"> - BGP Support for 4-Octet AS Numbers
|
|
<item> <rfc id="7311"> - Accumulated IGP Metric Attribute for BGP
|
|
<item> <rfc id="7313"> - Enhanced Route Refresh Capability for BGP
|
|
<item> <rfc id="7606"> - Revised Error Handling for BGP UPDATE Messages
|
|
<item> <rfc id="7911"> - Advertisement of Multiple Paths in BGP
|
|
<item> <rfc id="7947"> - Internet Exchange BGP Route Server
|
|
<item> <rfc id="8092"> - BGP Large Communities Attribute
|
|
<item> <rfc id="8203"> - BGP Administrative Shutdown Communication
|
|
<item> <rfc id="8212"> - Default EBGP Route Propagation Behavior without Policies
|
|
<item> <rfc id="9117"> - Revised Validation Procedure for BGP Flow Specifications
|
|
<item> <rfc id="9234"> - Route Leak Prevention and Detection Using Roles
|
|
</itemize>
|
|
|
|
<sect1>Route selection rules
|
|
<label id="bgp-route-select-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
|
|
<label id="bgp-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>Protocol configuration
|
|
<label id="bgp-proto-config">
|
|
|
|
<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><label id="bgp-local">local [<m/ip/] [port <m/number/] [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).
|
|
Optional <cf/port/ argument specifies the local BGP port instead of
|
|
standard port 179. The parameter may be used multiple times with
|
|
different sub-options (e.g., both <cf/local 10.0.0.1 as 65000;/ and
|
|
<cf/local 10.0.0.1; local as 65000;/ are valid). This parameter is
|
|
mandatory.
|
|
|
|
<tag><label id="bgp-neighbor">neighbor [<m/ip/ | range <m/prefix/] [port <m/number/] [as <m/number/] [internal|external]</tag>
|
|
Define neighboring router this instance will be talking to and what AS
|
|
it is located in. In case the neighbor is in the same AS as we are, we
|
|
automatically switch to IBGP. Alternatively, it is possible to specify
|
|
just <cf/internal/ or <cf/external/ instead of AS number, in that case
|
|
either local AS number, or any external AS number is accepted.
|
|
Optionally, the remote port may also be specified. Like <cf/local/
|
|
parameter, this parameter may also be used multiple times with different
|
|
sub-options. This parameter is mandatory.
|
|
|
|
It is possible to specify network prefix (with <cf/range/ keyword)
|
|
instead of explicit neighbor IP address. This enables dynamic BGP
|
|
behavior, where the BGP instance listens on BGP port, but new BGP
|
|
instances are spawned for incoming BGP connections (if source address
|
|
matches the network prefix). It is possible to mix regular BGP instances
|
|
with dynamic BGP instances and have multiple dynamic BGP instances with
|
|
different ranges.
|
|
|
|
<tag><label id="bgp-iface">interface <m/string/</tag>
|
|
Define interface we should use for link-local BGP IPv6 sessions.
|
|
Interface can also be specified as a part of <cf/neighbor address/
|
|
(e.g., <cf/neighbor fe80::1234%eth0 as 65000;/). The option may also be
|
|
used for non link-local sessions when it is necessary to explicitly
|
|
specify an interface, but only for direct (not multihop) sessions.
|
|
|
|
<tag><label id="bgp-direct">direct</tag>
|
|
Specify that the neighbor is directly connected. The IP address of the
|
|
neighbor must be from a directly reachable IP range (i.e. associated
|
|
with one of your router's interfaces), otherwise the BGP session
|
|
wouldn't start but it would wait for such interface to appear. The
|
|
alternative is the <cf/multihop/ option. Default: enabled for eBGP.
|
|
|
|
<tag><label id="bgp-multihop">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. The
|
|
alternative is the <cf/direct/ option. For multihop BGP it is
|
|
recommended to explicitly configure the source address to have it
|
|
stable. Optional <cf/number/ argument can be used to specify the number
|
|
of hops (used for TTL). Note that the number of networks (edges) in a
|
|
path is counted; i.e., if two BGP speakers are separated by one router,
|
|
the number of hops is 2. Default: enabled for iBGP.
|
|
|
|
<tag><label id="bgp-source-address">source address <m/ip/</tag>
|
|
Define local address we should use as a source address for the BGP
|
|
session. Default: the address of the local end of the interface our
|
|
neighbor is connected to.
|
|
|
|
<tag><label id="bgp-dynamic-name">dynamic name "<m/text/"</tag>
|
|
Define common prefix of names used for new BGP instances spawned when
|
|
dynamic BGP behavior is active. Actual names also contain numeric
|
|
index to distinguish individual instances. Default: "dynbgp".
|
|
|
|
<tag><label id="bgp-dynamic-name-digits">dynamic name digits <m/number/</tag>
|
|
Define minimum number of digits for index in names of spawned dynamic
|
|
BGP instances. E.g., if set to 2, then the first name would be
|
|
"dynbgp01". Default: 0.
|
|
|
|
<tag><label id="bgp-strict-bind">strict bind <m/switch/</tag>
|
|
Specify whether BGP listening socket should be bound to a specific local
|
|
address (the same as the <cf/source address/) and associated interface,
|
|
or to all addresses. Binding to a specific address could be useful in
|
|
cases like running multiple BIRD instances on a machine, each using its
|
|
IP address. Note that listening sockets bound to a specific address and
|
|
to all addresses collide, therefore either all BGP protocols (of the
|
|
same address family and using the same local port) should have set
|
|
<cf/strict bind/, or none of them. Default: disabled.
|
|
|
|
<tag><label id="bgp-free-bind">free bind <m/switch/</tag>
|
|
Use IP_FREEBIND socket option for the listening socket, which allows
|
|
binding to an IP address not (yet) assigned to an interface. Note that
|
|
all BGP instances that share a listening socket should have the same
|
|
value of the <cf/freebind/ option. Default: disabled.
|
|
|
|
<tag><label id="bgp-check-link">check link <M>switch</M></tag>
|
|
BGP could use hardware link state into consideration. If enabled,
|
|
BIRD tracks the link state of the associated interface and when link
|
|
disappears (e.g. an ethernet cable is unplugged), the BGP session is
|
|
immediately shut down. Note that this option cannot be used with
|
|
multihop BGP. Default: enabled for direct BGP, disabled otherwise.
|
|
|
|
<tag><label id="bgp-bfd">bfd <M>switch</M>|graceful| { <m/options/ }</tag>
|
|
BGP could use BFD protocol as an advisory mechanism for neighbor
|
|
liveness and failure detection. If enabled, BIRD setups a BFD session
|
|
for the BGP neighbor and tracks its liveness by it. This has an
|
|
advantage of an order of magnitude lower detection times in case of
|
|
failure. When a neighbor failure is detected, the BGP session is
|
|
restarted. Optionally, it can be configured (by <cf/graceful/ argument)
|
|
to trigger graceful restart instead of regular restart. It is also
|
|
possible to specify section with per-peer BFD session options instead of
|
|
just switch argument. Most BFD session specific options are allowed here
|
|
with the exception of authentication options. here Note that BFD
|
|
protocol also has to be configured, see <ref id="bfd" name="BFD">
|
|
section for details. Default: disabled.
|
|
|
|
<tag><label id="bgp-ttl-security">ttl security <m/switch/</tag>
|
|
Use GTSM (<rfc id="5082"> - the generalized TTL security mechanism). GTSM
|
|
protects against spoofed packets by ignoring received packets with a
|
|
smaller than expected TTL. To work properly, GTSM have to be enabled on
|
|
both sides of a BGP session. If both <cf/ttl security/ and
|
|
<cf/multihop/ options are enabled, <cf/multihop/ option should specify
|
|
proper hop value to compute expected TTL. Kernel support required:
|
|
Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only.
|
|
Note that full (ICMP protection, for example) <rfc id="5082"> support is
|
|
provided by Linux only. Default: disabled.
|
|
|
|
<tag><label id="bgp-password">password <m/string/</tag>
|
|
Use this password for MD5 authentication of BGP sessions (<rfc id="2385">). When
|
|
used on BSD systems, see also <cf/setkey/ option below. Default: no
|
|
authentication.
|
|
|
|
<tag><label id="bgp-setkey">setkey <m/switch/</tag>
|
|
On BSD systems, keys for TCP MD5 authentication are stored in the global
|
|
SA/SP database, which can be accessed by external utilities (e.g.
|
|
setkey(8)). BIRD configures security associations in the SA/SP database
|
|
automatically based on <cf/password/ options (see above), this option
|
|
allows to disable automatic updates by BIRD when manual configuration by
|
|
external utilities is preferred. Note that automatic SA/SP database
|
|
updates are currently implemented only for FreeBSD. Passwords have to be
|
|
set manually by an external utility on NetBSD and OpenBSD. Default:
|
|
enabled (ignored on non-FreeBSD).
|
|
|
|
<tag><label id="bgp-passive">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><label id="bgp-confederation">confederation <m/number/</tag>
|
|
BGP confederations (<rfc id="5065">) are collections of autonomous
|
|
systems that act as one entity to external systems, represented by one
|
|
confederation identifier (instead of AS numbers). This option allows to
|
|
enable BGP confederation behavior and to specify the local confederation
|
|
identifier. When BGP confederations are used, all BGP speakers that are
|
|
members of the BGP confederation should have the same confederation
|
|
identifier configured. Default: 0 (no confederation).
|
|
|
|
<tag><label id="bgp-confederation-member">confederation member <m/switch/</tag>
|
|
When BGP confederations are used, this option allows to specify whether
|
|
the BGP neighbor is a member of the same confederation as the local BGP
|
|
speaker. The option is unnecessary (and ignored) for IBGP sessions, as
|
|
the same AS number implies the same confederation. Default: no.
|
|
|
|
<tag><label id="bgp-rr-client">rr client</tag>
|
|
Be a route reflector and treat the neighbor as a route reflection
|
|
client. Default: disabled.
|
|
|
|
<tag><label id="bgp-rr-cluster-id">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><label id="bgp-rs-client">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 id="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
|
|
keeps MED attribute). Default: disabled.
|
|
|
|
<tag><label id="bgp-allow-local-pref">allow bgp_local_pref <m/switch/</tag>
|
|
A standard BGP implementation do not send the Local Preference attribute
|
|
to eBGP neighbors and ignore this attribute if received from eBGP
|
|
neighbors, as per <rfc id="4271">. When this option is enabled on an
|
|
eBGP session, this attribute will be sent to and accepted from the peer,
|
|
which is useful for example if you have a setup like in <rfc id="7938">.
|
|
The option does not affect iBGP sessions. Default: off.
|
|
|
|
<tag><label id="bgp-allow-local-as">allow local as [<m/number/]</tag>
|
|
BGP prevents routing loops by rejecting received routes with the local
|
|
AS number in the AS path. This option allows to loose or disable the
|
|
check. Optional <cf/number/ argument can be used to specify the maximum
|
|
number of local ASNs in the AS path that is allowed for received
|
|
routes. When the option is used without the argument, the check is
|
|
completely disabled and you should ensure loop-free behavior by some
|
|
other means. Default: 0 (no local AS number allowed).
|
|
|
|
<tag><label id="bgp-allow-as-sets">allow as sets [<m/switch/]</tag>
|
|
AS path attribute received with BGP routes may contain not only
|
|
sequences of AS numbers, but also sets of AS numbers. These rarely used
|
|
artifacts are results of inter-AS route aggregation. AS sets are
|
|
deprecated (<rfc id="6472">), and likely to be rejected in the future,
|
|
as they complicate security features like RPKI validation. When this
|
|
option is disabled, then received AS paths with AS sets are rejected as
|
|
malformed and corresponding BGP updates are treated as withdraws.
|
|
Default: on.
|
|
|
|
<tag><label id="bgp-enforce-first-as">enforce first as [<m/switch/]</tag>
|
|
Routes received from an EBGP neighbor are generally expected to have the
|
|
first (leftmost) AS number in their AS path equal to the neighbor AS
|
|
number. This is not enforced by default as there are legitimate cases
|
|
where it is not true, e.g. connections to route servers. When this
|
|
option is enabled, routes with non-matching first AS number are rejected
|
|
and corresponding updates are treated as withdraws. The option is valid
|
|
on EBGP sessions only. Default: off.
|
|
|
|
<tag><label id="bgp-enable-route-refresh">enable route refresh <m/switch/</tag>
|
|
After the initial route exchange, BGP protocol uses incremental updates
|
|
to keep BGP speakers synchronized. Sometimes (e.g., if BGP speaker
|
|
changes its import filter, or if there is suspicion of inconsistency) it
|
|
is necessary to do a new complete route exchange. BGP protocol extension
|
|
Route Refresh (<rfc id="2918">) allows BGP speaker to request
|
|
re-advertisement of all routes from its neighbor. BGP protocol
|
|
extension Enhanced Route Refresh (<rfc id="7313">) specifies explicit
|
|
begin and end for such exchanges, therefore the receiver can remove
|
|
stale routes that were not advertised during the exchange. This option
|
|
specifies whether BIRD advertises these capabilities and supports
|
|
related procedures. Note that even when disabled, BIRD can send route
|
|
refresh requests. Default: on.
|
|
|
|
<tag><label id="bgp-graceful-restart">graceful restart <m/switch/|aware</tag>
|
|
When a BGP speaker restarts or crashes, neighbors will discard all
|
|
received paths from the speaker, which disrupts packet forwarding even
|
|
when the forwarding plane of the speaker remains intact. <rfc id="4724">
|
|
specifies an optional graceful restart mechanism to alleviate this
|
|
issue. This option controls the mechanism. It has three states:
|
|
Disabled, when no support is provided. Aware, when the graceful restart
|
|
support is announced and the support for restarting neighbors is
|
|
provided, but no local graceful restart is allowed (i.e. receiving-only
|
|
role). Enabled, when the full graceful restart support is provided
|
|
(i.e. both restarting and receiving role). Restarting role could be also
|
|
configured per-channel. Note that proper support for local graceful
|
|
restart requires also configuration of other protocols. Default: aware.
|
|
|
|
<tag><label id="bgp-graceful-restart-time">graceful restart time <m/number/</tag>
|
|
The restart time is announced in the BGP graceful restart capability
|
|
and specifies how long the neighbor would wait for the BGP session to
|
|
re-establish after a restart before deleting stale routes. Default:
|
|
120 seconds.
|
|
|
|
<tag><label id="bgp-long-lived-graceful-restart">long lived graceful restart <m/switch/|aware</tag>
|
|
The long-lived graceful restart is an extension of the traditional
|
|
<ref id="bgp-graceful-restart" name="BGP graceful restart">, where stale
|
|
routes are kept even after the <ref id="bgp-graceful-restart-time"
|
|
name="restart time"> expires for additional long-lived stale time, but
|
|
they are marked with the LLGR_STALE community, depreferenced, and
|
|
withdrawn from routers not supporting LLGR. Like traditional BGP
|
|
graceful restart, it has three states: disabled, aware (receiving-only),
|
|
and enabled. Note that long-lived graceful restart requires at least
|
|
aware level of traditional BGP graceful restart. Default: aware, unless
|
|
graceful restart is disabled.
|
|
|
|
<tag><label id="bgp-long-lived-stale-time">long lived stale time <m/number/</tag>
|
|
The long-lived stale time is announced in the BGP long-lived graceful
|
|
restart capability and specifies how long the neighbor would keep stale
|
|
routes depreferenced during long-lived graceful restart until either the
|
|
session is re-stablished and synchronized or the stale time expires and
|
|
routes are removed. Default: 3600 seconds.
|
|
|
|
<tag><label id="bgp-interpret-communities">interpret communities <m/switch/</tag>
|
|
<rfc id="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><label id="bgp-enable-as4">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><label id="bgp-enable-extended-messages">enable extended messages <m/switch/</tag>
|
|
The BGP protocol uses maximum message length of 4096 bytes. This option
|
|
provides an extension (<rfc id="8654">) to allow extended messages with
|
|
length up to 65535 bytes. Default: off.
|
|
|
|
<tag><label id="bgp-capabilities">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><label id="bgp-advertise-hostname">advertise hostname <m/switch/</tag>
|
|
Advertise hostname capability along with the hostname. Default: off.
|
|
|
|
<tag><label id="bgp-disable-after-error">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><label id="bgp-disable-after-cease">disable after cease <m/switch/|<m/set-of-flags/</tag>
|
|
When a Cease notification is received, disable the instance
|
|
automatically and wait for an administrator to fix the problem manually.
|
|
When used with <m/switch/ argument, it means handle every Cease subtype
|
|
with the exception of <cf/connection collision/. Default: off.
|
|
|
|
The <m/set-of-flags/ allows to narrow down relevant Cease subtypes. The
|
|
syntax is <cf>{<m/flag/ [, <m/.../] }</cf>, where flags are: <cf/cease/,
|
|
<cf/prefix limit hit/, <cf/administrative shutdown/,
|
|
<cf/peer deconfigured/, <cf/administrative reset/,
|
|
<cf/connection rejected/, <cf/configuration change/,
|
|
<cf/connection collision/, <cf/out of resources/.
|
|
|
|
<tag><label id="bgp-hold-time">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><label id="bgp-startup-hold-time">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><label id="bgp-keepalive-time">keepalive time <m/number/</tag>
|
|
Delay in seconds between sending of two consecutive Keepalive messages.
|
|
Default: One third of the hold time.
|
|
|
|
<tag><label id="bgp-connect-delay-time">connect delay time <m/number/</tag>
|
|
Delay in seconds between protocol startup and the first attempt to
|
|
connect. Default: 5 seconds.
|
|
|
|
<tag><label id="bgp-connect-retry-time">connect retry time <m/number/</tag>
|
|
Time in seconds to wait before retrying a failed attempt to connect.
|
|
Default: 120 seconds.
|
|
|
|
<tag><label id="bgp-error-wait-time">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 not 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><label id="bgp-error-forget-time">error forget time <m/number/</tag>
|
|
Maximum time in seconds between two protocol failures to treat them as a
|
|
error sequence which makes <cf/error wait time/ increase exponentially.
|
|
Default: 300 seconds.
|
|
|
|
<tag><label id="bgp-path-metric">path metric <m/switch/</tag>
|
|
Enable comparison of path lengths when deciding which BGP route is the
|
|
best one. Default: on.
|
|
|
|
<tag><label id="bgp-med-metric">med metric <m/switch/</tag>
|
|
Enable comparison of MED attributes (during best route selection) even
|
|
between routes received from different ASes. This may be useful if all
|
|
MED attributes contain some consistent metric, perhaps enforced in
|
|
import filters of AS boundary routers. If this option is disabled, MED
|
|
attributes are compared only if routes are received from the same AS
|
|
(which is the standard behavior). Default: off.
|
|
|
|
<tag><label id="bgp-deterministic-med">deterministic med <m/switch/</tag>
|
|
BGP route selection algorithm is often viewed as a comparison between
|
|
individual routes (e.g. if a new route appears and is better than the
|
|
current best one, it is chosen as the new best one). But the proper
|
|
route selection, as specified by <rfc id="4271">, cannot be fully
|
|
implemented in that way. The problem is mainly in handling the MED
|
|
attribute. BIRD, by default, uses an simplification based on individual
|
|
route comparison, which in some cases may lead to temporally dependent
|
|
behavior (i.e. the selection is dependent on the order in which routes
|
|
appeared). This option enables a different (and slower) algorithm
|
|
implementing proper <rfc id="4271"> route selection, which is
|
|
deterministic. Alternative way how to get deterministic behavior is to
|
|
use <cf/med metric/ option. This option is incompatible with <ref
|
|
id="dsc-table-sorted" name="sorted tables">. Default: off.
|
|
|
|
<tag><label id="bgp-igp-metric">igp metric <m/switch/</tag>
|
|
Enable comparison of internal distances to boundary routers during best
|
|
route selection. Default: on.
|
|
|
|
<tag><label id="bgp-prefer-older">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 id="5004">. Default: off.
|
|
|
|
<tag><label id="bgp-default-med">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><label id="bgp-default-local-pref">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).
|
|
|
|
<tag><label id="bgp-local-role">local role <m/role-name/</tag>
|
|
BGP roles are a mechanism for route leak prevention and automatic route
|
|
filtering based on common BGP topology relationships. They are defined
|
|
in <rfc id="9234">. Instead of manually configuring filters and
|
|
communities, automatic filtering is done with the help of the OTC
|
|
attribute - a flag for routes that should be sent only to customers.
|
|
The same attribute is also used to automatically detect and filter route
|
|
leaks created by third parties.
|
|
|
|
This option is valid for EBGP sessions, but it is not recommended to be
|
|
used within AS confederations (which would require manual filtering of
|
|
<cf/bgp_otc/ attribute on confederation boundaries).
|
|
|
|
Possible <cf><m/role-name/</cf> values are: <cf/provider/,
|
|
<cf/rs_server/, <cf/rs_client/, <cf/customer/ and <cf/peer/.
|
|
Default: No local role assigned.
|
|
|
|
<tag><label id="bgp-require-roles">require roles <m/switch/</tag>
|
|
If this option is set, the BGP roles must be defined on both sides,
|
|
otherwise the session will not be established. This behavior is defined
|
|
in <rfc id="9234"> as "strict mode" and is used to enforce corresponding
|
|
configuration at your conterpart side. Default: disabled.
|
|
</descrip>
|
|
|
|
<sect1>Channel configuration
|
|
<label id="bgp-channel-config">
|
|
|
|
<p>BGP supports several AFIs and SAFIs over one connection. Every AFI/SAFI
|
|
announced to the peer corresponds to one channel. The table of supported AFI/SAFIs
|
|
together with their appropriate channels follows.
|
|
|
|
<table loc="h">
|
|
<tabular ca="l|l|l|r|r">
|
|
<bf/Channel name/ | <bf/Table nettype/ | <bf/IGP table allowed/ | <bf/AFI/ | <bf/SAFI/
|
|
@<hline>
|
|
<cf/ipv4/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 1
|
|
@ <cf/ipv6/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 1
|
|
@ <cf/ipv4 multicast/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 2
|
|
@ <cf/ipv6 multicast/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 2
|
|
@ <cf/ipv4 mpls/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 4
|
|
@ <cf/ipv6 mpls/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 4
|
|
@ <cf/vpn4 mpls/ | <cf/vpn4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 128
|
|
@ <cf/vpn6 mpls/ | <cf/vpn6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 128
|
|
@ <cf/vpn4 multicast/ | <cf/vpn4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 129
|
|
@ <cf/vpn6 multicast/ | <cf/vpn6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 129
|
|
@ <cf/flow4/ | <cf/flow4/ | --- | 1 | 133
|
|
@ <cf/flow6/ | <cf/flow6/ | --- | 2 | 133
|
|
</tabular>
|
|
</table>
|
|
|
|
<p>Due to <rfc id="8212">, external BGP protocol requires explicit configuration
|
|
of import and export policies (in contrast to other protocols, where default
|
|
policies of <cf/import all/ and <cf/export none/ are used in absence of explicit
|
|
configuration). Note that blanket policies like <cf/all/ or <cf/none/ can still
|
|
be used in explicit configuration.
|
|
|
|
<p>BGP channels have additional config options (together with the common ones):
|
|
|
|
<descrip>
|
|
<tag><label id="bgp-mandatory">mandatory <m/switch/</tag>
|
|
When local and neighbor sets of configured AFI/SAFI pairs differ,
|
|
capability negotiation ensures that a common subset is used. For
|
|
mandatory channels their associated AFI/SAFI must be negotiated
|
|
(i.e., also announced by the neighbor), otherwise BGP session
|
|
negotiation fails with <it/'Required capability missing'/ error.
|
|
Regardless, at least one AFI/SAFI must be negotiated in order to BGP
|
|
session be successfully established. Default: off.
|
|
|
|
<tag><label id="bgp-next-hop-keep">next hop keep <m/switch/|ibgp|ebgp</tag>
|
|
Do not modify the Next Hop attribute and advertise the current one
|
|
unchanged even in cases where our own local address should be used
|
|
instead. This is necessary when the BGP speaker does not forward network
|
|
traffic (route servers and some route reflectors) and also can be useful
|
|
in some other cases (e.g. multihop EBGP sessions). Can be enabled for
|
|
all routes, or just for routes received from IBGP / EBGP neighbors.
|
|
Default: disabled for regular BGP, enabled for route servers,
|
|
<cf/ibgp/ for route reflectors.
|
|
|
|
<tag><label id="bgp-next-hop-self">next hop self <m/switch/|ibgp|ebgp</tag>
|
|
Always advertise our own local address as a next hop, even in cases
|
|
where the current Next Hop attribute should be used unchanged. This is
|
|
sometimes used for routes propagated from EBGP to IBGP when IGP routing
|
|
does not cover inter-AS links, therefore IP addreses of EBGP neighbors
|
|
are not resolvable through IGP. Can be enabled for all routes, or just
|
|
for routes received from IBGP / EBGP neighbors. Default: disabled.
|
|
|
|
<tag><label id="bgp-next-hop-address">next hop address <m/ip/</tag>
|
|
Specify which address to use when our own local address should be
|
|
announced in the Next Hop attribute. Default: the source address of the
|
|
BGP session (if acceptable), or the preferred address of an associated
|
|
interface.
|
|
|
|
<tag><label id="bgp-gateway">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 and must be directly reachable. Recursive mode
|
|
means that the gateway is computed by an IGP routing table lookup for
|
|
the IP address from <cf/bgp_next_hop/. Note that there is just one level
|
|
of indirection in recursive mode - the route obtained by the lookup must
|
|
not be recursive itself, to prevent mutually recursive routes.
|
|
|
|
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. Recursive mode is
|
|
incompatible with <ref id="dsc-table-sorted" name="sorted tables">. Default:
|
|
<cf/direct/ for direct sessions, <cf/recursive/ for multihop sessions.
|
|
|
|
<tag><label id="bgp-igp-table">igp table <m/name/</tag>
|
|
Specifies a table that is used as an IGP routing table. The type of this
|
|
table must be as allowed in the table above. This option is allowed once
|
|
for every allowed table type. Default: the same as the main table
|
|
the channel is connected to (if eligible).
|
|
|
|
<tag><label id="bgp-import-table">import table <m/switch/</tag>
|
|
A BGP import table contains all received routes from given BGP neighbor,
|
|
before application of import filters. It is also called <em/Adj-RIB-In/
|
|
in BGP terminology. BIRD BGP by default operates without import tables,
|
|
in which case received routes are just processed by import filters,
|
|
accepted ones are stored in the master table, and the rest is forgotten.
|
|
Enabling <cf/import table/ allows to store unprocessed routes, which can
|
|
be examined later by <cf/show route/, and can be used to reconfigure
|
|
import filters without full route refresh. Default: off.
|
|
|
|
<tag><label id="bgp-export-table">export table <m/switch/</tag>
|
|
A BGP export table contains all routes sent to given BGP neighbor, after
|
|
application of export filters. It is also called <em/Adj-RIB-Out/ in BGP
|
|
terminology. BIRD BGP by default operates without export tables, in
|
|
which case routes from master table are just processed by export filters
|
|
and then announced by BGP. Enabling <cf/export table/ allows to store
|
|
routes after export filter processing, so they can be examined later by
|
|
<cf/show route/, and can be used to eliminate unnecessary updates or
|
|
withdraws. Default: off.
|
|
|
|
<tag><label id="bgp-secondary">secondary <m/switch/</tag>
|
|
Usually, if an export filter rejects a selected route, no other route is
|
|
propagated for that network. This option allows to try the next route in
|
|
order until one that is accepted is found or all routes for that network
|
|
are rejected. This can be used for route servers that need to propagate
|
|
different tables to each client but do not want to have these tables
|
|
explicitly (to conserve memory). This option requires that the connected
|
|
routing table is <ref id="dsc-table-sorted" name="sorted">. Default: off.
|
|
|
|
<tag><label id="bgp-validate">validate <m/switch/</tag>
|
|
Apply flowspec validation procedure as described in <rfc id="8955">
|
|
section 6 and <rfc id="9117">. The Validation procedure enforces that
|
|
only routers in the forwarding path for a network can originate flowspec
|
|
rules for that network. The validation procedure should be used for EBGP
|
|
to prevent injection of malicious flowspec rules from outside, but it
|
|
should also be used for IBGP to ensure that selected flowspec rules are
|
|
consistent with selected IP routes. The validation procedure uses an IP
|
|
routing table (<ref id="bgp-base-table" name="base table">, see below)
|
|
against which flowspec rules are validated. This option is limited to
|
|
flowspec channels. Default: off (for compatibility reasons).
|
|
|
|
Note that currently the flowspec validation does not work reliably
|
|
together with <ref id="bgp-import-table" name="import table"> option
|
|
enabled on flowspec channels.
|
|
|
|
<tag><label id="bgp-base-table">base table <m/name/</tag>
|
|
Specifies an IP table used for the flowspec validation procedure. The
|
|
table must have enabled <cf/trie/ option, otherwise the validation
|
|
procedure would not work. The type of the table must be <cf/ipv4/ for
|
|
<cf/flow4/ channels and <cf/ipv6/ for <cf/flow6/ channels. This option
|
|
is limited to flowspec channels. Default: the main table of the
|
|
<cf/ipv4/ / <cf/ipv6/ channel of the same BGP instance, or the
|
|
<cf/master4/ / <cf/master6/ table if there is no such channel.
|
|
|
|
<tag><label id="bgp-extended-next-hop">extended next hop <m/switch/</tag>
|
|
BGP expects that announced next hops have the same address family as
|
|
associated network prefixes. This option provides an extension to use
|
|
IPv4 next hops with IPv6 prefixes and vice versa. For IPv4 / VPNv4
|
|
channels, the behavior is controlled by the Extended Next Hop Encoding
|
|
capability, as described in <rfc id="5549">. For IPv6 / VPNv6 channels,
|
|
just IPv4-mapped IPv6 addresses are used, as described in
|
|
<rfc id="4798"> and <rfc id="4659">. Default: off.
|
|
|
|
<tag><label id="bgp-add-paths">add paths <m/switch/|rx|tx</tag>
|
|
Standard BGP can propagate only one path (route) per destination network
|
|
(usually the selected one). This option controls the add-path protocol
|
|
extension, which allows to advertise any number of paths to a
|
|
destination. Note that to be active, add-path has to be enabled on both
|
|
sides of the BGP session, but it could be enabled separately for RX and
|
|
TX direction. When active, all available routes accepted by the export
|
|
filter are advertised to the neighbor. Default: off.
|
|
|
|
<tag><label id="bgp-aigp">aigp <m/switch/|originate</tag>
|
|
The BGP protocol does not use a common metric like other routing
|
|
protocols, instead it uses a set of criteria for route selection
|
|
consisting both overall AS path length and a distance to the nearest AS
|
|
boundary router. Assuming that metrics of different autonomous systems
|
|
are incomparable, once a route is propagated from an AS to a next one,
|
|
the distance in the old AS does not matter.
|
|
|
|
The AIGP extension (<rfc id="7311">) allows to propagate accumulated
|
|
IGP metric (in the AIGP attribute) through both IBGP and EBGP links,
|
|
computing total distance through multiple autonomous systems (assuming
|
|
they use comparable IGP metric). The total AIGP metric is compared in
|
|
the route selection process just after Local Preference comparison (and
|
|
before AS path length comparison).
|
|
|
|
This option controls whether AIGP attribute propagation is allowed on
|
|
the session. Optionally, it can be set to <cf/originate/, which not only
|
|
allows AIGP attribute propagation, but also new AIGP attributes are
|
|
automatically attached to non-BGP routes with valid IGP metric (e.g.
|
|
<cf/ospf_metric1/) as they are exported to the BGP session. Default:
|
|
enabled for IBGP (and intra-confederation EBGP), disabled for regular
|
|
EBGP.
|
|
|
|
<tag><label id="bgp-cost">cost <m/number/</tag>
|
|
When BGP <ref id="bgp-gateway" name="gateway mode"> is <cf/recursive/
|
|
(mainly multihop IBGP sessions), then the distance to BGP next hop is
|
|
based on underlying IGP metric. This option specifies the distance to
|
|
BGP next hop for BGP sessions in direct gateway mode (mainly direct
|
|
EBGP sessions).
|
|
|
|
<tag><label id="bgp-graceful-restart-c">graceful restart <m/switch/</tag>
|
|
Although BGP graceful restart is configured mainly by protocol-wide
|
|
<ref id="bgp-graceful-restart" name="options">, it is possible to
|
|
configure restarting role per AFI/SAFI pair by this channel option.
|
|
The option is ignored if graceful restart is disabled by protocol-wide
|
|
option. Default: off in aware mode, on in full mode.
|
|
|
|
<tag><label id="bgp-long-lived-graceful-restart-c">long lived graceful restart <m/switch/</tag>
|
|
BGP long-lived graceful restart is configured mainly by protocol-wide
|
|
<ref id="bgp-long-lived-graceful-restart" name="options">, but the
|
|
restarting role can be set per AFI/SAFI pair by this channel option.
|
|
The option is ignored if long-lived graceful restart is disabled by
|
|
protocol-wide option. Default: off in aware mode, on in full mode.
|
|
|
|
<tag><label id="bgp-long-lived-stale-time-c">long lived stale time <m/number/</tag>
|
|
Like previous graceful restart channel options, this option allows to
|
|
set <ref id="bgp-long-lived-stale-time" name="long lived stale time">
|
|
per AFI/SAFI pair instead of per protocol. Default: set by protocol-wide
|
|
option.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
<label id="bgp-attr">
|
|
|
|
<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><label id="rta-bgp-path">bgppath 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><label id="rta-bgp-local-pref">int 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><label id="rta-bgp-med">int bgp_med [O]</tag>
|
|
The Multiple Exit Discriminator of the route is an optional attribute
|
|
which is used on external (inter-AS) links to convey to an adjacent AS
|
|
the optimal entry point into the local AS. The received attribute is
|
|
also propagated over internal BGP links. The attribute value is zeroed
|
|
when a route is exported to an external 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 an
|
|
external BGP instance. See <rfc id="4451"> for further discussion of
|
|
BGP MED attribute.
|
|
|
|
<tag><label id="rta-bgp-origin">enum 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><label id="rta-bgp-next-hop">ip 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><label id="rta-bgp-atomic-aggr">void 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.
|
|
|
|
<tag><label id="rta-bgp-aggregator">void bgp_aggregator [O]</tag>
|
|
This is an optional attribute specifying AS number and IP address of the
|
|
BGP router that created the route by aggregating multiple BGP routes.
|
|
Currently, the attribute is not accessible from filters.
|
|
|
|
<tag><label id="rta-bgp-community">clist 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><label id="rta-bgp-ext-community">eclist bgp_ext_community [O]</tag>
|
|
List of extended community values associated with the route. Extended
|
|
communities have similar usage as plain communities, but they have an
|
|
extended range (to allow 4B ASNs) and a nontrivial structure with a type
|
|
field. Individual community values are represented using an <cf/ec/ data
|
|
type inside the filters.
|
|
|
|
<tag><label id="rta-bgp-large-community">lclist bgp_large_community [O]</tag>
|
|
List of large community values associated with the route. Large BGP
|
|
communities is another variant of communities, but contrary to extended
|
|
communities they behave very much the same way as regular communities,
|
|
just larger -- they are uniform untyped triplets of 32bit numbers.
|
|
Individual community values are represented using an <cf/lc/ data type
|
|
inside the filters.
|
|
|
|
<tag><label id="rta-bgp-originator-id">quad bgp_originator_id [I, 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><label id="rta-bgp-cluster-list">clist bgp_cluster_list [I, O]</tag>
|
|
This attribute contains a list of cluster IDs of route reflectors. Each
|
|
route reflector prepends its cluster ID when reflecting the route.
|
|
|
|
<tag><label id="rta-bgp-aigp">void bgp_aigp [O]</tag>
|
|
This attribute contains accumulated IGP metric, which is a total
|
|
distance to the destination through multiple autonomous systems.
|
|
Currently, the attribute is not accessible from filters.
|
|
|
|
<tag><label id="bgp-otc">int bgp_otc [O]</tag>
|
|
This attribute is defined in <rfc id="9234">. OTC is a flag that marks
|
|
routes that should be sent only to customers. If <ref id="bgp-role"
|
|
name="local Role"> is configured it set automatically.
|
|
</descrip>
|
|
|
|
<sect1>Example
|
|
<label id="bgp-exam">
|
|
|
|
<p><code>
|
|
protocol bgp {
|
|
local 198.51.100.14 as 65000; # Use a private AS number
|
|
neighbor 198.51.100.130 as 64496; # Our neighbor ...
|
|
multihop; # ... which is connected indirectly
|
|
ipv4 {
|
|
export filter { # We use non-trivial export rules
|
|
if source = RTS_STATIC then { # Export only static routes
|
|
# Assign our community
|
|
bgp_community.add((65000,64501));
|
|
# Artificially increase path length
|
|
# by advertising local AS number twice
|
|
if bgp_path ~ [= 65000 =] then
|
|
bgp_path.prepend(65000);
|
|
accept;
|
|
}
|
|
reject;
|
|
};
|
|
import all;
|
|
next hop self; # advertise this router as next hop
|
|
igp table myigptable4; # IGP table for routes with IPv4 nexthops
|
|
igp table myigptable6; # IGP table for routes with IPv6 nexthops
|
|
};
|
|
ipv6 {
|
|
export filter mylargefilter; # We use a named filter
|
|
import all;
|
|
missing lladdr self;
|
|
igp table myigptable4; # IGP table for routes with IPv4 nexthops
|
|
igp table myigptable6; # IGP table for routes with IPv6 nexthops
|
|
};
|
|
ipv4 multicast {
|
|
import all;
|
|
export filter someotherfilter;
|
|
table mymulticasttable4; # Another IPv4 table, dedicated for multicast
|
|
igp table myigptable4;
|
|
};
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>Device
|
|
<label id="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. This protocol supports no channel.
|
|
|
|
<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
|
|
<label id="device-config">
|
|
|
|
<p><descrip>
|
|
<tag><label id="device-scan-time">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><label id="device-iface">interface <m/pattern/ [, <m/.../]</tag>
|
|
By default, the Device protocol handles all interfaces without any
|
|
configuration. Interface definitions allow to specify optional
|
|
parameters for specific interfaces. See <ref id="proto-iface"
|
|
name="interface"> common option for detailed description. Currently only
|
|
one interface option is available:
|
|
|
|
<tag><label id="device-preferred">preferred <m/ip/</tag>
|
|
If a network interface has more than one IP address, BIRD chooses one of
|
|
them as a preferred one. Preferred IP address is used as source address
|
|
for packets or announced next hop by routing protocols. Precisely, BIRD
|
|
chooses one preferred IPv4 address, one preferred IPv6 address and one
|
|
preferred link-local IPv6 address. By default, BIRD chooses the first
|
|
found IP address as the preferred one.
|
|
|
|
This option allows to specify which IP address should be preferred. May
|
|
be used multiple times for different address classes (IPv4, IPv6, IPv6
|
|
link-local). 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
|
|
interface "eth0" {
|
|
preferred 192.168.1.1;
|
|
preferred 2001:db8:1:10::1;
|
|
};
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>Direct
|
|
<label id="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. The Direct protocol supports both IPv4 and IPv6
|
|
channels; both can be configured simultaneously. It can also be configured with
|
|
<ref id="ip-sadr-routes" name="IPv6 SADR"> channel instead of regular IPv6
|
|
channel in order to be used together with SADR-enabled Babel 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. But the
|
|
Direct protocol is necessary for distance-vector protocols like RIP or Babel to
|
|
announce local networks.
|
|
|
|
<p>There are just few configuration options for the Direct protocol:
|
|
|
|
<p><descrip>
|
|
<tag><label id="direct-iface">interface <m/pattern/ [, <m/.../]</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 or addresses (e.g. 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. See <ref id="proto-iface" name="interface">
|
|
common option for detailed description. The Direct protocol uses
|
|
extended interface clauses.
|
|
|
|
<tag><label id="direct-check-link">check link <m/switch/</tag>
|
|
If enabled, a hardware link state (reported by OS) is taken into
|
|
consideration. Routes for directly connected networks are generated only
|
|
if link up is reported and they are withdrawn when link disappears
|
|
(e.g., an ethernet cable is unplugged). Default value is no.
|
|
</descrip>
|
|
|
|
<p>Direct device routes don't contain any specific attributes.
|
|
|
|
<p>Example config might look like this:
|
|
|
|
<p><code>
|
|
protocol direct {
|
|
ipv4;
|
|
ipv6;
|
|
interface "-arc*", "*"; # Exclude the ARCnets
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>Kernel
|
|
<label id="krt">
|
|
|
|
<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>Note that routes created by OS kernel itself, namely direct routes
|
|
representing IP subnets of associated interfaces, are not imported even with
|
|
<cf/learn/ enabled. You can use <ref id="direct" name="Direct protocol"> to
|
|
generate these direct routes.
|
|
|
|
<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), 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.
|
|
|
|
<p>Because the kernel protocol is partially integrated with the connected
|
|
routing table, there are two limitations - it is not possible to connect more
|
|
kernel protocols to the same routing table and changing route destination
|
|
(gateway) in an export filter of a kernel protocol does not work. Both
|
|
limitations can be overcome using another routing table and the pipe protocol.
|
|
|
|
<p>The Kernel protocol supports both IPv4 and IPv6 channels; only one channel
|
|
can be configured in each protocol instance. On Linux, it also supports <ref
|
|
id="ip-sadr-routes" name="IPv6 SADR"> and <ref id="mpls-routes" name="MPLS">
|
|
channels.
|
|
|
|
<sect1>Configuration
|
|
<label id="krt-config">
|
|
|
|
<p><descrip>
|
|
<tag><label id="krt-persist">persist <m/switch/</tag>
|
|
Tell BIRD to leave all its routes in the routing tables when it exits
|
|
(instead of cleaning them up).
|
|
|
|
<tag><label id="krt-scan-time">scan time <m/number/</tag>
|
|
Time in seconds between two consecutive scans of the kernel routing
|
|
table.
|
|
|
|
<tag><label id="krt-learn">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><label id="krt-kernel-table">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.
|
|
|
|
<tag><label id="krt-metric">metric <m/number/</tag> (Linux)
|
|
Use specified value as a kernel metric (priority) for all routes sent to
|
|
the kernel. When multiple routes for the same network are in the kernel
|
|
routing table, the Linux kernel chooses one with lower metric. Also,
|
|
routes with different metrics do not clash with each other, therefore
|
|
using dedicated metric value is a reliable way to avoid overwriting
|
|
routes from other sources (e.g. kernel device routes). Metric 0 has a
|
|
special meaning of undefined metric, in which either OS default is used,
|
|
or per-route metric can be set using <cf/krt_metric/ attribute. Default:
|
|
32.
|
|
|
|
<tag><label id="krt-graceful-restart">graceful restart <m/switch/</tag>
|
|
Participate in graceful restart recovery. If this option is enabled and
|
|
a graceful restart recovery is active, the Kernel protocol will defer
|
|
synchronization of routing tables until the end of the recovery. Note
|
|
that import of kernel routes to BIRD is not affected.
|
|
|
|
<tag><label id="krt-merge-paths">merge paths <M>switch</M> [limit <M>number</M>]</tag>
|
|
Usually, only best routes are exported to the kernel protocol. With path
|
|
merging enabled, both best routes and equivalent non-best routes are
|
|
merged during export to generate one ECMP (equal-cost multipath) route
|
|
for each network. This is useful e.g. for BGP multipath. Note that best
|
|
routes are still pivotal for route export (responsible for most
|
|
properties of resulting ECMP routes), while exported non-best routes are
|
|
responsible just for additional multipath next hops. This option also
|
|
allows to specify a limit on maximal number of nexthops in one route. By
|
|
default, multipath merging is disabled. If enabled, default value of the
|
|
limit is 16.
|
|
|
|
<tag><label id="krt-netlink-rx-buffer">netlink rx buffer <m/number/</tag> (Linux)
|
|
Set kernel receive buffer size (in bytes) for the netlink socket. The default
|
|
value is OS-dependent (from the <file>/proc/sys/net/core/rmem_default</file>
|
|
file), If you get some "Kernel dropped some netlink message ..." warnings,
|
|
you may increase this value.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
<label id="krt-attr">
|
|
|
|
<p>The Kernel protocol defines several attributes. These attributes are
|
|
translated to appropriate system (and OS-specific) route attributes. We support
|
|
these attributes:
|
|
|
|
<descrip>
|
|
<tag><label id="rta-krt-source">int krt_source</tag>
|
|
The original source of the imported kernel route. The value is
|
|
system-dependent. On Linux, it is a value of the protocol field of the
|
|
route. See /etc/iproute2/rt_protos for common values. On BSD, it is
|
|
based on STATIC and PROTOx flags. The attribute is read-only.
|
|
|
|
<tag><label id="rta-krt-metric">int krt_metric</tag> (Linux)
|
|
The kernel metric of the route. When multiple same routes are in a
|
|
kernel routing table, the Linux kernel chooses one with lower metric.
|
|
Note that preferred way to set kernel metric is to use protocol option
|
|
<cf/metric/, unless per-route metric values are needed.
|
|
|
|
<tag><label id="rta-krt-prefsrc">ip krt_prefsrc</tag> (Linux)
|
|
The preferred source address. Used in source address selection for
|
|
outgoing packets. Has to be one of the IP addresses of the router.
|
|
|
|
<tag><label id="rta-krt-realm">int krt_realm</tag> (Linux)
|
|
The realm of the route. Can be used for traffic classification.
|
|
|
|
<tag><label id="rta-krt-scope">int krt_scope</tag> (Linux IPv4)
|
|
The scope of the route. Valid values are 0-254, although Linux kernel
|
|
may reject some values depending on route type and nexthop. It is
|
|
supposed to represent `indirectness' of the route, where nexthops of
|
|
routes are resolved through routes with a higher scope, but in current
|
|
kernels anything below <it/link/ (253) is treated as <it/global/ (0).
|
|
When not present, global scope is implied for all routes except device
|
|
routes, where link scope is used by default.
|
|
</descrip>
|
|
|
|
<p>In Linux, there is also a plenty of obscure route attributes mostly focused
|
|
on tuning TCP performance of local connections. BIRD supports most of these
|
|
attributes, see Linux or iproute2 documentation for their meaning. Attributes
|
|
<cf/krt_lock_*/ and <cf/krt_feature_*/ have type bool, others have type int.
|
|
Supported attributes are:
|
|
|
|
<cf/krt_mtu/, <cf/krt_lock_mtu/, <cf/krt_window/, <cf/krt_lock_window/,
|
|
<cf/krt_rtt/, <cf/krt_lock_rtt/, <cf/krt_rttvar/, <cf/krt_lock_rttvar/,
|
|
<cf/krt_sstresh/, <cf/krt_lock_sstresh/, <cf/krt_cwnd/, <cf/krt_lock_cwnd/,
|
|
<cf/krt_advmss/, <cf/krt_lock_advmss/, <cf/krt_reordering/, <cf/krt_lock_reordering/,
|
|
<cf/krt_hoplimit/, <cf/krt_lock_hoplimit/, <cf/krt_rto_min/, <cf/krt_lock_rto_min/,
|
|
<cf/krt_initcwnd/, <cf/krt_initrwnd/, <cf/krt_quickack/,
|
|
<cf/krt_feature_ecn/, <cf/krt_feature_allfrag/
|
|
|
|
<sect1>Example
|
|
<label id="krt-exam">
|
|
|
|
<p>A simple configuration can look this way:
|
|
|
|
<p><code>
|
|
protocol kernel {
|
|
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
|
|
ipv4 {
|
|
import all;
|
|
export all;
|
|
};
|
|
}
|
|
|
|
protocol kernel { # Secondary routing table
|
|
kernel table 100;
|
|
ipv4 {
|
|
table auxtable;
|
|
export all;
|
|
};
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>MRT
|
|
<label id="mrt">
|
|
|
|
<sect1>Introduction
|
|
<label id="mrt-intro">
|
|
|
|
<p>The MRT protocol is a component responsible for handling the Multi-Threaded
|
|
Routing Toolkit (MRT) routing information export format, which is mainly used
|
|
for collecting and analyzing of routing information from BGP routers. The MRT
|
|
protocol can be configured to do periodic dumps of routing tables, created MRT
|
|
files can be analyzed later by other tools. Independent MRT table dumps can also
|
|
be requested from BIRD client. There is also a feature to save incoming BGP
|
|
messages in MRT files, but it is controlled by <ref id="proto-mrtdump"
|
|
name="mrtdump"> options independently of MRT protocol, although that might
|
|
change in the future.
|
|
|
|
BIRD implements the main MRT format specification as defined in <rfc id="6396">
|
|
and the ADD_PATH extension (<rfc id="8050">).
|
|
|
|
<sect1>Configuration
|
|
<label id="mrt-config">
|
|
|
|
<p>MRT configuration consists of several statements describing routing table
|
|
dumps. Multiple independent periodic dumps can be done as multiple MRT protocol
|
|
instances. The MRT protocol does not use channels. There are two mandatory
|
|
statements: <cf/filename/ and <cf/period/.
|
|
|
|
The behavior can be modified by following configuration parameters:
|
|
|
|
<descrip>
|
|
<tag><label id="mrt-table">table <m/name/ | "<m/pattern/"</tag>
|
|
Specify a routing table (or a set of routing tables described by a
|
|
wildcard pattern) that are to be dumped by the MRT protocol instance.
|
|
Default: the master table.
|
|
|
|
<tag><label id="mrt-filter">filter { <m/filter commands/ }</tag>
|
|
The MRT protocol allows to specify a filter that is applied to routes as
|
|
they are dumped. Rejected routes are ignored and not saved to the MRT
|
|
dump file. Default: no filter.
|
|
|
|
<tag><label id="mrt-where">where <m/filter expression/</tag>
|
|
An alternative way to specify a filter for the MRT protocol.
|
|
|
|
<tag><label id="mrt-filename">filename "<m/filename/"</tag>
|
|
Specify a filename for MRT dump files. The filename may contain time
|
|
format sequences with <it/strftime(3)/ notation (see <it/man strftime/
|
|
for details), there is also a sequence "%N" that is expanded to the name
|
|
of dumped table. Therefore, each periodic dump of each table can be
|
|
saved to a different file. Mandatory, see example below.
|
|
|
|
<tag><label id="mrt-period">period <m/number/</tag>
|
|
Specify the time interval (in seconds) between periodic dumps.
|
|
Mandatory.
|
|
|
|
<tag><label id="mrt-always-add-path">always add path <m/switch/</tag>
|
|
The MRT format uses special records (specified in <rfc id="8050">) for
|
|
routes received using BGP ADD_PATH extension to keep Path ID, while
|
|
other routes use regular records. This has advantage of better
|
|
compatibility with tools that do not know special records, but it loses
|
|
information about which route is the best route. When this option is
|
|
enabled, both ADD_PATH and non-ADD_PATH routes are stored in ADD_PATH
|
|
records and order of routes for network is preserved. Default: disabled.
|
|
</descrip>
|
|
|
|
<sect1>Example
|
|
<label id="mrt-exam">
|
|
|
|
<p><code>
|
|
protocol mrt {
|
|
table "tab*";
|
|
where source = RTS_BGP;
|
|
filename "/var/log/bird/%N_%F_%T.mrt";
|
|
period 300;
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>OSPF
|
|
<label id="ospf">
|
|
|
|
<sect1>Introduction
|
|
<label id="ospf-intro">
|
|
|
|
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
|
|
protocol. The current IPv4 version (OSPFv2) is defined in <rfc id="2328"> and
|
|
the current IPv6 version (OSPFv3) is defined in <rfc id="5340"> 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
|
|
<label id="ospf-config">
|
|
|
|
<p>First, the desired OSPF version can be specified by using <cf/ospf v2/ or
|
|
<cf/ospf v3/ as a protocol type. By default, OSPFv2 is used. 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.
|
|
|
|
<p>OSPFv2 needs one IPv4 channel. OSPFv3 needs either one IPv6 channel, or one
|
|
IPv4 channel (<rfc id="5838">). Therefore, it is possible to use OSPFv3 for both
|
|
IPv4 and Pv6 routing, but it is necessary to have two protocol instances anyway.
|
|
If no channel is configured, appropriate channel is defined with default
|
|
parameters.
|
|
|
|
<code>
|
|
protocol ospf [v2|v3] <name> {
|
|
rfc1583compat <switch>;
|
|
rfc5838 <switch>;
|
|
instance id <num>;
|
|
stub router <switch>;
|
|
tick <num>;
|
|
ecmp <switch> [limit <num>];
|
|
merge external <switch>;
|
|
graceful restart <switch>|aware;
|
|
graceful restart time <num>;
|
|
area <id> {
|
|
stub;
|
|
nssa;
|
|
summary <switch>;
|
|
default nssa <switch>;
|
|
default cost <num>;
|
|
default cost2 <num>;
|
|
translator <switch>;
|
|
translator stability <num>;
|
|
|
|
networks {
|
|
<prefix>;
|
|
<prefix> hidden;
|
|
};
|
|
external {
|
|
<prefix>;
|
|
<prefix> hidden;
|
|
<prefix> tag <num>;
|
|
};
|
|
stubnet <prefix>;
|
|
stubnet <prefix> {
|
|
hidden <switch>;
|
|
summary <switch>;
|
|
cost <num>;
|
|
};
|
|
interface <interface pattern> [instance <num>] {
|
|
cost <num>;
|
|
stub <switch>;
|
|
hello <num>;
|
|
poll <num>;
|
|
retransmit <num>;
|
|
priority <num>;
|
|
wait <num>;
|
|
dead count <num>;
|
|
dead <num>;
|
|
secondary <switch>;
|
|
rx buffer [normal|large|<num>];
|
|
tx length <num>;
|
|
type [broadcast|bcast|pointopoint|ptp|
|
|
nonbroadcast|nbma|pointomultipoint|ptmp];
|
|
link lsa suppression <switch>;
|
|
strict nonbroadcast <switch>;
|
|
real broadcast <switch>;
|
|
ptp netmask <switch>;
|
|
ptp address <switch>;
|
|
check link <switch>;
|
|
bfd <switch>;
|
|
ecmp weight <num>;
|
|
ttl security [<switch>; | tx only]
|
|
tx class|dscp <num>;
|
|
tx priority <num>;
|
|
authentication none|simple|cryptographic;
|
|
password "<text>";
|
|
password "<text>" {
|
|
id <num>;
|
|
generate from "<date>";
|
|
generate to "<date>";
|
|
accept from "<date>";
|
|
accept to "<date>";
|
|
from "<date>";
|
|
to "<date>";
|
|
algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
|
|
};
|
|
neighbors {
|
|
<ip>;
|
|
<ip> eligible;
|
|
};
|
|
};
|
|
virtual link <id> [instance <num>] {
|
|
hello <num>;
|
|
retransmit <num>;
|
|
wait <num>;
|
|
dead count <num>;
|
|
dead <num>;
|
|
authentication none|simple|cryptographic;
|
|
password "<text>";
|
|
password "<text>" {
|
|
id <num>;
|
|
generate from "<date>";
|
|
generate to "<date>";
|
|
accept from "<date>";
|
|
accept to "<date>";
|
|
from "<date>";
|
|
to "<date>";
|
|
algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
|
|
};
|
|
};
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<descrip>
|
|
<tag><label id="ospf-rfc1583compat">rfc1583compat <M>switch</M></tag>
|
|
This option controls compatibility of routing table calculation with
|
|
<rfc id="1583">. Default value is no.
|
|
|
|
<tag><label id="ospf-rfc5838">rfc5838 <m/switch/</tag>
|
|
Basic OSPFv3 is limited to IPv6 unicast routing. The <rfc id="5838">
|
|
extension defines support for more address families (IPv4, IPv6, both
|
|
unicast and multicast). The extension is enabled by default, but can be
|
|
disabled if necessary, as it restricts the range of available instance
|
|
IDs. Default value is yes.
|
|
|
|
<tag><label id="ospf-instance-id">instance id <m/num/</tag>
|
|
When multiple OSPF protocol instances are active on the same links, they
|
|
should use different instance IDs to distinguish their packets. Although
|
|
it could be done on per-interface basis, it is often preferred to set
|
|
one instance ID to whole OSPF domain/topology (e.g., when multiple
|
|
instances are used to represent separate logical topologies on the same
|
|
physical network). This option specifies the instance ID for all
|
|
interfaces of the OSPF instance, but can be overridden by
|
|
<cf/interface/ option. Default value is 0 unless OSPFv3-AF extended
|
|
address families are used, see <rfc id="5838"> for that case.
|
|
|
|
<tag><label id="ospf-stub-router">stub router <M>switch</M></tag>
|
|
This option configures the router to be a stub router, i.e., a router
|
|
that participates in the OSPF topology but does not allow transit
|
|
traffic. In OSPFv2, this is implemented by advertising maximum metric
|
|
for outgoing links. In OSPFv3, the stub router behavior is announced by
|
|
clearing the R-bit in the router LSA. See <rfc id="6987"> for details.
|
|
Default value is no.
|
|
|
|
<tag><label id="ospf-tick">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><label id="ospf-ecmp">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 maximum number of
|
|
nexthops in one route. By default, ECMP is enabled if supported by
|
|
Kernel. Default value of the limit is 16.
|
|
|
|
<tag><label id="ospf-merge-external">merge external <M>switch</M></tag>
|
|
This option specifies whether OSPF should merge external routes from
|
|
different routers/LSAs for the same destination. When enabled together
|
|
with <cf/ecmp/, equal-cost external routes will be combined to multipath
|
|
routes in the same way as regular routes. When disabled, external routes
|
|
from different LSAs are treated as separate even if they represents the
|
|
same destination. Default value is no.
|
|
|
|
<tag><label id="ospf-graceful-restart">graceful restart <m/switch/|aware</tag>
|
|
When an OSPF instance is restarted, neighbors break adjacencies and
|
|
recalculate their routing tables, which disrupts packet forwarding even
|
|
when the forwarding plane of the restarting router remains intact.
|
|
<rfc id="3623"> specifies a graceful restart mechanism to alleviate this
|
|
issue. For OSPF graceful restart, restarting router originates
|
|
Grace-LSAs, announcing intent to do graceful restart. Neighbors
|
|
receiving these LSAs enter helper mode, in which they ignore breakdown
|
|
of adjacencies, behave as if nothing is happening and keep old routes.
|
|
When adjacencies are reestablished, the restarting router flushes
|
|
Grace-LSAs and graceful restart is ended.
|
|
|
|
This option controls the graceful restart mechanism. It has three
|
|
states: Disabled, when no support is provided. Aware, when graceful
|
|
restart helper mode is supported, but no local graceful restart is
|
|
allowed (i.e. helper-only role). Enabled, when the full graceful restart
|
|
support is provided (i.e. both restarting and helper role). Note that
|
|
proper support for local graceful restart requires also configuration of
|
|
other protocols. Default: aware.
|
|
|
|
<tag><label id="ospf-graceful-restart-time">graceful restart time <m/num/</tag>
|
|
The restart time is announced in the Grace-LSA and specifies how long
|
|
neighbors should wait for proper end of the graceful restart before
|
|
exiting helper mode prematurely. Default: 120 seconds.
|
|
|
|
<tag><label id="ospf-area">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><label id="ospf-stub">stub</tag>
|
|
This option configures the area to be a stub area. External routes are
|
|
not flooded into stub areas. Also summary LSAs can be limited in stub
|
|
areas (see option <cf/summary/). By default, the area is not a stub
|
|
area.
|
|
|
|
<tag><label id="ospf-nssa">nssa</tag>
|
|
This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA
|
|
is a variant of a stub area which allows a limited way of external route
|
|
propagation. Global external routes are not propagated into a NSSA, but
|
|
an external route can be imported into NSSA as a (area-wide) NSSA-LSA
|
|
(and possibly translated and/or aggregated on area boundary). By
|
|
default, the area is not NSSA.
|
|
|
|
<tag><label id="ospf-summary">summary <M>switch</M></tag>
|
|
This option controls propagation of summary LSAs into stub or NSSA
|
|
areas. If enabled, summary LSAs are propagated as usual, otherwise just
|
|
the default summary route (0.0.0.0/0) is propagated (this is sometimes
|
|
called totally stubby area). If a stub area has more area boundary
|
|
routers, propagating summary LSAs could lead to more efficient routing
|
|
at the cost of larger link state database. Default value is no.
|
|
|
|
<tag><label id="ospf-default-nssa">default nssa <M>switch</M></tag>
|
|
When <cf/summary/ option is enabled, default summary route is no longer
|
|
propagated to the NSSA. In that case, this option allows to originate
|
|
default route as NSSA-LSA to the NSSA. Default value is no.
|
|
|
|
<tag><label id="ospf-default-cost">default cost <M>num</M></tag>
|
|
This option controls the cost of a default route propagated to stub and
|
|
NSSA areas. Default value is 1000.
|
|
|
|
<tag><label id="ospf-default-cost2">default cost2 <M>num</M></tag>
|
|
When a default route is originated as NSSA-LSA, its cost can use either
|
|
type 1 or type 2 metric. This option allows to specify the cost of a
|
|
default route in type 2 metric. By default, type 1 metric (option
|
|
<cf/default cost/) is used.
|
|
|
|
<tag><label id="ospf-translator">translator <M>switch</M></tag>
|
|
This option controls translation of NSSA-LSAs into external LSAs. By
|
|
default, one translator per NSSA is automatically elected from area
|
|
boundary routers. If enabled, this area boundary router would
|
|
unconditionally translate all NSSA-LSAs regardless of translator
|
|
election. Default value is no.
|
|
|
|
<tag><label id="ospf-translator-stability">translator stability <M>num</M></tag>
|
|
This option controls the translator stability interval (in seconds).
|
|
When the new translator is elected, the old one keeps translating until
|
|
the interval is over. Default value is 40.
|
|
|
|
<tag><label id="ospf-networks">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><label id="ospf-external">external { <m/set/ }</tag>
|
|
Definition of external area IP ranges for NSSAs. This is used for
|
|
NSSA-LSA translation. Hidden networks are not translated into external
|
|
LSAs. Networks can have configured route tag.
|
|
|
|
<tag><label id="ospf-stubnet">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><label id="ospf-iface">interface <M>pattern</M> [instance <m/num/]</tag>
|
|
Defines that the specified interfaces belong to the area being defined.
|
|
See <ref id="proto-iface" name="interface"> common option for detailed
|
|
description. In OSPFv2, extended interface clauses are used, because
|
|
each network prefix is handled as a separate virtual interface.
|
|
|
|
You can specify alternative instance ID for the interface definition,
|
|
therefore it is possible to have several instances of that interface
|
|
with different options or even in different areas. For OSPFv2, instance
|
|
ID support is an extension (<rfc id="6549">) and is supposed to be set
|
|
per-protocol. For OSPFv3, it is an integral feature.
|
|
|
|
<tag><label id="ospf-virtual-link">virtual link <M>id</M> [instance <m/num/]</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 a transport area. This item cannot be in the backbone. Like with
|
|
<cf/interface/ option, you could also use several virtual links to one
|
|
destination with different instance IDs.
|
|
|
|
<tag><label id="ospf-cost">cost <M>num</M></tag>
|
|
Specifies output cost (metric) of an interface. Default value is 10.
|
|
|
|
<tag><label id="ospf-stub-iface">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><label id="ospf-hello">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><label id="ospf-poll">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><label id="ospf-retransmit">retransmit <M>num</M></tag>
|
|
Specifies interval in seconds between retransmissions of unacknowledged
|
|
updates. Default value is 5.
|
|
|
|
<tag><label id="ospf-transmit-delay">transmit delay <M>num</M></tag>
|
|
Specifies estimated transmission delay of link state updates send over
|
|
the interface. The value is added to LSA age of LSAs propagated through
|
|
it. Default value is 1.
|
|
|
|
<tag><label id="ospf-priority">priority <M>num</M></tag>
|
|
On every multiple access network (e.g., the Ethernet) Designated Router
|
|
and Backup Designated 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><label id="ospf-wait">wait <M>num</M></tag>
|
|
After start, router waits for the specified number of seconds between
|
|
starting election and building adjacency. Default value is 4*<m/hello/.
|
|
|
|
<tag><label id="ospf-dead-count">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><label id="ospf-dead">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
|
|
<cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precedence.
|
|
|
|
<tag><label id="ospf-rx-buffer">rx buffer <M>num</M></tag>
|
|
This option allows to specify the size of buffers used for packet
|
|
processing. The buffer size should be bigger than maximal size of any
|
|
packets. By default, buffers are dynamically resized as needed, but a
|
|
fixed value could be specified. Value <cf/large/ means maximal allowed
|
|
packet size - 65535.
|
|
|
|
<tag><label id="ospf-tx-length">tx length <M>num</M></tag>
|
|
Transmitted OSPF messages that contain large amount of information are
|
|
segmented to separate OSPF packets to avoid IP fragmentation. This
|
|
option specifies the soft ceiling for the length of generated OSPF
|
|
packets. Default value is the MTU of the network interface. Note that
|
|
larger OSPF packets may still be generated if underlying OSPF messages
|
|
cannot be splitted (e.g. when one large LSA is propagated).
|
|
|
|
<tag><label id="ospf-type-bcast">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><label id="ospf-type-ptp">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><label id="ospf-type-nbma">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><label id="ospf-type-ptmp">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><label id="ospf-link-lsa-suppression">link lsa suppression <m/switch/</tag>
|
|
In OSPFv3, link LSAs are generated for each link, announcing link-local
|
|
IPv6 address of the router to its local neighbors. These are useless on
|
|
PtP or PtMP networks and this option allows to suppress the link LSA
|
|
origination for such interfaces. The option is ignored on other than PtP
|
|
or PtMP interfaces. Default value is no.
|
|
|
|
<tag><label id="ospf-strict-nonbroadcast">strict nonbroadcast <m/switch/</tag>
|
|
If set, don't send hello to any undefined neighbor. This switch is
|
|
ignored on other than NBMA or PtMP interfaces. Default value is no.
|
|
|
|
<tag><label id="ospf-real-broadcast">real broadcast <m/switch/</tag>
|
|
In <cf/type broadcast/ or <cf/type ptp/ network configuration, OSPF
|
|
packets are sent as IP multicast packets. This option changes the
|
|
behavior to using old-fashioned IP broadcast packets. This may be useful
|
|
as a workaround if IP multicast for some reason does not work or does
|
|
not work reliably. This is a non-standard option and probably is not
|
|
interoperable with other OSPF implementations. Default value is no.
|
|
|
|
<tag><label id="ospf-ptp-netmask">ptp netmask <m/switch/</tag>
|
|
In <cf/type ptp/ network configurations, OSPFv2 implementations should
|
|
ignore received netmask field in hello packets and should send hello
|
|
packets with zero netmask field on unnumbered PtP links. But some OSPFv2
|
|
implementations perform netmask checking even for PtP links.
|
|
|
|
This option specifies whether real netmask will be used in hello packets
|
|
on <cf/type ptp/ interfaces. You should ignore this option unless you
|
|
meet some compatibility problems related to this issue. Default value is
|
|
no for unnumbered PtP links, yes otherwise.
|
|
|
|
<tag><label id="ospf-ptp-address">ptp address <m/switch/</tag>
|
|
In <cf/type ptp/ network configurations, OSPFv2 implementations should
|
|
use IP address for regular PtP links and interface id for unnumbered PtP
|
|
links in data field of link description records in router LSA. This data
|
|
field has only local meaning for PtP links, but some broken OSPFv2
|
|
implementations assume there is an IP address and use it as a next hop
|
|
in SPF calculations. Note that interface id for unnumbered PtP links is
|
|
necessary when graceful restart is enabled to distinguish PtP links with
|
|
the same local IP address.
|
|
|
|
This option specifies whether an IP address will be used in data field
|
|
for <cf/type ptp/ interfaces, it is ignored for other interfaces. You
|
|
should ignore this option unless you meet some compatibility problems
|
|
related to this issue. Default value is no for unnumbered PtP links when
|
|
graceful restart is enabled, yes otherwise.
|
|
|
|
<tag><label id="ospf-check-link">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 yes.
|
|
|
|
<tag><label id="ospf-bfd">bfd <M>switch</M></tag>
|
|
OSPF could use BFD protocol as an advisory mechanism for neighbor
|
|
liveness and failure detection. If enabled, BIRD setups a BFD session
|
|
for each OSPF neighbor and tracks its liveness by it. This has an
|
|
advantage of an order of magnitude lower detection times in case of
|
|
failure. Note that BFD protocol also has to be configured, see
|
|
<ref id="bfd" name="BFD"> section for details. Default value is no.
|
|
|
|
<tag><label id="ospf-ttl-security">ttl security [<m/switch/ | tx only]</tag>
|
|
TTL security is a feature that protects routing protocols from remote
|
|
spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
|
|
destined to neighbors. Because TTL is decremented when packets are
|
|
forwarded, it is non-trivial to spoof packets with TTL 255 from remote
|
|
locations. Note that this option would interfere with OSPF virtual
|
|
links.
|
|
|
|
If this option is enabled, the router will send OSPF packets with TTL
|
|
255 and drop received packets with TTL less than 255. If this option si
|
|
set to <cf/tx only/, TTL 255 is used for sent packets, but is not
|
|
checked for received packets. Default value is no.
|
|
|
|
<tag><label id="ospf-tx-class">tx class|dscp|priority <m/num/</tag>
|
|
These options specify the ToS/DiffServ/Traffic class/Priority of the
|
|
outgoing OSPF packets. See <ref id="proto-tx-class" name="tx class"> common
|
|
option for detailed description.
|
|
|
|
<tag><label id="ospf-ecmp-weight">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><label id="ospf-auth-none">authentication none</tag>
|
|
No passwords are sent in OSPF packets. This is the default value.
|
|
|
|
<tag><label id="ospf-auth-simple">authentication simple</tag>
|
|
Every packet carries 8 bytes of password. Received packets lacking this
|
|
password are ignored. This authentication mechanism is very weak.
|
|
This option is not available in OSPFv3.
|
|
|
|
<tag><label id="ospf-auth-cryptographic">authentication cryptographic</tag>
|
|
An authentication code is appended to every packet. The specific
|
|
cryptographic algorithm is selected by option <cf/algorithm/ for each
|
|
key. The default cryptographic algorithm for OSPFv2 keys is Keyed-MD5
|
|
and for OSPFv3 keys is HMAC-SHA-256. Passwords are not sent open via
|
|
network, so this mechanism is quite secure. Packets can still be read by
|
|
an attacker.
|
|
|
|
<tag><label id="ospf-pass">password "<M>text</M>"</tag>
|
|
Specifies a password used for authentication. See
|
|
<ref id="proto-pass" name="password"> common option for detailed
|
|
description.
|
|
|
|
<tag><label id="ospf-neighbors">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.
|
|
In OSPFv3, link-local addresses should be used, using global ones is
|
|
possible, but it is nonstandard and might be problematic. And definitely,
|
|
link-local and global addresses should not be mixed.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
<label id="ospf-attr">
|
|
|
|
<p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
|
|
|
|
<p>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/.
|
|
|
|
When both metrics are specified then <cf/metric of type 2/ is used. This is
|
|
relevant e.g. when a type 2 external route is propagated from one OSPF domain to
|
|
another and <cf/ospf_metric1/ is an internal distance to the original ASBR,
|
|
while <cf/ospf_metric2/ stores the type 2 metric. Note that in such cases if
|
|
<cf/ospf_metric1/ is non-zero then <cf/ospf_metric2/ is increased by one to
|
|
ensure monotonicity of metric, as internal distance is reset to zero when an
|
|
external route is announced.
|
|
|
|
<p>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
|
|
<label id="ospf-exam">
|
|
|
|
<p><code>
|
|
protocol ospf MyOSPF {
|
|
ipv4 {
|
|
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";
|
|
algorithm hmac sha384;
|
|
};
|
|
password "def" {
|
|
id 2;
|
|
generate to "22-07-2005 17:03:21";
|
|
accept from "22-02-2001 11:34:06";
|
|
algorithm hmac sha512;
|
|
};
|
|
};
|
|
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>Perf
|
|
<label id="perf">
|
|
|
|
<sect1>Introduction
|
|
<label id="perf-intro">
|
|
|
|
<p>The Perf protocol is a generator of fake routes together with a time measurement
|
|
framework. Its purpose is to check BIRD performance and to benchmark filters.
|
|
|
|
<p>Import mode of this protocol runs in several steps. In each step, it generates 2^x routes,
|
|
imports them into the appropriate table and withdraws them. The exponent x is configurable.
|
|
It runs the benchmark several times for the same x, then it increases x by one
|
|
until it gets too high, then it stops.
|
|
|
|
<p>Export mode of this protocol repeats route refresh from table and measures how long it takes.
|
|
|
|
<p>Output data is logged on info level. There is a Perl script <cf>proto/perf/parse.pl</cf>
|
|
which may be handy to parse the data and draw some plots.
|
|
|
|
<p>Implementation of this protocol is experimental. Use with caution and do not keep
|
|
any instance of Perf in production configs for long time. The config interface is also unstable
|
|
and may change in future versions without warning.
|
|
|
|
<sect1>Configuration
|
|
<label id="perf-config">
|
|
|
|
<p><descrip>
|
|
<tag><label id="perf-mode">mode import|export</tag>
|
|
Set perf mode. Default: import
|
|
|
|
<tag><label id="perf-repeat">repeat <m/number/</tag>
|
|
Run this amount of iterations of the benchmark for every amount step. Default: 4
|
|
|
|
<tag><label id="perf-from">exp from <m/number/</tag>
|
|
Begin benchmarking on this exponent for number of generated routes in one step.
|
|
Default: 10
|
|
|
|
<tag><label id="perf-to">exp to <m/number/</tag>
|
|
Stop benchmarking on this exponent. Default: 20
|
|
|
|
<tag><label id="perf-threshold-min">threshold min <m/time/</tag>
|
|
If a run for the given exponent took less than this time for route import,
|
|
increase the exponent immediately. Default: 1 ms
|
|
|
|
<tag><label id="perf-threshold-max">threshold max <m/time/</tag>
|
|
If every run for the given exponent took at least this time for route import,
|
|
stop benchmarking. Default: 500 ms
|
|
</descrip>
|
|
|
|
<sect>Pipe
|
|
<label id="pipe">
|
|
|
|
<sect1>Introduction
|
|
<label id="pipe-intro">
|
|
|
|
<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. Both tables
|
|
must be of the same nettype.
|
|
|
|
<p>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.
|
|
|
|
<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
|
|
<label id="pipe-config">
|
|
|
|
<p>Essentially, the Pipe protocol is just a channel connected to a table on both
|
|
sides. Therefore, the configuration block for <cf/protocol pipe/ shall directly
|
|
include standard channel config options; see the example below.
|
|
|
|
<p><descrip>
|
|
<tag><label id="pipe-peer-table">peer table <m/table/</tag>
|
|
Defines secondary routing table to connect to. The primary one is
|
|
selected by the <cf/table/ keyword.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
<label id="pipe-attr">
|
|
|
|
<p>The Pipe protocol doesn't define any route attributes.
|
|
|
|
<sect1>Example
|
|
<label id="pipe-exam">
|
|
|
|
<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>
|
|
ipv4 table as1; # Define the tables
|
|
ipv4 table as2;
|
|
|
|
protocol kernel kern1 { # Synchronize them with the kernel
|
|
ipv4 { table as1; export all; };
|
|
kernel table 1;
|
|
}
|
|
|
|
protocol kernel kern2 {
|
|
ipv4 { table as2; export all; };
|
|
kernel table 2;
|
|
}
|
|
|
|
protocol bgp bgp1 { # The outside connections
|
|
ipv4 { table as1; import all; export all; };
|
|
local as 1;
|
|
neighbor 192.168.0.1 as 1001;
|
|
}
|
|
|
|
protocol bgp bgp2 {
|
|
ipv4 { table as2; import all; export all; };
|
|
local as 2;
|
|
neighbor 10.0.0.1 as 1002;
|
|
}
|
|
|
|
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
|
|
<label id="radv">
|
|
|
|
<sect1>Introduction
|
|
<label id="radv-intro">
|
|
|
|
<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 id="4861">, router preferences and specific routes (<rfc id="4191">),
|
|
and DNS extensions (<rfc id="6106">).
|
|
|
|
<p>The RAdv protocols supports just IPv6 channel.
|
|
|
|
<sect1>Configuration
|
|
<label id="radv-config">
|
|
|
|
<p>There are several classes of definitions in RAdv configuration -- interface
|
|
definitions, prefix definitions and DNS definitions:
|
|
|
|
<descrip>
|
|
<tag><label id="radv-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag>
|
|
Interface definitions specify a set of interfaces on which the
|
|
protocol is activated and contain interface specific options.
|
|
See <ref id="proto-iface" name="interface"> common options for
|
|
detailed description.
|
|
|
|
<tag><label id="radv-prefix">prefix <m/prefix/ { <m/options/ }</tag>
|
|
Prefix definitions allow 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.
|
|
|
|
<tag><label id="radv-rdnss">rdnss { <m/options/ }</tag>
|
|
RDNSS definitions allow to specify a list of advertised recursive DNS
|
|
servers together with their options. As options are seldom necessary,
|
|
there is also a short variant <cf>rdnss <m/address/</cf> that just
|
|
specifies one DNS server. Multiple definitions are cumulative. RDNSS
|
|
definitions may also be interface-specific when used inside interface
|
|
options. By default, interface uses both global and interface-specific
|
|
options, but that can be changed by <cf/rdnss local/ option.
|
|
|
|
<tag><label id="radv-dnssl">dnssl { <m/options/ }</tag>
|
|
DNSSL definitions allow to specify a list of advertised DNS search
|
|
domains together with their options. Like <cf/rdnss/ above, multiple
|
|
definitions are cumulative, they can be used also as interface-specific
|
|
options and there is a short variant <cf>dnssl <m/domain/</cf> that just
|
|
specifies one DNS search domain.
|
|
|
|
<tag><label id="radv-trigger">trigger <m/prefix/</tag>
|
|
RAdv protocol could be configured to change its behavior based on
|
|
availability of routes. When this option is used, the protocol waits in
|
|
suppressed state until a <it/trigger route/ (for the specified network)
|
|
is exported to the protocol, the protocol also returns to suppressed
|
|
state if the <it/trigger route/ disappears. Note that route export
|
|
depends on specified export filter, as usual. This option could be used,
|
|
e.g., for handling failover in multihoming scenarios.
|
|
|
|
During suppressed state, router advertisements are generated, but with
|
|
some fields zeroed. Exact behavior depends on which fields are zeroed,
|
|
this can be configured by <cf/sensitive/ option for appropriate
|
|
fields. By default, just <cf/default lifetime/ (also called <cf/router
|
|
lifetime/) is zeroed, which means hosts cannot use the router as a
|
|
default router. <cf/preferred lifetime/ and <cf/valid lifetime/ could
|
|
also be configured as <cf/sensitive/ for a prefix, which would cause
|
|
autoconfigured IPs to be deprecated or even removed.
|
|
|
|
<tag><label id="radv-propagate-routes">propagate routes <m/switch/</tag>
|
|
This option controls propagation of more specific routes, as defined in
|
|
<rfc id="4191">. If enabled, all routes exported to the RAdv protocol,
|
|
with the exception of the trigger prefix, are added to advertisments as
|
|
additional options. The lifetime and preference of advertised routes can
|
|
be set individually by <cf/ra_lifetime/ and <cf/ra_preference/ route
|
|
attributes, or per interface by <cf/route lifetime/ and
|
|
<cf/route preference/ options. Default: disabled.
|
|
|
|
Note that the RFC discourages from sending more than 17 routes and
|
|
recommends the routes to be configured manually.
|
|
</descrip>
|
|
|
|
<p>Interface specific options:
|
|
|
|
<descrip>
|
|
<tag><label id="radv-iface-max-ra-interval">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><label id="radv-iface-min-ra-interval">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 * <cf/max ra interval/. Default:
|
|
about 1/3 * <cf/max ra interval/.
|
|
|
|
<tag><label id="radv-iface-min-delay">min delay <m/expr/</tag>
|
|
The minimum delay between two consecutive router advertisements, in
|
|
seconds. Default: 3
|
|
|
|
<tag><label id="radv-solicited-ra-unicast">solicited ra unicast <m/switch/</tag>
|
|
Solicited router advertisements are usually sent to all-nodes multicast
|
|
group like unsolicited ones, but the router can be configured to send
|
|
them as unicast directly to soliciting nodes instead. This is especially
|
|
useful on wireless networks (see <rfc id="7772">). Default: no
|
|
|
|
<tag><label id="radv-iface-managed">managed <m/switch/</tag>
|
|
This option specifies whether hosts should use DHCPv6 for IP address
|
|
configuration. Default: no
|
|
|
|
<tag><label id="radv-iface-other-config">other config <m/switch/</tag>
|
|
This option specifies whether hosts should use DHCPv6 to receive other
|
|
configuration information. Default: no
|
|
|
|
<tag><label id="radv-iface-link-mtu">link mtu <m/expr/</tag>
|
|
This option specifies which value of MTU should be used by hosts. 0
|
|
means unspecified. Default: 0
|
|
|
|
<tag><label id="radv-iface-reachable-time">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><label id="radv-iface-retrans-timer">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><label id="radv-iface-current-hop-limit">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><label id="radv-iface-default-lifetime">default lifetime <m/expr/ [sensitive <m/switch/]</tag>
|
|
This option specifies the time (in seconds) how long (since the receipt
|
|
of RA) hosts may use the router as a default router. 0 means do not use
|
|
as a default router. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">.
|
|
Default: 3 * <cf/max ra interval/, <cf/sensitive/ yes.
|
|
|
|
<tag><label id="radv-iface-default-preference">default preference low|medium|high</tag>
|
|
This option specifies the Default Router Preference value to advertise
|
|
to hosts. Default: medium.
|
|
|
|
<tag><label id="radv-iface-route-lifetime">route lifetime <m/expr/ [sensitive <m/switch/]</tag>
|
|
This option specifies the default value of advertised lifetime for
|
|
specific routes; i.e., the time (in seconds) for how long (since the
|
|
receipt of RA) hosts should consider these routes valid. A special value
|
|
0xffffffff represents infinity. The lifetime can be overriden on a per
|
|
route basis by the <ref id="rta-ra-lifetime" name="ra_lifetime"> route
|
|
attribute. Default: 3 * <cf/max ra interval/, <cf/sensitive/ no.
|
|
|
|
For the <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">.
|
|
If <cf/sensitive/ is enabled, even the routes with the <cf/ra_lifetime/
|
|
attribute become sensitive to the trigger.
|
|
|
|
<tag><label id="radv-iface-route-preference">route preference low|medium|high</tag>
|
|
This option specifies the default value of advertised route preference
|
|
for specific routes. The value can be overriden on a per route basis by
|
|
the <ref id="rta-ra-preference" name="ra_preference"> route attribute.
|
|
Default: medium.
|
|
|
|
<tag><label id="radv-prefix-linger-time">prefix linger time <m/expr/</tag>
|
|
When a prefix or a route disappears, it is advertised for some time with
|
|
zero lifetime, to inform clients it is no longer valid. This option
|
|
specifies the time (in seconds) for how long prefixes are advertised
|
|
that way. Default: 3 * <cf/max ra interval/.
|
|
|
|
<tag><label id="radv-route-linger-time">route linger time <m/expr/</tag>
|
|
When a prefix or a route disappears, it is advertised for some time with
|
|
zero lifetime, to inform clients it is no longer valid. This option
|
|
specifies the time (in seconds) for how long routes are advertised
|
|
that way. Default: 3 * <cf/max ra interval/.
|
|
|
|
<tag><label id="radv-iface-rdnss-local">rdnss local <m/switch/</tag>
|
|
Use only local (interface-specific) RDNSS definitions for this
|
|
interface. Otherwise, both global and local definitions are used. Could
|
|
also be used to disable RDNSS for given interface if no local definitons
|
|
are specified. Default: no.
|
|
|
|
<tag><label id="radv-iface-dnssl-local">dnssl local <m/switch/</tag>
|
|
Use only local DNSSL definitions for this interface. See <cf/rdnss local/
|
|
option above. Default: no.
|
|
</descrip>
|
|
|
|
<p>Prefix specific options
|
|
|
|
<descrip>
|
|
<tag><label id="radv-prefix-skip">skip <m/switch/</tag>
|
|
This option allows to specify that given prefix should not be
|
|
advertised. This is useful for making exceptions from a default policy
|
|
of advertising all prefixes. Note that for withdrawing an already
|
|
advertised prefix it is more useful to advertise it with zero valid
|
|
lifetime. Default: no
|
|
|
|
<tag><label id="radv-prefix-onlink">onlink <m/switch/</tag>
|
|
This option specifies whether hosts may use the advertised prefix for
|
|
onlink determination. Default: yes
|
|
|
|
<tag><label id="radv-prefix-autonomous">autonomous <m/switch/</tag>
|
|
This option specifies whether hosts may use the advertised prefix for
|
|
stateless autoconfiguration. Default: yes
|
|
|
|
<tag><label id="radv-prefix-valid-lifetime">valid lifetime <m/expr/ [sensitive <m/switch/]</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. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">.
|
|
Default: 86400 (1 day), <cf/sensitive/ no.
|
|
|
|
<tag><label id="radv-prefix-preferred-lifetime">preferred lifetime <m/expr/ [sensitive <m/switch/]</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. For <cf/sensitive/ option,
|
|
see <ref id="radv-trigger" name="trigger">. Default: 14400 (4 hours),
|
|
<cf/sensitive/ no.
|
|
</descrip>
|
|
|
|
<p>RDNSS specific options:
|
|
|
|
<descrip>
|
|
<tag><label id="radv-rdnss-ns">ns <m/address/</tag>
|
|
This option specifies one recursive DNS server. Can be used multiple
|
|
times for multiple servers. It is mandatory to have at least one
|
|
<cf/ns/ option in <cf/rdnss/ definition.
|
|
|
|
<tag><label id="radv-rdnss-lifetime">lifetime [mult] <m/expr/</tag>
|
|
This option specifies the time how long the RDNSS information may be
|
|
used by clients after the receipt of RA. It is expressed either in
|
|
seconds or (when <cf/mult/ is used) in multiples of <cf/max ra
|
|
interval/. Note that RDNSS information is also invalidated when
|
|
<cf/default lifetime/ expires. 0 means these addresses are no longer
|
|
valid DNS servers. Default: 3 * <cf/max ra interval/.
|
|
</descrip>
|
|
|
|
<p>DNSSL specific options:
|
|
|
|
<descrip>
|
|
<tag><label id="radv-dnssl-domain">domain <m/address/</tag>
|
|
This option specifies one DNS search domain. Can be used multiple times
|
|
for multiple domains. It is mandatory to have at least one <cf/domain/
|
|
option in <cf/dnssl/ definition.
|
|
|
|
<tag><label id="radv-dnssl-lifetime">lifetime [mult] <m/expr/</tag>
|
|
This option specifies the time how long the DNSSL information may be
|
|
used by clients after the receipt of RA. Details are the same as for
|
|
RDNSS <cf/lifetime/ option above. Default: 3 * <cf/max ra interval/.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
<label id="radv-attr">
|
|
|
|
<p>RAdv defines two route attributes:
|
|
|
|
<descrip>
|
|
<tag><label id="rta-ra-preference">enum ra_preference</tag>
|
|
The preference of the route. The value can be <it/RA_PREF_LOW/,
|
|
<it/RA_PREF_MEDIUM/ or <it/RA_PREF_HIGH/. If the attribute is not set,
|
|
the <ref id="radv-iface-route-preference" name="route preference">
|
|
option is used.
|
|
|
|
<tag><label id="rta-ra-lifetime">int ra_lifetime</tag>
|
|
The advertised lifetime of the route, in seconds. The special value of
|
|
0xffffffff represents infinity. If the attribute is not set, the
|
|
<ref id="radv-iface-route-lifetime" name="route lifetime">
|
|
option is used.
|
|
</descrip>
|
|
|
|
<sect1>Example
|
|
<label id="radv-exam">
|
|
|
|
<p><code>
|
|
ipv6 table radv_routes; # Manually configured routes go here
|
|
|
|
protocol static {
|
|
ipv6 { table radv_routes; };
|
|
|
|
route 2001:0DB8:4000::/48 unreachable;
|
|
route 2001:0DB8:4010::/48 unreachable;
|
|
|
|
route 2001:0DB8:4020::/48 unreachable {
|
|
ra_preference = RA_PREF_HIGH;
|
|
ra_lifetime = 3600;
|
|
};
|
|
}
|
|
|
|
protocol radv {
|
|
propagate routes yes; # Propagate the routes from the radv_routes table
|
|
ipv6 { table radv_routes; export all; };
|
|
|
|
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
|
|
};
|
|
|
|
rdnss 2001:0DB8:1234::10; # Short form of RDNSS
|
|
|
|
rdnss {
|
|
lifetime mult 10;
|
|
ns 2001:0DB8:1234::11;
|
|
ns 2001:0DB8:1234::12;
|
|
};
|
|
|
|
dnssl {
|
|
lifetime 3600;
|
|
domain "abc.com";
|
|
domain "xyz.com";
|
|
};
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>RIP
|
|
<label id="rip">
|
|
|
|
<sect1>Introduction
|
|
<label id="rip-intro">
|
|
|
|
<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.
|
|
|
|
<p>BIRD supports RIPv1 (<rfc id="1058">), RIPv2 (<rfc id="2453">), RIPng (<rfc
|
|
id="2080">), Triggered RIP for demand circuits (<rfc id="2091">), and RIP
|
|
cryptographic authentication (<rfc id="4822">).
|
|
|
|
<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
|
|
<label id="rip-config">
|
|
|
|
<p>RIP configuration consists mainly of common protocol options and interface
|
|
definitions, most RIP options are interface specific. RIPng (RIP for IPv6)
|
|
protocol instance can be configured by using <cf/rip ng/ instead of just
|
|
<cf/rip/ as a protocol type.
|
|
|
|
<p>RIP needs one IPv4 channel. RIPng needs one IPv6 channel. If no channel is
|
|
configured, appropriate channel is defined with default parameters.
|
|
|
|
<code>
|
|
protocol rip [ng] [<name>] {
|
|
infinity <number>;
|
|
ecmp <switch> [limit <number>];
|
|
interface <interface pattern> {
|
|
metric <number>;
|
|
mode multicast|broadcast;
|
|
passive <switch>;
|
|
address <ip>;
|
|
port <number>;
|
|
version 1|2;
|
|
split horizon <switch>;
|
|
poison reverse <switch>;
|
|
demand circuit <switch>;
|
|
check zero <switch>;
|
|
update time <number>;
|
|
timeout time <number>;
|
|
garbage time <number>;
|
|
ecmp weight <number>;
|
|
ttl security <switch>; | tx only;
|
|
tx class|dscp <number>;
|
|
tx priority <number>;
|
|
rx buffer <number>;
|
|
tx length <number>;
|
|
check link <switch>;
|
|
authentication none|plaintext|cryptographic;
|
|
password "<text>";
|
|
password "<text>" {
|
|
id <num>;
|
|
generate from "<date>";
|
|
generate to "<date>";
|
|
accept from "<date>";
|
|
accept to "<date>";
|
|
from "<date>";
|
|
to "<date>";
|
|
algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
|
|
};
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<descrip>
|
|
<tag><label id="rip-infinity">infinity <M>number</M></tag>
|
|
Selects the distance of infinity. Bigger values will make
|
|
protocol convergence even slower. The default value is 16.
|
|
|
|
<tag><label id="rip-ecmp">ecmp <M>switch</M> [limit <M>number</M>]</tag>
|
|
This option specifies whether RIP 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 maximum number of
|
|
nexthops in one route. By default, ECMP is enabled if supported by
|
|
Kernel. Default value of the limit is 16.
|
|
|
|
<tag><label id="rip-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag>
|
|
Interface definitions specify a set of interfaces on which the
|
|
protocol is activated and contain interface specific options.
|
|
See <ref id="proto-iface" name="interface"> common options for
|
|
detailed description.
|
|
</descrip>
|
|
|
|
<p>Interface specific options:
|
|
|
|
<descrip>
|
|
<tag><label id="rip-iface-metric">metric <m/num/</tag>
|
|
This option specifies the metric of the interface. When a route is
|
|
received from the interface, its metric is increased by this value
|
|
before further processing. Valid values are 1-255, but values higher
|
|
than infinity has no further meaning. Default: 1.
|
|
|
|
<tag><label id="rip-iface-mode">mode multicast|broadcast</tag>
|
|
This option selects the mode for RIP to use on the interface. The
|
|
default is multicast mode for RIPv2 and broadcast mode for RIPv1.
|
|
RIPng always uses the multicast mode.
|
|
|
|
<tag><label id="rip-iface-passive">passive <m/switch/</tag>
|
|
Passive interfaces receive routing updates but do not transmit any
|
|
messages. Default: no.
|
|
|
|
<tag><label id="rip-iface-address">address <m/ip/</tag>
|
|
This option specifies a destination address used for multicast or
|
|
broadcast messages, the default is the official RIP (224.0.0.9) or RIPng
|
|
(ff02::9) multicast address, or an appropriate broadcast address in the
|
|
broadcast mode.
|
|
|
|
<tag><label id="rip-iface-port">port <m/number/</tag>
|
|
This option selects an UDP port to operate on, the default is the
|
|
official RIP (520) or RIPng (521) port.
|
|
|
|
<tag><label id="rip-iface-version">version 1|2</tag>
|
|
This option selects the version of RIP used on the interface. For RIPv1,
|
|
automatic subnet aggregation is not implemented, only classful network
|
|
routes and host routes are propagated. Note that BIRD allows RIPv1 to be
|
|
configured with features that are defined for RIPv2 only, like
|
|
authentication or using multicast sockets. The default is RIPv2 for IPv4
|
|
RIP, the option is not supported for RIPng, as no further versions are
|
|
defined.
|
|
|
|
<tag><label id="rip-iface-version-only">version only <m/switch/</tag>
|
|
Regardless of RIP version configured for the interface, BIRD accepts
|
|
incoming packets of any RIP version. This option restrict accepted
|
|
packets to the configured version. Default: no.
|
|
|
|
<tag><label id="rip-iface-split-horizon">split horizon <m/switch/</tag>
|
|
Split horizon is a scheme for preventing routing loops. When split
|
|
horizon is active, routes are not regularly propagated back to the
|
|
interface from which they were received. They are either not propagated
|
|
back at all (plain split horizon) or propagated back with an infinity
|
|
metric (split horizon with poisoned reverse). Therefore, other routers
|
|
on the interface will not consider the router as a part of an
|
|
independent path to the destination of the route. Default: yes.
|
|
|
|
<tag><label id="rip-iface-poison-reverse">poison reverse <m/switch/</tag>
|
|
When split horizon is active, this option specifies whether the poisoned
|
|
reverse variant (propagating routes back with an infinity metric) is
|
|
used. The poisoned reverse has some advantages in faster convergence,
|
|
but uses more network traffic. Default: yes.
|
|
|
|
<tag><label id="rip-iface-demand-circuit">demand circuit <m/switch/</tag>
|
|
Regular RIP sends periodic full updates on an interface. There is the
|
|
Triggered RIP extension for demand circuits (<rfc id="2091">), which
|
|
removes periodic updates and introduces update acknowledgments. When
|
|
enabled, there is no RIP communication in steady-state network. Note
|
|
that in order to work, it must be enabled on both sides. As there are
|
|
no hello packets, it depends on hardware link state to detect neighbor
|
|
failures. Also, it is designed for PtP links and it does not work
|
|
properly with multiple RIP neighbors on an interface. Default: no.
|
|
|
|
<tag><label id="rip-iface-check-zero">check zero <m/switch/</tag>
|
|
Received RIPv1 packets with non-zero values in reserved fields should
|
|
be discarded. This option specifies whether the check is performed or
|
|
such packets are just processed as usual. Default: yes.
|
|
|
|
<tag><label id="rip-iface-update-time">update time <m/number/</tag>
|
|
Specifies the number of seconds between periodic updates. A lower number
|
|
will mean faster convergence but bigger network load. Default: 30.
|
|
|
|
<tag><label id="rip-iface-timeout-time">timeout time <m/number/</tag>
|
|
Specifies the time interval (in seconds) between the last received route
|
|
announcement and the route expiration. After that, the network is
|
|
considered unreachable, but still is propagated with infinity distance.
|
|
Default: 180.
|
|
|
|
<tag><label id="rip-iface-garbage-time">garbage time <m/number/</tag>
|
|
Specifies the time interval (in seconds) between the route expiration
|
|
and the removal of the unreachable network entry. The garbage interval,
|
|
when a route with infinity metric is propagated, is used for both
|
|
internal (after expiration) and external (after withdrawal) routes.
|
|
Default: 120.
|
|
|
|
<tag><label id="rip-iface-ecmp-weight">ecmp weight <m/number/</tag>
|
|
When ECMP (multipath) routes are allowed, this value specifies a
|
|
relative weight used for nexthops going through the iface. Valid
|
|
values are 1-256. Default value is 1.
|
|
|
|
<tag><label id="rip-iface-auth">authentication none|plaintext|cryptographic</tag>
|
|
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/cryptographic/ means that
|
|
packets are authenticated using some cryptographic hash function
|
|
selected by option <cf/algorithm/ for each key. The default
|
|
cryptographic algorithm for RIP keys is Keyed-MD5. If you set
|
|
authentication to not-none, it is a good idea to add <cf>password</cf>
|
|
section. Default: none.
|
|
|
|
<tag><label id="rip-iface-pass">password "<m/text/"</tag>
|
|
Specifies a password used for authentication. See <ref id="proto-pass"
|
|
name="password"> common option for detailed description.
|
|
|
|
<tag><label id="rip-iface-ttl-security">ttl security [<m/switch/ | tx only]</tag>
|
|
TTL security is a feature that protects routing protocols from remote
|
|
spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
|
|
destined to neighbors. Because TTL is decremented when packets are
|
|
forwarded, it is non-trivial to spoof packets with TTL 255 from remote
|
|
locations.
|
|
|
|
If this option is enabled, the router will send RIP packets with TTL 255
|
|
and drop received packets with TTL less than 255. If this option si set
|
|
to <cf/tx only/, TTL 255 is used for sent packets, but is not checked
|
|
for received packets. Such setting does not offer protection, but offers
|
|
compatibility with neighbors regardless of whether they use ttl
|
|
security.
|
|
|
|
For RIPng, TTL security is a standard behavior (required by <rfc
|
|
id="2080">) and therefore default value is yes. For IPv4 RIP, default
|
|
value is no.
|
|
|
|
<tag><label id="rip-iface-tx-class">tx class|dscp|priority <m/number/</tag>
|
|
These options specify the ToS/DiffServ/Traffic class/Priority of the
|
|
outgoing RIP packets. See <ref id="proto-tx-class" name="tx class"> common
|
|
option for detailed description.
|
|
|
|
<tag><label id="rip-iface-rx-buffer">rx buffer <m/number/</tag>
|
|
This option specifies the size of buffers used for packet processing.
|
|
The buffer size should be bigger than maximal size of received packets.
|
|
The default value is 532 for IPv4 RIP and interface MTU value for RIPng.
|
|
|
|
<tag><label id="rip-iface-tx-length">tx length <m/number/</tag>
|
|
This option specifies the maximum length of generated RIP packets. To
|
|
avoid IP fragmentation, it should not exceed the interface MTU value.
|
|
The default value is 532 for IPv4 RIP and interface MTU value for RIPng.
|
|
|
|
<tag><label id="rip-iface-check-link">check link <m/switch/</tag>
|
|
If set, the hardware link state (as reported by OS) is taken into
|
|
consideration. When the link disappears (e.g. an ethernet cable is
|
|
unplugged), neighbors are immediately considered unreachable and all
|
|
routes received from them are withdrawn. It is possible that some
|
|
hardware drivers or platforms do not implement this feature.
|
|
Default: yes.
|
|
</descrip>
|
|
|
|
<sect1>Attributes
|
|
<label id="rip-attr">
|
|
|
|
<p>RIP defines two route attributes:
|
|
|
|
<descrip>
|
|
<tag><label id="rta-rip-metric">int 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 a
|
|
non-RIP route is exported to RIP, the default metric is 1.
|
|
|
|
<tag><label id="rta-rip-tag">int 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 a non-RIP route is exported to RIP, the
|
|
default tag is 0.
|
|
</descrip>
|
|
|
|
<sect1>Example
|
|
<label id="rip-exam">
|
|
|
|
<p><code>
|
|
protocol rip {
|
|
ipv4 {
|
|
import all;
|
|
export all;
|
|
};
|
|
interface "eth*" {
|
|
metric 2;
|
|
port 1520;
|
|
mode multicast;
|
|
update time 12;
|
|
timeout time 60;
|
|
authentication cryptographic;
|
|
password "secret" { algorithm hmac sha256; };
|
|
};
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>RPKI
|
|
<label id="rpki">
|
|
|
|
<sect1>Introduction
|
|
|
|
<p>The Resource Public Key Infrastructure (RPKI) is mechanism for origin
|
|
validation of BGP routes (<rfc id="6480">). BIRD supports only so-called
|
|
RPKI-based origin validation. There is implemented RPKI to Router (RPKI-RTR)
|
|
protocol (<rfc id="6810">). It uses some of the RPKI data to allow a router to
|
|
verify that the autonomous system announcing an IP address prefix is in fact
|
|
authorized to do so. This is not crypto checked so can be violated. But it
|
|
should prevent the vast majority of accidental hijackings on the Internet today,
|
|
e.g. the famous Pakistani accidental announcement of YouTube's address space.
|
|
|
|
<p>The RPKI-RTR protocol receives and maintains a set of ROAs from a cache
|
|
server (also called validator). You can validate routes (<rfc id="6483">,
|
|
<rfc id="6811">) using function <cf/roa_check()/ in filter and set it as import
|
|
filter at the BGP protocol. BIRD offers crude automatic re-validating of
|
|
affected routes after RPKI update, see option <ref id="proto-rpki-reload"
|
|
name="rpki reload">. Or you can use a BIRD client command <cf>reload in
|
|
<m/bgp_protocol_name/</cf> for manual call of revalidation of all routes.
|
|
|
|
<sect1>Supported transports
|
|
<p>
|
|
<itemize>
|
|
<item>Unprotected transport over TCP uses a port 323. The cache server
|
|
and BIRD router should be on the same trusted and controlled network
|
|
for security reasons.
|
|
<item>SSHv2 encrypted transport connection uses the normal SSH port
|
|
22.
|
|
</itemize>
|
|
|
|
<sect1>Configuration
|
|
|
|
<p>We currently support just one cache server per protocol. However you can
|
|
define more RPKI protocols generally.
|
|
|
|
<code>
|
|
protocol rpki [<name>] {
|
|
roa4 { table <tab>; };
|
|
roa6 { table <tab>; };
|
|
remote <ip> | "<domain>" [port <num>];
|
|
port <num>;
|
|
refresh [keep] <num>;
|
|
retry [keep] <num>;
|
|
expire [keep] <num>;
|
|
transport tcp;
|
|
transport ssh {
|
|
bird private key "</path/to/id_rsa>";
|
|
remote public key "</path/to/known_host>";
|
|
user "<name>";
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<p>Alse note that you have to specify the ROA channel. If you want to import
|
|
only IPv4 prefixes you have to specify only roa4 channel. Similarly with IPv6
|
|
prefixes only. If you want to fetch both IPv4 and even IPv6 ROAs you have to
|
|
specify both channels.
|
|
|
|
<sect2>RPKI protocol options
|
|
<p>
|
|
<descrip>
|
|
<tag>remote <m/ip/ | "<m/hostname/" [port <m/num/]</tag> Specifies
|
|
a destination address of the cache server. Can be specified by an IP
|
|
address or by full domain name string. Only one cache can be specified
|
|
per protocol. This option is required.
|
|
|
|
<tag>port <m/num/</tag> Specifies the port number. The default port
|
|
number is 323 for transport without any encryption and 22 for transport
|
|
with SSH encryption.
|
|
|
|
<tag>refresh [keep] <m/num/</tag> Time period in seconds. Tells how
|
|
long to wait before next attempting to poll the cache using a Serial
|
|
Query or a Reset Query packet. Must be lower than 86400 seconds (one
|
|
day). Too low value can caused a false positive detection of
|
|
network connection problems. A keyword <cf/keep/ suppresses updating
|
|
this value by a cache server.
|
|
Default: 3600 seconds
|
|
|
|
<tag>retry [keep] <m/num/</tag> Time period in seconds between a failed
|
|
Serial/Reset Query and a next attempt. Maximum allowed value is 7200
|
|
seconds (two hours). Too low value can caused a false positive
|
|
detection of network connection problems. A keyword <cf/keep/
|
|
suppresses updating this value by a cache server.
|
|
Default: 600 seconds
|
|
|
|
<tag>expire [keep] <m/num/</tag> Time period in seconds. Received
|
|
records are deleted if the client was unable to successfully refresh
|
|
data for this time period. Must be in range from 600 seconds (ten
|
|
minutes) to 172800 seconds (two days). A keyword <cf/keep/
|
|
suppresses updating this value by a cache server.
|
|
Default: 7200 seconds
|
|
|
|
<tag>ignore max length <m/switch/</tag>
|
|
Ignore received max length in ROA records and use max value (32 or 128)
|
|
instead. This may be useful for implementing loose RPKI check for
|
|
blackholes. Default: disabled.
|
|
|
|
<tag>transport tcp</tag> Unprotected transport over TCP. It's a default
|
|
transport. Should be used only on secure private networks.
|
|
Default: tcp
|
|
|
|
<tag>transport ssh { <m/SSH transport options.../ }</tag> It enables a
|
|
SSHv2 transport encryption. Cannot be combined with a TCP transport.
|
|
Default: off
|
|
</descrip>
|
|
|
|
<sect3>SSH transport options
|
|
<p>
|
|
<descrip>
|
|
<tag>bird private key "<m>/path/to/id_rsa</m>"</tag>
|
|
A path to the BIRD's private SSH key for authentication.
|
|
It can be a <cf><m>id_rsa</m></cf> file.
|
|
|
|
<tag>remote public key "<m>/path/to/known_host</m>"</tag>
|
|
A path to the cache's public SSH key for verification identity
|
|
of the cache server. It could be a path to <cf><m>known_host</m></cf> file.
|
|
|
|
<tag>user "<m/name/"</tag>
|
|
A SSH user name for authentication. This option is a required.
|
|
</descrip>
|
|
|
|
<sect1>Examples
|
|
<sect2>BGP origin validation
|
|
<p>Policy: Don't import <cf/ROA_INVALID/ routes.
|
|
<code>
|
|
roa4 table r4;
|
|
roa6 table r6;
|
|
|
|
protocol rpki {
|
|
debug all;
|
|
|
|
roa4 { table r4; };
|
|
roa6 { table r6; };
|
|
|
|
# Please, do not use rpki-validator.realmv6.org in production
|
|
remote "rpki-validator.realmv6.org" port 8282;
|
|
|
|
retry keep 5;
|
|
refresh keep 30;
|
|
expire 600;
|
|
}
|
|
|
|
filter peer_in_v4 {
|
|
if (roa_check(r4, net, bgp_path.last) = ROA_INVALID) then
|
|
{
|
|
print "Ignore RPKI invalid ", net, " for ASN ", bgp_path.last;
|
|
reject;
|
|
}
|
|
accept;
|
|
}
|
|
|
|
protocol bgp {
|
|
debug all;
|
|
local as 65000;
|
|
neighbor 192.168.2.1 as 65001;
|
|
ipv4 {
|
|
import filter peer_in_v4;
|
|
export none;
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<sect2>SSHv2 transport encryption
|
|
<p>
|
|
<code>
|
|
roa4 table r4;
|
|
roa6 table r6;
|
|
|
|
protocol rpki {
|
|
debug all;
|
|
|
|
roa4 { table r4; };
|
|
roa6 { table r6; };
|
|
|
|
remote 127.0.0.1 port 2345;
|
|
transport ssh {
|
|
bird private key "/home/birdgeek/.ssh/id_rsa";
|
|
remote public key "/home/birdgeek/.ssh/known_hosts";
|
|
user "birdgeek";
|
|
};
|
|
|
|
# Default interval values
|
|
}
|
|
</code>
|
|
|
|
|
|
<sect>Static
|
|
<label id="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 classes of definitions in Static protocol configuration --
|
|
global options, static route definitions, and per-route options. Usually, the
|
|
definition of the protocol contains mainly a list of static routes. Static
|
|
routes have no specific attributes, but <ref id="rta-igp-metric" name="igp_metric">
|
|
attribute is used to compare static routes with the same preference.
|
|
|
|
<p>The list of static routes may contain multiple routes for the same network
|
|
(usually, but not necessary, distinquished by <cf/preference/ or <cf/igp_metric/),
|
|
but only routes of the same network type are allowed, as the static protocol
|
|
has just one channel. E.g., to have both IPv4 and IPv6 static routes, define two
|
|
static protocols, each with appropriate routes and channel.
|
|
|
|
<p>Global options:
|
|
|
|
<descrip>
|
|
<tag><label id="static-check-link">check link <m/switch/</tag>
|
|
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.
|
|
|
|
<tag><label id="static-igp-table">igp table <m/name/</tag>
|
|
Specifies a table that is used for route table lookups of recursive
|
|
routes. Default: the same table as the protocol is connected to.
|
|
</descrip>
|
|
|
|
<p>Route definitions (each may also contain a block of per-route options):
|
|
|
|
<sect1>Regular routes; MPLS switching rules
|
|
|
|
<p>There exist several types of routes; keep in mind that <m/prefix/ syntax is
|
|
<ref id="type-prefix" name="dependent on network type">.
|
|
|
|
<descrip>
|
|
<tag>route <m/prefix/ via <m/ip/|<m/"interface"/ [<m/per-nexthop options/] [via ...]</tag>
|
|
Regular routes may bear one or more <ref id="route-next-hop" name="next hops">.
|
|
Every next hop is preceded by <cf/via/ and configured as shown.
|
|
|
|
<tag>route <m/prefix/ recursive <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag>
|
|
Recursive nexthop resolves the given IP in the configured IGP table and
|
|
uses that route's next hop. The MPLS stacks are concatenated; on top is
|
|
the IGP's nexthop stack and on bottom is this route's stack.
|
|
|
|
<tag>route <m/prefix/ blackhole|unreachable|prohibit</tag>
|
|
Special routes specifying to silently drop the packet, return it as
|
|
unreachable or return it as administratively prohibited. First two
|
|
targets are also known as <cf/drop/ and <cf/reject/.
|
|
</descrip>
|
|
|
|
<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.
|
|
|
|
<sect2>Per-nexthop options
|
|
|
|
<p>There are several options that in a case of multipath route are per-nexthop
|
|
(i.e., they can be used multiple times for a route, one time for each nexthop).
|
|
Syntactically, they are not separate options but just parts of <cf/route/
|
|
statement after each <cf/via/ statement, not separated by semicolons. E.g.,
|
|
statement <cf/route 10.0.0.0/8 via 192.0.2.1 bfd weight 1 via 192.0.2.2 weight
|
|
2;/ describes a route with two nexthops, the first nexthop has two per-nexthop
|
|
options (<cf/bfd/ and <cf/weight 1/), the second nexthop has just <cf/weight 2/.
|
|
|
|
<descrip>
|
|
<tag><label id="static-route-bfd">bfd <m/switch/</tag>
|
|
The Static protocol could use BFD protocol for next hop liveness
|
|
detection. If enabled, a BFD session to the route next hop is created
|
|
and the static route is BFD-controlled -- the static route is announced
|
|
only if the next hop liveness is confirmed by BFD. If the BFD session
|
|
fails, the static route (or just the affected nexthop from multiple
|
|
ones) is removed. Note that this is a bit different compared to other
|
|
protocols, which may use BFD as an advisory mechanism for fast failure
|
|
detection but ignore it if a BFD session is not even established. Note
|
|
that BFD protocol also has to be configured, see <ref id="bfd" name="BFD">
|
|
section for details. Default value is no.
|
|
|
|
<tag><label id="static-route-mpls">mpls <m/num/[/<m/num/[/<m/num/[...]]]</tag>
|
|
MPLS labels that should be pushed to packets forwarded by the route.
|
|
The option could be used for both IP routes (on MPLS ingress routers)
|
|
and MPLS switching rules (on MPLS transit routers). Default value is
|
|
no labels.
|
|
|
|
<tag><label id="static-route-onlink">onlink <m/switch/</tag>
|
|
Onlink flag means that the specified nexthop is accessible on the
|
|
(specified) interface regardless of IP prefixes of the interface. The
|
|
interface must be attached to nexthop IP address using link-local-scope
|
|
format (e.g. <cf/192.0.2.1%eth0/). Default value is no.
|
|
|
|
<tag><label id="static-route-weight">weight <m/switch/</tag>
|
|
For multipath routes, this value specifies a relative weight of the
|
|
nexthop. Allowed values are 1-256. Default value is 1.
|
|
</descrip>
|
|
|
|
<sect1>Route Origin Authorization
|
|
|
|
<p>The ROA config is just <cf>route <m/prefix/ max <m/int/ as <m/int/</cf> with no nexthop.
|
|
|
|
<sect1>Flowspec
|
|
<label id="flowspec-network-type">
|
|
|
|
<p>The flow specification are rules for routers and firewalls for filtering
|
|
purpose. It is described by <rfc id="5575">. There are 3 types of arguments:
|
|
<m/inet4/ or <m/inet6/ prefixes, numeric matching expressions and bitmask
|
|
matching expressions.
|
|
|
|
Numeric matching is a matching sequence of numbers and ranges separeted by a
|
|
commas (<cf/,/) (e.g. <cf/10,20,30/). Ranges can be written using double dots
|
|
<cf/../ notation (e.g. <cf/80..90,120..124/). An alternative notation are
|
|
sequence of one or more pairs of relational operators and values separated by
|
|
logical operators <cf/&&/ or <cf/||/. Allowed relational operators are <cf/=/,
|
|
<cf/!=/, <cf/</, <cf/<=/, <cf/>/, <cf/>=/, <cf/true/ and <cf/false/.
|
|
|
|
Bitmask matching is written using <m/value/<cf>/</cf><m/mask/ or
|
|
<cf/!/<m/value/<cf>/</cf><m/mask/ pairs. It means that <cf/(/<m/data/ <cf/&/
|
|
<m/mask/<cf/)/ is or is not equal to <m/value/. It is also possible to use
|
|
multiple value/mask pairs connected by logical operators <cf/&&/ or <cf/||/.
|
|
Note that for negated matches, value must be either zero or equal to bitmask
|
|
(e.g. !0x0/0xf or !0xf/0xf, but not !0x3/0xf).
|
|
|
|
<sect2>IPv4 Flowspec
|
|
|
|
<p><descrip>
|
|
<tag><label id="flow-dst">dst <m/inet4/</tag>
|
|
Set a matching destination prefix (e.g. <cf>dst 192.168.0.0/16</cf>).
|
|
Only this option is mandatory in IPv4 Flowspec.
|
|
|
|
<tag><label id="flow-src">src <m/inet4/</tag>
|
|
Set a matching source prefix (e.g. <cf>src 10.0.0.0/8</cf>).
|
|
|
|
<tag><label id="flow-proto">proto <m/numbers-match/</tag>
|
|
Set a matching IP protocol numbers (e.g. <cf/proto 6/).
|
|
|
|
<tag><label id="flow-port">port <m/numbers-match/</tag>
|
|
Set a matching source or destination TCP/UDP port numbers (e.g.
|
|
<cf>port 1..1023,1194,3306</cf>).
|
|
|
|
<tag><label id="flow-dport">dport <m/numbers-match/</tag>
|
|
Set a matching destination port numbers (e.g. <cf>dport 49151</cf>).
|
|
|
|
<tag><label id="flow-sport">sport <m/numbers-match/</tag>
|
|
Set a matching source port numbers (e.g. <cf>sport = 0</cf>).
|
|
|
|
<tag><label id="flow-icmp-type">icmp type <m/numbers-match/</tag>
|
|
Set a matching type field number of an ICMP packet (e.g. <cf>icmp type
|
|
3</cf>)
|
|
|
|
<tag><label id="flow-icmp-code">icmp code <m/numbers-match/</tag>
|
|
Set a matching code field number of an ICMP packet (e.g. <cf>icmp code
|
|
1</cf>)
|
|
|
|
<tag><label id="flow-tcp-flags">tcp flags <m/bitmask-match/</tag>
|
|
Set a matching bitmask for TCP header flags (aka control bits) (e.g.
|
|
<cf>tcp flags 0x03/0x0f;</cf>). The maximum length of mask is 12 bits
|
|
(0xfff).
|
|
|
|
<tag><label id="flow-length">length <m/numbers-match/</tag>
|
|
Set a matching packet length (e.g. <cf>length > 1500</cf>)
|
|
|
|
<tag><label id="flow-dscp">dscp <m/numbers-match/</tag>
|
|
Set a matching DiffServ Code Point number (e.g. <cf>dscp 8..15</cf>).
|
|
|
|
<tag><label id="flow-fragment">fragment <m/fragmentation-type/</tag>
|
|
Set a matching type of packet fragmentation. Allowed fragmentation
|
|
types are <cf/dont_fragment/, <cf/is_fragment/, <cf/first_fragment/,
|
|
<cf/last_fragment/ (e.g. <cf>fragment is_fragment &&
|
|
!dont_fragment</cf>).
|
|
</descrip>
|
|
|
|
<p><code>
|
|
protocol static {
|
|
flow4;
|
|
|
|
route flow4 {
|
|
dst 10.0.0.0/8;
|
|
port > 24 && < 30 || 40..50,60..70,80 && >= 90;
|
|
tcp flags 0x03/0x0f;
|
|
length > 1024;
|
|
dscp = 63;
|
|
fragment dont_fragment, is_fragment || !first_fragment;
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<sect2>Differences for IPv6 Flowspec
|
|
|
|
<p>Flowspec IPv6 are same as Flowspec IPv4 with a few exceptions.
|
|
<itemize>
|
|
<item>Prefixes <m/inet6/ can be specified not only with prefix length,
|
|
but with prefix <cf/offset/ <m/num/ too (e.g.
|
|
<cf>::1234:5678:9800:0000/101 offset 64</cf>). Offset means to don't
|
|
care of <m/num/ first bits.
|
|
<item>IPv6 Flowspec hasn't mandatory any flowspec component.
|
|
<item>In IPv6 packets, there is a matching the last next header value
|
|
for a matching IP protocol number (e.g. <cf>next header 6</cf>).
|
|
<item>It is not possible to set <cf>dont_fragment</cf> as a type of
|
|
packet fragmentation.
|
|
</itemize>
|
|
|
|
<p><descrip>
|
|
<tag><label id="flow6-dst">dst <m/inet6/ [offset <m/num/]</tag>
|
|
Set a matching destination IPv6 prefix (e.g. <cf>dst
|
|
::1c77:3769:27ad:a11a/128 offset 64</cf>).
|
|
|
|
<tag><label id="flow6-src">src <m/inet6/ [offset <m/num/]</tag>
|
|
Set a matching source IPv6 prefix (e.g. <cf>src fe80::/64</cf>).
|
|
|
|
<tag><label id="flow6-next-header">next header <m/numbers-match/</tag>
|
|
Set a matching IP protocol numbers (e.g. <cf>next header != 6</cf>).
|
|
|
|
<tag><label id="flow6-label">label <m/bitmask-match/</tag>
|
|
Set a 20-bit bitmask for matching Flow Label field in IPv6 packets
|
|
(e.g. <cf>label 0x8e5/0x8e5</cf>).
|
|
</descrip>
|
|
|
|
<p><code>
|
|
protocol static {
|
|
flow6 { table myflow6; };
|
|
|
|
route flow6 {
|
|
dst fec0:1122:3344:5566:7788:99aa:bbcc:ddee/128;
|
|
src 0000:0000:0000:0001:1234:5678:9800:0000/101 offset 63;
|
|
next header = 23;
|
|
sport > 24 && < 30 || = 40 || 50,60,70..80;
|
|
dport = 50;
|
|
tcp flags 0x03/0x0f && !0/0xff || 0x33/0x33;
|
|
fragment !is_fragment || !first_fragment;
|
|
label 0xaaaa/0xaaaa && 0x33/0x33;
|
|
};
|
|
}
|
|
</code>
|
|
|
|
<sect1>Per-route options
|
|
<p>
|
|
<descrip>
|
|
<tag><label id="static-route-filter"><m/filter expression/</tag>
|
|
This is a special option that allows filter expressions to be configured
|
|
on per-route basis. Can be used multiple times. These expressions are
|
|
evaluated when the route is originated, similarly to the import filter
|
|
of the static protocol. This is especially useful for configuring route
|
|
attributes, e.g., <cf/ospf_metric1 = 100;/ for a route that will be
|
|
exported to the OSPF protocol.
|
|
</descrip>
|
|
|
|
<sect1>Example static configs
|
|
<label id="static-example">
|
|
|
|
<p><code>
|
|
protocol static {
|
|
ipv4 { table testable; }; # Connect to a non-default routing table
|
|
check link; # Advertise routes only if link is up
|
|
route 0.0.0.0/0 via 198.51.100.130; # Default route
|
|
route 10.0.0.0/8 # Multipath route
|
|
via 198.51.100.10 weight 2
|
|
via 198.51.100.20 bfd # BFD-controlled next hop
|
|
via 192.0.2.1;
|
|
route 203.0.113.0/24 blackhole; # Sink route
|
|
route 10.2.0.0/24 via "arc0"; # Secondary network
|
|
route 192.168.10.0/24 via 198.51.100.100 {
|
|
ospf_metric1 = 20; # Set extended attribute
|
|
};
|
|
route 192.168.11.0/24 via 198.51.100.100 {
|
|
ospf_metric2 = 100; # Set extended attribute
|
|
ospf_tag = 2; # Set extended attribute
|
|
};
|
|
route 192.168.12.0/24 via 198.51.100.100 {
|
|
bgp_community.add((65535, 65281)); # Set extended BGP attribute
|
|
bgp_large_community.add((64512, 1, 1)); # Set extended BGP attribute
|
|
};
|
|
}
|
|
|
|
protocol static {
|
|
ipv6; # Channel is mandatory
|
|
route 2001:db8:10::/48 via 2001:db8:1::1; # Route with global nexthop
|
|
route 2001:db8:20::/48 via fe80::10%eth0; # Route with link-local nexthop
|
|
route 2001:db8:30::/48 via fe80::20%'eth1.60'; # Iface with non-alphanumeric characters
|
|
route 2001:db8:40::/48 via "eth2"; # Direct route to eth2
|
|
route 2001:db8::/32 unreachable; # Unreachable route
|
|
route ::/0 via 2001:db8:1::1 bfd; # BFD-controlled default route
|
|
}
|
|
</code>
|
|
|
|
|
|
<chapt>Conclusions
|
|
<label id="conclusion">
|
|
|
|
<sect>Future work
|
|
<label id="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>Opaque LSA's
|
|
<item>Route aggregation and flap dampening
|
|
<item>Multicast routing protocols
|
|
<item>Ports to other systems
|
|
</itemize>
|
|
|
|
|
|
<sect>Getting more help
|
|
<label id="help">
|
|
|
|
<p>If you use BIRD, you're welcome to join the bird-users mailing list
|
|
(<HTMLURL URL="mailto:bird-users@network.cz" name="bird-users@network.cz">)
|
|
where you can share your experiences with the other users and consult
|
|
your problems with the authors. To subscribe to the list, visit
|
|
<HTMLURL URL="http://bird.network.cz/?m_list" name="http://bird.network.cz/?m_list">.
|
|
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
|
|
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
|
|
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
|
|
-->
|