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.
(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">
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 followed by any
-combination of letters and numbers (e.g. <cf/R123/, <cf/myfilter/, <cf/bgp5/) or
-you can enclose the name into apostrophes (<cf/'/) and than you can use any
-combination of numbers, letters. hyphens, dots and colons (e.g.
-<cf/'1:strange-name'/, <cf/'-NAME-'/, <cf/'cool::name'/).
+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
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>
+ 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
<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>
+ <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. 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 for proper VRF support it is necessary to
- use Linux kernel version at least 4.14, older versions have limited VRF
- implementation.
+ 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
on all interfaces that have address from 192.168.0.0/16, but not from
192.168.1.0/24.
- <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
- on all interfaces that have address from 192.168.0.0/16, but not from
- 192.168.1.0/24.
-
<cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all
ethernet interfaces that have address from 192.168.1.0/24.
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,
<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.
<p>As you can see, a filter has a header, a list of local variables, and a body.
The header consists of the <cf/filter/ keyword followed by a (unique) name of
filter. The list of local variables consists of <cf><M>type name</M>;</cf>
-pairs where each pair defines one local variable. The body consists of <cf>
+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
values using the <cf>return <m/[expr]/</cf> command. Returning a value exits
from current function (this is similar to C).
-<p>Filters are declared in a way similar to functions except they can't have
+<p>Filters are defined in a way similar to functions except they can't have
explicit parameters. They get a route table entry as an implicit parameter, it
is also passed automatically to any functions called. The filter must terminate
with either <cf/accept/ or <cf/reject/ statement. If there's a runtime error in
<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 in the
-foot).
+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 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_ip4</cf>
- which returns <cf/bool/. IP addresses are written in the standard
+ 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
but <tt>bgp_path ˜ [= * 4 5 * =]</tt> is false. BGP mask
expressions can also contain integer expressions enclosed in parenthesis
and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. You can
- also use ranges, for example <tt>[= * 3..5 2 100..200 * =]</tt>.
+ 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
<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>
+ <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/˜/
<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 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,
+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
<label id="route-attributes">
<p>A filter is implicitly passed a route, and it can access its attributes just
-like it accesses variables. Attempts to access undefined attribute result in a
-runtime error; you can check if an attribute is defined by using the
-<cf>defined( <m>attribute</m> )</cf> operator. One notable exception to this
-rule are attributes of bgppath and *clist types, where undefined value is
-regarded as empty bgppath/*clist for most purposes.
+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>
<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
-corresponding protocol sections.
+<p>Protocol-specific route attributes are described in the corresponding
+protocol sections.
<sect>Other statements
<descrip>
<tag><label id="assignment"><m/variable/ = <m/expr/</tag>
- Set variable to a given value.
+ 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>.
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">.
-We currently support at most one protocol instance.
<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>
+<cf>/proc/sys/net/ipv4/ip_local_port_range</cf>.
<sect1>Configuration
<label id="bfd-config">
<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.
+<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
<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
<cf/local 10.0.0.1; local as 65000;/ are valid). This parameter is
mandatory.
- <tag><label id="bgp-neighbor">neighbor [<m/ip/] [port <m/number/] [as <m/number/]</tag>
+ <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. 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.
+ 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.
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-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
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
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
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,
<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 to allow extended messages with length up
- to 65535 bytes. Default: off.
+ 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
<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-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>
- 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-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
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
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-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
<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.
</descrip>
<sect1>Example
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"
Direct protocol is necessary for distance-vector protocols like RIP or Babel to
announce local networks.
-<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.
-
<p>There are just few configuration options for the Direct protocol:
<p><descrip>
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
</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">
tick <num>;
ecmp <switch> [limit <num>];
merge external <switch>;
+ graceful restart <switch>|aware;
+ graceful restart time <num>;
area <id> {
stub;
nssa;
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
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
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 returnsd to suppressed
+ 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.
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
filter peer_in_v4 {
if (roa_check(r4, net, bgp_path.last) = ROA_INVALID) then
{
- print "Ignore invalid ROA ", net, " for ASN ", bgp_path.last;
+ print "Ignore RPKI invalid ", net, " for ASN ", bgp_path.last;
reject;
}
accept;
projects / thirdparty / bird.git / blobdiff