Ondrej Filip <it/<feela@network.cz>/,
Pavel Machek <it/<pavel@ucw.cz>/,
Martin Mares <it/<mj@ucw.cz>/,
-Jan Matejka <it/<mq@jmq.cz>/,
+Maria Matejka <it/<mq@jmq.cz>/,
Ondrej Zajicek <it/<santiago@crfreenet.org>/
</author>
use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
<tag><label id="argv-debug">-d</tag>
- enable debug messages and run bird in foreground.
+ enable debug messages to stderr, and run bird in foreground.
- <tag><label id="argv-log-file">-D <m/filename of debug log/</tag>
- log debugging information to given file instead of stderr.
+ <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.
<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">
include "tablename.conf";;
</code>
- <tag><label id="opt-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag>
- Set logging of messages having the given class (either <cf/all/ or
- <cf/{ error|trace [, <m/.../] }/ etc.) into selected destination (a file specified
- as a filename string, syslog with optional name argument, or the stderr
- output). Classes are:
+ <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.
+ 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 <cf/debug/ in the
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>
+ Define a custom route attribute. You can set and get it in filters like
+ any other route atribute. 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
<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 route all' command.
+ part of the output of 'show protocols all' command.
<tag><label id="proto-vrf">vrf "<m/text/"</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. Appropriate VRF interface must exist on OS level. For kernel
protocol, an appropriate table still must be explicitly selected by
- <cf/table/ option. Note that the VRF support in BIRD and Linux kernel
- (4.11) is still in development and is currently problematic outside of
- multihop BGP.
+ <cf/table/ option. Note that for proper VRF support it is necessary to
+ use Linux kernel version at least 4.14, older versions have limited VRF
+ implementation.
<tag><label id="proto-channel"><m/channel name/ [{<m/channel config/}]</tag>
Every channel must be explicitly stated. See the protocol-specific
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,
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.
+
<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
lclists, with LCs instead of pairs as arguments.
</descrip>
+
<sect>Operators
<label id="operators">
<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. Read-only.
+ 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
The optional attribute that can be used to specify a distance to the
network for routes that do not have a native protocol metric attribute
(like <cf/ospf_metric1/ for OSPF routes). It is used mainly by BGP to
- compare internal distances to boundary routers (see below). It is also
- used when the route is exported to OSPF as a default value for OSPF type
- 1 metric.
+ compare internal distances to boundary routers (see below).
</descrip>
<p>There also exist protocol-specific attributes which are described in the
routes over the same IPv6 transport. For sending and receiving Babel packets,
only a link-local IPv6 address is needed.
-<p>BIRD does not implement any Babel extensions, but will coexist with
-implementations using extensions (and will just ignore extension messages).
+<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>Babel supports no global configuration options apart from those common to all
-other protocols, but supports the following per-interface configuration options:
+<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 { <channel config> };
+ ipv6 [sadr] { <channel config> };
+ randomize router id <switch>;
interface <interface pattern> {
type <wired|wireless>;
rxcost <number>;
</code>
<descrip>
- <tag><label id="babel-channel">ipv4|ipv6 <m/channel config/</tag>
- The supported channels are IPv4 and IPv6.
+ <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
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
+ 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
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 for next hop calculation and as a
- source address for the BGP session. Default: the address of the local
- end of the interface our neighbor is connected to.
+ 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-strict-bind">strict bind <m/switch/</tag>
Specify whether BGP listening socket should be bound to a specific local
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></tag>
+ <tag><label id="bgp-bfd">bfd <M>switch</M>|graceful</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. Note that BFD protocol also has to be configured, see
- <ref id="bfd" name="BFD"> section for details. Default: disabled.
+ 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. 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
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,
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
<p>BGP channels have additional config options (together with the common ones):
<descrip>
- <tag><label id="bgp-next-hop-keep">next hop keep</tag>
- Forward the received Next Hop attribute even in situations where the
- local address should be used instead, like when the route is sent to an
- interface with a different subnet. Default: disabled.
-
- <tag><label id="bgp-next-hop-self">next hop self</tag>
- Avoid calculation of the Next Hop attribute and always advertise our own
- source address as a next hop. This needs to be used only occasionally to
- circumvent misconfigurations of other routers. Default: disabled.
+ <tag><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>
- Avoid calculation of the Next Hop attribute and always advertise this address
- as a next hop.
+ 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-missing-lladdr">missing lladdr self|drop|ignore</tag>
Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6
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-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
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-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
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
some of them (marked with `<tt/O/') are optional.
<descrip>
- <tag><label id="rta-bgp-path">bgppath bgp_path/</tag>
+ <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>
+ <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>
+ <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
external BGP instance. See <rfc id="4451"> for further discussion of
BGP MED attribute.
- <tag><label id="rta-bgp-origin">enum bgp_origin/</tag>
+ <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>
+ <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>
+ <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.
<!-- we don't handle aggregators right since they are of a very obscure type
<tag>bgp_aggregator</tag>
-->
- <tag><label id="rta-bgp-community">clist bgp_community/ [O]</tag>
+ <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
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>
+ <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 <cf/bgp_large_community/ [O]</tag>
+ <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,
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>
+ <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>
+ <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.
</descrip>
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"
<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.
+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. Although
-there are some use cases that use the direct protocol (like abusing eBGP as an
-IGP routing protocol), in most cases it is not needed to have these device
-routes in BIRD routing table and to use the direct protocol.
-
-<p>There is one notable case when you definitely want to use the direct protocol
--- running BIRD on BSD systems. Having high priority device routes for directly
-connected networks from the direct protocol protects kernel device routes from
-being overwritten or removed by IGP routes during some transient network
-conditions, because a lower priority IGP route for the same network is not
-exported to the kernel routing table. This is an issue on BSD systems only, as
-on Linux systems BIRD cannot change non-BIRD route in the kernel routing table.
+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:
on the <cf/learn/ switch, such routes are either ignored or accepted to our
table).
-<p>Unfortunately, there is one thing that makes the routing table synchronization
-a bit more complicated. In the kernel routing table there are also device routes
-for directly connected networks. These routes are usually managed by OS itself
-(as a part of IP address configuration) and we don't want to touch that. They
-are completely ignored during the scan of the kernel tables and also the export
-of device routes from BIRD tables to kernel routing tables is restricted to
-prevent accidental interference. This restriction can be disabled using
-<cf/device routes/ switch.
+<p>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
(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 of them
-can be configured in each protocol instance.
+<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">
these attributes:
<descrip>
- <tag><label id="rta-krt-source">int krt_source/</tag>
+ <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)
+ <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)
+ <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)
+ <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)
+ <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
</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">
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
<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-secondary">secondary <M>switch</M></tag>
- On BSD systems, older versions of BIRD supported OSPFv2 only for the
- primary IP address of an interface, other IP ranges on the interface
- were handled as stub networks. Since v1.4.1, regular operation on
- secondary IP addresses is supported, but disabled by default for
- compatibility. This option allows to enable it. The option is a
- transitional measure, will be removed in the next major release as the
- behavior will be changed. On Linux systems, the option is irrelevant, as
- operation on non-primary addresses is already the regular behavior.
-
<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
with internal <cf/metric/, a <cf/metric of type 2/ is always longer than any
<cf/metric of type 1/ or any <cf/internal metric/. <cf/Internal metric/ or
<cf/metric of type 1/ is stored in attribute <cf/ospf_metric1/, <cf/metric type
-2/ is stored in attribute <cf/ospf_metric2/. If you specify both metrics only
-metric1 is used.
+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
}
</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">
the secondary one, import filters control the opposite direction. Both tables
must be of the same nettype.
-<p>The Pipe protocol may work in the transparent mode mode or in the opaque
-mode. In the transparent mode, the Pipe protocol retransmits all routes from
-one table to the other table, retaining their original source and attributes.
-If import and export filters are set to accept, then both tables would have
-the same content. The transparent mode is the default mode.
-
-<p>In the opaque mode, the Pipe protocol retransmits optimal route from one
-table to the other table in a similar way like other protocols send and receive
-routes. Retransmitted route will have the source set to the Pipe protocol, which
-may limit access to protocol specific route attributes. This mode is mainly for
-compatibility, it is not suggested for new configs. The mode can be changed by
-<tt/mode/ option.
+<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
<p>RAdv defines two route attributes:
<descrip>
- <tag><label id="rta-ra-preference">enum ra_preference/</tag>
+ <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>
+ <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">
<p>RIP defines two route attributes:
<descrip>
- <tag>int <cf/rip_metric/</tag>
+ <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>
+ <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
<sect>RPKI
+<label id="rpki">
<sect1>Introduction
projects / thirdparty / bird.git / blobdiff