(set-fill-column 80)
- Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
+ Copyright 1999 - 2022 CZ.NIC, z.s.p.o , distribute under GPL version 2 or later.
-->
<title>BIRD 2.0 User's Guide
<author>
Ondrej Filip <it/<feela@network.cz>/,
-Pavel Machek <it/<pavel@ucw.cz>/,
Martin Mares <it/<mj@ucw.cz>/,
Maria Matejka <it/<mq@jmq.cz>/,
Ondrej Zajicek <it/<santiago@crfreenet.org>/
</itemize>
<p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected
-route from a list of entries for one network. But if the <cf/sorted/ option is
-activated, these lists of entries are kept completely sorted (according to
-preference or some protocol-dependent metric). This is needed for some features
-of some protocols (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.
+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">
<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/.
+<p>MPLS routes control MPLS forwarding in the same way as IP routes control IP
+forwarding. MPLS-aware routing protocols produce both labeled IP routes and
+corresponding MPLS routes. Configuration keyword is <cf/mpls/.
<itemize>
<item>(PK) MPLS label
are notified about planned graceful restart and routes are kept in kernel table
after shutdown.
+<sect>MPLS
+<label id="mpls">
+
+<p>Multiprotocol Label Switching (MPLS) is a networking technology which works
+below IP routing but above the link (e.g. ethernet) layer. It is described in
+<rfc id="3031">.
+
+In regular IP forwarding, the destination address of a packet is independently
+examined in each hop, a route with longest prefix match is selected from the
+routing table, and packet is processed accordingly. In general, there is no
+difference between border routers and internal routers w.r.t. IP forwarding.
+
+In MPLS forwarding, when a packet enters the network, it is classified (based on
+destination address, ingress interface and other factors) into one of forwarding
+equivalence classes (FECs), then a header with a MPLS label identifying the FEC
+is attached to it, and the packet is forwarded. In internal routers, only the
+MPLS label is examined, the matching MPLS route is selected from the MPLS
+routing table, and the packet is processed accordingly. The specific value of
+MPLS label has local meaning only and may change between hops (that is why it is
+called label switching). When the packet leaves the network, the MPLS header is
+removed.
+
+The advantage of the MPLS approach is that other factors than the destination
+address can be considered and used consistently in the whole network, for
+example IP traffic with multiple overlapping private address ranges could be
+mixed together, or particular paths for specific flows could be defined. Another
+advantage is that MPLS forwarding by internal routers can be much simpler than
+IP forwarding, as instead of the longest prefix match algorithm it uses simpler
+exact match for MPLS route selection. The disadvantage is additional complexity
+in signaling. For further details, see <rfc id="3031">.
+
+MPLS-aware routing protocols not only distribute IP routing information, but
+they also distribute labels. Therefore, they produce labeled routes - routes
+representing label switched paths (LSPs) through the MPLS domain. Such routes
+have IP prefix and next hop address like regular (non-labeled) routes, but they
+also have local MPLS label (in route attribute <ref id="rta-mpls-label"
+name="mpls_label">) and outgoing MPLS label (as a part of the next hop). They
+are stored in regular IP routing tables.
+
+Labeled routes are used for exchange of routing information between routing
+protocols and for ingress (IP -> MPLS) forwarding, but they are not directly
+used for MPLS forwarding. For that purpose <ref id="mpls-routes" name="MPLS
+routes"> are used. These are routes that have local MPLS label as a primary key
+and they are stored in the MPLS routing table.
+
+In BIRD, the whole process generally works this way: A MPLS-aware routing
+protocol (say BGP) receives routing information including remote label. It
+produces a route with attribute <ref id="rta-mpls-policy" name="mpls_policy">
+specifying desired <ref id="mpls-channel-label-policy" name="MPLS label policy">.
+Such route then passes the import filter (which could modify the MPLS label
+policy or perhaps assign a static label) and when it is accepted, a local MPLS
+label is selected (according to the label policy) and attached to the route,
+producing labeled route. When a new MPLS label is allocated, the MPLS-aware
+protocol automatically produces corresponding MPLS route. When all labeled
+routes that use specific local MPLS label are retracted, the corresponding MPLS
+route is retracted too.
+
+There are three important concepts for MPLS in BIRD: MPLS domains, MPLS tables
+and MPLS channels. MPLS domain represents an independent label space, all
+MPLS-aware protocols are associated with some MPLS domain. It is responsible for
+label management, handling label allocation requests from MPLS-aware protocols.
+MPLS table is just a routing table for MPLS routes. Routers usually have one
+MPLS domain and one MPLS table, with Kernel protocol to export MPLS routes into
+kernel FIB.
+
+MPLS channels make protocols MPLS-aware, they are responsible for keeping track
+of active FECs (and corresponding allocated labels), selecting FECs / local
+labels for labeled routes, and maintaining correspondence between labeled routes
+and MPLS routes.
+
+Note that local labels are allocated to individual MPLS-aware protocols and
+therefore it is not possible to share local labels between different protocols.
+
<chapt>Configuration
<label id="config">
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>
+ <tag><label id="opt-log">log "<m/filename/" [<m/limit/ "<m/backup/"] | syslog [name <m/name/] | stderr | udp <m/address/ [port <m/port/] 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.
+ syslog (with optional name argument), the stderr output, or as a UDP
+ message (in <rfc id="3164"> syslog format).
Classes are:
<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
See <ref id="channel-debug" name="debug"> in the channel section.
Default: off.
+ <tag><label id="opt-debug-tables">debug tables all|off|{ states|routes|filters|events [, <m/.../] }</tag>
+ Set global defaults of table debugging options.
+ See <ref id="table-debug" name="debug"> in the table 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
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>
+ <tag><label id="opt-function">function <m/name/ (<m/parameters/) [ -> <m/return type/ ] <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>
<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/ [sorted]</tag>
- Create a new routing table. The default routing tables <cf/master4/ and
- <cf/master6/ are created implicitly, other routing tables have to be
- added by this command. Option <cf/sorted/ can be used to enable sorting
- of routes, see <ref id="dsc-table-sorted" name="sorted table">
- description for details.
+ <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-mpls-domain">mpls domain <m/name/ [ { <m/option/; [<m/.../] } ]</tag>
+ Define a new MPLS domain. MPLS domains represent independent label
+ spaces and are responsible for MPLS label management. All MPLS-aware
+ protocols are associated with some MPLS domain. See the <ref id="mpls-opts"
+ name="MPLS configuration section"> for MPLS domain 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="table-debug">debug all|off|{ states|routes|filters [, <m/.../] }</tag>
+ Set table debugging options. Like in <ref id="proto-debug"
+ name="protocol debugging">, tables are capable of writing trace
+ messages about its work to the log (with category <cf/trace/).
+ For now, this does nothing, but in version 3, it is used. Default: off.
+
+ <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">
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>password options</m> } ]</tag>
+ <tag><label id="proto-pass">password "<m/password/" | <m/bytestring/ [ { <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
authentication is enabled, authentication can be enabled by separate,
protocol-dependent <cf/authentication/ option.
- This option is allowed in BFD, OSPF and RIP protocols. BGP has also
- <cf/password/ option, but it is slightly different and described
- separately.
- Default: none.
+ A password can be specified as a string or as a sequence of hexadecimal
+ digit pairs (<ref id="type-bytestring" name="bytestring">).
+
+ 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:
<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>.
+ The format of <cf><m/time/</cf> is <tt>YYYY-MM-DD [hh:mm:ss[.sss]]</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-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 )</tag>
+ <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
- protocol it is HMAC-SHA-256.
+ For RIP and OSPFv2 it is Keyed-MD5 (for compatibility), for OSPFv3 and
+ Babel it is HMAC-SHA-256.
</descrip>
<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).
+ (except for EBGP and L3VPN).
<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.
</code>
+<sect>MPLS options
+<label id="mpls-opts">
+
+<p>The MPLS domain definition is mandatory for a MPLS router. All MPLS channels
+and MPLS-aware protocols are associated with some MPLS domain (although usually
+implicitly with the sole one). In the MPLS domain definition you can configure
+details of MPLS label allocation. Currently, there is just one option,
+<cf/label range/.
+
+<p>Note that the MPLS subsystem is experimental, it is likely that there will be
+some backward-incompatible changes in the future.
+
+<descrip>
+ <tag><label id="mpls-domain-label-range">label range <m/name/ { start <m/number/; length <m/number/; [<m/.../] }</tag>
+ Define a new label range, or redefine implicit label ranges <cf/static/
+ and <cf/dynamic/. MPLS channels use configured label ranges for dynamic
+ label allocation, while <cf/static/ label range is used for static label
+ allocation. The label range definition must specify the extent of the
+ range. By default, the range <cf/static/ is 16-1000, while the range
+ <cf/dynamic/ is 1000-10000.
+</descrip>
+
+<p>MPLS channel should be defined in each MPLS-aware protocol in addition to its
+regular channels. It is responsible for label allocation and for announcing MPLS
+routes to the MPLS routing table. Besides common <ref id="channel-opts"
+name="channel options">, MPLS channels have some specific options:
+
+<descrip>
+ <tag><label id="mpls-channel-domain">domain <m/name/</tag>
+ Specify a MPLS domain to which this channel and protocol belongs.
+ Default: The first defined MPLS domain.
+
+ <tag><label id="mpls-channel-label-range">label range <m/name/</tag>
+ Use specific label range for dynamic label allocation. Note that static
+ labels always use the range <cf/static/. Default: the range <cf/dynamic/.
+
+ <tag><label id="mpls-channel-label-policy">label policy static|prefix|aggregate|vrf</tag>
+ Label policy specifies how routes are grouped to forwarding equivalence
+ classes (FECs) and how labels are assigned to them.
+
+ The policy <cf/static/ means no dynamic label allocation is done, and
+ static labels must be set in import filters using the route attribute
+ <ref id="rta-mpls-label" name="mpls_label">.
+
+ The policy <cf/prefix/ means each prefix uses separate label associated
+ with that prefix. When a labeled route is updated, it keeps the label.
+ This policy is appropriate for IGPs.
+
+ The policy <cf/aggregate/ means routes are grouped to FECs according to
+ their next hops (including next hop labels), and one label is used for
+ all routes in the same FEC. When a labeled route is updated, it may
+ change next hop, change FEC and therefore change label. This policy is
+ appropriate for BGP.
+
+ The policy <cf/vrf/ is only valid in L3VPN protocols. It uses one label
+ for all routes from a VRF, while replacing the original next hop with
+ lookup in the VRF.
+
+ Default: <cf/prefix/.
+</descrip>
+
+<p>This is a trivial example of MPLS setup:
+<code>
+mpls domain mdom {
+ label range bgprange { start 2000; length 1000; };
+}
+
+mpls table mtab;
+
+protocol static {
+ ipv6;
+ mpls;
+
+ route 2001:db8:1:1/64 mpls 100 via 2001:db8:1:2::1/64 mpls 200;
+}
+
+protocol bgp {
+ # regular channels
+ ipv6 mpls { ... };
+ vpn6 mpls { ... };
+
+ # MPLS channel
+ mpls {
+ # domain mdom;
+ # table mtab;
+ label range bgprange;
+ label policy aggregate;
+ };
+
+ ...
+}
+</code>
+
+
<chapt>Remote control
<label id="remote-control">
<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-bfd-sessions">show bfd sessions [<m/name/] [address (<m/IP/|<m/prefix/)] [(interface|dev) "<m/name/"] [ipv4|ipv6] [direct|multihop] [all]</tag>
+ Show information about BFD sessions. Options could be used to filter
+ entries, or in the case of the option <cf/all/ to give verbose output.
<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>
+ <tag><label id="cli-show-route">show route [[(for|in)] <m/prefix/|for <m/IP/] [table (<m/t/|all)] [(import|export) table <m/p/.<m/c/] [filter <m/f/|where <m/cond/] [(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
+ destination. Finally, if you use <cf>in <m/prefix/</cf>, you get all
+ prefixes covered by the given prefix.
+ 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.
Last, the set of default tables is used: <cf/master4/, <cf/master6/ and
each first table of any other network type.
+ <p>There are internal tables when <cf/(import|export) table/ options
+ are used for some channels. They can be selected explicitly with
+ <cf/(import|export) table/ switch, specifying protocol <m/p/ and
+ channel name <m/c/.
+
<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>).
restarted otherwise. Changes in filters usually lead to restart of
affected protocols.
+ The previous configuration is saved and the user can switch back to it
+ with <ref id="cli-configure-undo" name="configure undo"> command. The
+ old saved configuration is released (even if the reconfiguration attempt
+ fails due to e.g. a syntax error).
+
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
<code>
filter not_too_far
-int var;
{
+ int var;
if defined( rip_metric ) then
var = rip_metric;
else {
(<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:
+<p>BIRD supports functions, so that you don not have to repeat the same blocks
+of code over and over. Functions can have zero or more parameters and they can
+have local variables. If the function returns value, then you should always
+specify its return type. Direct recursion is possible. Function definitions look
+like this:
<code>
-function name ()
-int local_variable;
+function name() -> int
{
- local_variable = 5;
+ int local_variable;
+ int another_variable = 5;
+ return 42;
}
-function with_parameters (int parameter)
+function with_parameters(int parameter) -> pair
{
print parameter;
+ return (1, 2);
}
</code>
-<p>Unlike in C, variables are declared after the <cf/function/ line, but before
-the first <cf/{/. You can't declare variables in nested blocks. Functions are
-called like in C: <cf>name(); with_parameters(5);</cf>. Function may return
-values using the <cf>return <m/[expr]/</cf> command. Returning a value exits
-from current function (this is similar to C).
-
-<p>Filters are 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
+<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 and cannot return. 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
+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>
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
!˜/) operators could be used to match a string value against
a shell pattern (represented also as a string).
+ <tag><label id="type-bytestring">bytestring</tag>
+ This is a sequences of arbitrary bytes. There are no ways to modify
+ bytestrings in filters. You can pass them between function, assign
+ them to variables of type <cf/bytestring/, print such values,
+ compare bytestings (<cf/=, !=/).
+
+ Bytestring literals are written as a sequence of hexadecimal digit
+ pairs, optionally colon-separated. A bytestring specified this way
+ must be either at least 16 bytes (32 digits) long, or prefixed by the
+ <cf/hex:/ prefix: <cf/01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef/,
+ <cf/0123456789abcdef0123456789abcdef/, <cf/hex:/, <cf/hex:12:34:56/,
+ <cf/hex:12345678/.
+
+ A bytestring can be made from a hex string using <cf/from_hex()/
+ function. Source strings can use any number of dots, colons, hyphens
+ and spaces as byte separators: <cf/from_hex(" 12.34 56:78 ab-cd-ef ")/.
+
<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.
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
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
+ identical and <cf>l <= len1 <= h</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
<cf><m/P/.len</cf> returns the length of path <m/P/.
- <cf><m/P/.empty</cf> makes the path <m/P/ empty.
+ <cf><m/P/.empty</cf> makes the path <m/P/ empty. Can't be used as a value, always modifies the object.
- <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and
+ <cf><m/P/.prepend(<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
+ <cf><m/P/.delete(<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/.
+ <cf><m/P/.filter(<m/A/)</cf> deletes all ASNs from path <m/P/ that are
+ not members of integer set <m/A/, and returns the result.
+ 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/.
+ Methods <cf>prepend</cf>, <cf>delete</cf> and <cf>filter</cf> keep the
+ original object intact as long as you use the result in any way. You can
+ also write e.g. <cf><m/P/.prepend(<m/A/);</cf> as a standalone statement.
+ This variant does modify the original object with the result of the operation.
<tag><label id="type-bgpmask">bgpmask</tag>
BGP masks are patterns used for BGP path matching (using <cf>path
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 three special operators on clists:
+ 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><m/C/.empty</cf> makes the list <m/C/ empty. Can't be used as a value, always modifies the object.
- <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and
+ <cf><m/C/.add(<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
+ <cf><m/C/.delete(<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
+ <cf><m/C/.filter(<m/P/)</cf> deletes all items from clist <m/C/ that are
+ not members of pair (or quad) set <m/P/, and returns the result. 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/.
+ Methods <cf>add</cf>, <cf>delete</cf> and <cf>filter</cf> keep the
+ original object intact as long as you use the result in any way. You can
+ also write e.g. <cf><m/P/.add(<m/A/);</cf> as a standalone statement.
+ This variant does modify the original object with the result of the operation.
+
+ <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
<sect>Control structures
<label id="control-structures">
-<p>Filters support two control structures: conditions and case switches.
+<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/;
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
<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";
}
-
-if 1234 = i then printn "."; else {
- print "not 1234";
- print "You need {} around multiple commands";
-}
</code>
<tag><label id="rta-source"><m/enum/ source</tag>
what protocol has told me about this route. Possible values:
- <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/,
+ <cf/RTS_STATIC/, <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/.
creation/removal. Zero is returned for routes with undefined outgoing
interfaces. Read-only.
+ <tag><label id="rta-onlink"><m/bool/ onlink</tag>
+ Onlink flag means that the specified nexthop is accessible on the
+ interface regardless of IP prefixes configured on the interface.
+ The attribute can be used to configure such next hops by first setting
+ <cf/onlink = true/ and <cf/ifname/, and then setting <cf/gw/. Possible
+ use case for setting this flag is to automatically build overlay IP-IP
+ networks on linux.
+
<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
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).
+
+ <tag><label id="rta-mpls-label"><m/int/ mpls_label</tag>
+ Local MPLS label attached to the route. This attribute is produced by
+ MPLS-aware protocols for labeled routes. It can also be set in import
+ filters to assign static labels, but that also requires static MPLS
+ label policy.
+
+ <tag><label id="rta-mpls-policy"><m/enum/ mpls_policy</tag>
+ For MPLS-aware protocols, this attribute defines which
+ <ref id="mpls-channel-label-policy" name="MPLS label policy"> will be
+ used for the route. It can be set in import filters to change it on
+ per-route basis. Valid values are <cf/MPLS_POLICY_NONE/ (no label),
+ <cf/MPLS_POLICY_STATIC/ (static label), <cf/MPLS_POLICY_PREFIX/
+ (per-prefix label), <cf/MPLS_POLICY_AGGREGATE/ (aggregated label),
+ and <cf/MPLS_POLICY_VRF/ (per-VRF label). See <ref
+ id="mpls-channel-label-policy" name="MPLS label policy"> for details.
+
+ <tag><label id="rta-mpls-class"><m/int/ mpls_class</tag>
+ When <ref id="mpls-channel-label-policy" name="MPLS label policy"> is
+ set to <cf/aggregate/, it may be useful to apply more fine-grained
+ aggregation than just one based on next hops. When routes have different
+ value of this attribute, they will not be aggregated under one local
+ label even if they have the same next hops.
</descrip>
<p>Protocol-specific route attributes are described in the corresponding
<chapt>Protocols
<label id="protocols">
+<sect>Aggregator
+<label id="aggregator">
+
+<sect1>Introduction
+<label id="aggregator-intro">
+<p>The Aggregator protocol explicitly merges routes by the given rules. There
+ are four phases of aggregation. First routes are filtered, then sorted into buckets,
+ then buckets are merged and finally the results are filtered once again.
+ Aggregating an already aggregated route is forbidden.
+
+<p>This is an experimental protocol, use with caution.
+
+<sect1>Configuration
+<label id="aggregator-config">
+<p><descrip>
+ <tag><label id="aggregator-table">table <m/table/</tag>
+ The table from which routes are exported to get aggregated.
+
+ <tag><label id="aggregator-export">export <m/.../</tag>
+ A standard channel's <cf/export/ clause, defining which routes are accepted into aggregation.
+
+ <tag><label id="aggregator-rule">aggregate on <m/expr/ | <m/attribute/ [<m/, .../]</tag>
+ All the given filter expressions and route attributes are evaluated for each route. Then routes
+ are sorted into buckets where <em/all/ values are the same. Note: due to performance reasons,
+ all filter expressions must return a compact type, e.g. integer, a BGP
+ (standard, extended, large) community or an IP address. If you need to compare e.g. modified
+ AS Paths in the aggregation rule, you can define a custom route attribute and set this attribute
+ in the export filter. For now, it's mandatory to say <cf/net/ here, we can't merge prefixes yet.
+
+ <tag><label id="aggregation-merge">merge by { <m/filter code/ }</tag>
+ The given filter code has an extra symbol defined: <cf/routes/. By iterating over <cf/routes/,
+ you get all the routes in the bucket and you can construct your new route. All attributes
+ selected in <cf/aggregate on/ are already set to the common values. For now, it's not possible
+ to use a named filter here. You have to finalize the route by calling <cf/accept/.
+
+ <tag><label id="aggregator-import">import <m/.../</tag>
+ Filter applied to the route after <cf/merge by/. Here you can use a named filter.
+
+ <tag><label id="aggregator-peer-table">peer table <m/table/</tag>
+ The table to which aggregated routes are imported. It may be the same table
+ as <cf/table/.
+</descrip>
+
+<sect1>Example
+<label id="aggregator-example">
+
+<p><code>
+protocol aggregator {
+ table master6;
+ export where defined(bgp_path);
+ /* Merge all routes with the same AS Path length */
+ aggregate on net, bgp_path.len;
+ merge by {
+ for route r in routes do {
+ if ! defined(bgp_path) then { bgp_path = r.bgp_path }
+ bgp_community = bgp_community.add(r.bgp_community);
+ }
+ accept;
+ };
+ import all;
+ peer table agr_result;
+}
+</code>
+
<sect>Babel
<label id="babel">
<label id="babel-intro">
<p>The Babel protocol
-(<rfc id="6126">) is a loop-avoiding distance-vector routing protocol that is
+(<rfc id="8966">) 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
ipv6 [sadr] { <channel config> };
randomize router id <switch>;
interface <interface pattern> {
- type <wired|wireless>;
+ type <wired|wireless|tunnel>;
rxcost <number>;
limit <number>;
hello interval <time>;
check link <switch>;
next hop ipv4 <address>;
next hop ipv6 <address>;
+ extended next hop <switch>;
+ rtt cost <number>;
+ rtt min <time>;
+ rtt max <time>;
+ rtt decay <number>;
+ send timestamps <switch>;
+ 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>
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
+ <tag><label id="babel-type">type wired|wireless|tunnel </tag>
+ This option specifies the interface type: Wired, wireless or tunnel. 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/.
+ the more binary up/down mechanism of wired type links. A tunnel is like a
+ wired interface, but turns on RTT-based metrics with a default cost of 96.
+ Default: <cf/wired/.
<tag><label id="babel-rxcost">rxcost <m/num/</tag>
This option specifies the nominal RX cost of the interface. The effective
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-extended-next-hop">extended next hop <m/switch/</tag>
+ If enabled, BIRD will accept and emit IPv4 routes with an IPv6 next
+ hop when IPv4 addresses are absent from the interface as described in
+ <rfc id="9229">. Default: yes.
+
+ <tag><label id="babel-rtt-cost">rtt cost <m/number/</tag>
+ The RTT-based cost that will be applied to all routes from each neighbour
+ based on the measured RTT to that neighbour. If this value is set,
+ timestamps will be included in generated Babel Hello and IHU messages, and
+ (if the neighbours also have timestamps enabled), the RTT to each
+ neighbour will be computed. An additional cost is added to a neighbour if
+ its RTT is above the <ref id="babel-rtt-min" name="rtt min"> value
+ configured on the interface. The added cost scales linearly from 0 up to
+ the RTT cost configured in this option; the full cost is applied if the
+ neighbour RTT reaches the RTT configured in the <ref id="babel-rtt-max"
+ name="rtt max"> option (and for all RTTs above this value). Default: 0
+ (disabled), except for tunnel interfaces, where it is 96.
+
+ <tag><label id="babel-rtt-min">rtt min <m/time/ s|ms</tag>
+ The minimum RTT above which the RTT cost will start to be applied (scaling
+ linearly from zero up to the full cost). Default: 10 ms
+
+ <tag><label id="babel-rtt-max">rtt max <m/time/ s|ms</tag>
+ The maximum RTT above which the full RTT cost will start be applied.
+ Default: 120 ms
+
+ <tag><label id="babel-rtt-decay">rtt decay <m/number/</tag>
+ The decay factor used for the exponentional moving average of the RTT
+ samples from each neighbour, in units of 1/256. Higher values discards old
+ RTT samples faster. Must be between 1 and 256. Default: 42
+
+ <tag><label id="babel-send-timestamps">send timestamps <m/switch/</tag>
+ Whether to send the timestamps used for RTT calculation on this interface.
+ Sending the timestamps enables peers to calculate an RTT to this node,
+ even if no RTT cost is applied to the route metrics. Default: yes.
+
+ <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
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.
<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="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="8654"> - Extended Message Support for BGP
+<item> <rfc id="8950"> - Advertising IPv4 NLRI with an IPv6 Next Hop
+<item> <rfc id="9072"> - Extended Optional Parameters Length for BGP OPEN Message
+<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
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
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.
+ just the switch argument. All BFD session-specific options are allowed
+ 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
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
+ Standard BGP implementations 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,
+ 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.
+ The option does not affect IBGP sessions. Default: off.
+
+ <tag><label id="bgp-allow-med">allow bgp_med <m/switch/</tag>
+ Standard BGP implementations do not propagate the MULTI_EXIT_DESC
+ attribute unless it is configured locally. When this option is enabled
+ on an EBGP session, this attribute will be sent to the peer regardless,
+ 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
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
+ re-advertisement of all routes from its neighbor. This option
+ specifies whether BIRD advertises this capability and supports
related procedures. Note that even when disabled, BIRD can send route
- refresh requests. Default: on.
+ refresh requests. Disabling Route Refresh also disables Enhanced Route Refresh.
+ Default: on.
+
+ <tag><label id="bgp-require-route-refresh">require route refresh <m/switch/</tag>
+ If enabled, the BGP Route Refresh capability (<rfc id="2918">) must be
+ announced by the BGP neighbor, otherwise the BGP session will not be
+ established. Default: off.
+
+ <tag><label id="bgp-enable-enhanced-route-refresh">enable enhanced route refresh <m/switch/</tag>
+ BGP protocol extension Enhanced Route Refresh (<rfc id="7313">)
+ specifies explicit begin and end for Route Refresh (see previous
+ option), therefore the receiver can remove stale routes that were not
+ advertised during the exchange. This option specifies whether BIRD
+ advertises this capability and supports related procedures. Default: on.
+
+ <tag><label id="bgp-require-enhanced-route-refresh">require enhanced route refresh <m/switch/</tag>
+ If enabled, the BGP Enhanced Route Refresh capability (<rfc id="7313">)
+ must be announced by the BGP neighbor, otherwise the BGP session
+ will not be established. Default: off.
<tag><label id="bgp-graceful-restart">graceful restart <m/switch/|aware</tag>
When a BGP speaker restarts or crashes, neighbors will discard all
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
+ 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-require-graceful-restart">require graceful restart <m/switch/</tag>
+ If enabled, the BGP Graceful Restart capability (<rfc id="4724">)
+ must be announced by the BGP neighbor, otherwise the BGP session
+ will not be established. Default: off.
+
<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
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
+ 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-require-long-lived-graceful-restart">require long lived graceful restart <m/switch/</tag>
+ If enabled, the BGP Long-lived Graceful Restart capability (draft)
+ must be announced by the BGP neighbor, otherwise the BGP session
+ will not be established. Default: off.
+
<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,
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-require-as4">require as4 <m/switch/</tag>
+ If enabled, the BGP 4B AS number capability (<rfc id="6793">) must be
+ announced by the BGP neighbor, otherwise the BGP session will not be
+ established. Default: off.
+
<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-require-extended-messages">require extended messages <m/switch/</tag>
+ If enabled, the BGP Extended Message capability (<rfc id="8654">) must
+ be announced by the BGP neighbor, otherwise the BGP session will not be
+ established. 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
disabled. Default: on, with automatic fallback to off when received
capability-related error.
- <tag><label id="bgp-advertise-ipv4">advertise ipv4 <m/switch/</tag>
- Advertise IPv4 multiprotocol capability. This is not a correct behavior
- according to the strict interpretation of <rfc id="4760">, but it is
- widespread and required by some BGP implementations (Cisco and Quagga).
- This option is relevant to IPv4 mode with enabled capability
- advertisement only. Default: on.
-
<tag><label id="bgp-advertise-hostname">advertise hostname <m/switch/</tag>
- Advertise hostname capability along with the hostname. Default: off.
+ Advertise the hostname capability along with the hostname. Default: off.
+
+ <tag><label id="bgp-require-hostname">require hostname <m/switch/</tag>
+ If enabled, the hostname capability must be announced by the BGP
+ neighbor, otherwise the BGP session negotiation fails. 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),
<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.
+ before considering the connection stale. The effective value is
+ negotiated during session establishment and it is a minimum of this
+ configured value and the value proposed by the peer. The zero value has
+ a special meaning, signifying that no keepalives are used. Default: 240
+ seconds.
+
+ <tag><label id="bgp-min-hold-time">min hold time <m/number/</tag>
+ Minimum value of the hold time that is accepted during session negotiation.
+ If the peer proposes a lower value, the session is rejected with error.
+ Default: none.
<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
<tag><label id="bgp-keepalive-time">keepalive time <m/number/</tag>
Delay in seconds between sending of two consecutive Keepalive messages.
+ The effective value depends on the negotiated hold time, as it is scaled
+ to maintain proportion between the keepalive time and the hold time.
Default: One third of the hold time.
+ <tag><label id="bgp-min-keepalive-time">min keepalive time <m/number/</tag>
+ Minimum value of the keepalive time that is accepted during session
+ negotiation. If the proposed hold time would lead to a lower value of
+ the keepalive time, the session is rejected with error. Default: none.
+
+ <tag><label id="bgp-send-hold-time">send hold time <m/number/</tag>
+ Maximum time in seconds betweeen successfull transmissions of BGP messages.
+ Send hold timer drops the session if the neighbor is sending keepalives,
+ but does not receive our messages, causing the TCP connection to stall.
+ This may happen due to malfunctioning or overwhelmed neighbor. See
+ <HTMLURL URL="https://datatracker.ietf.org/doc/draft-ietf-idr-bgp-sendholdtimer/"
+ name="draft-ietf-idr-bgp-sendholdtimer"> for more details.
+
+ Like the option <cf/keepalive time/, the effective value depends on the
+ negotiated hold time, as it is scaled to maintain proportion between the
+ send hold time and the keepalive time. If it is set to zero, the timer
+ is disabled. Default: double of the hold timer limit.
+
+ The option <cf/disable rx/ is intended only for testing this feature and
+ should not be used anywhere else. It discards received messages and
+ disables the hold timer.
+
<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-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't apply
+ 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.
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
</tabular>
</table>
+<p>The BGP protocol can be configured as MPLS-aware (by defining both AFI/SAFI
+channels and the MPLS channel). In such case the BGP protocol assigns labels to
+routes imported from MPLS-aware SAFIs (i.e. <cf/ipvX mpls/ and <cf/vpnX mpls/)
+and automatically announces corresponding MPLS route for each labeled route. As
+BGP generally processes a large amount of routes, it is suggested to set MPLS
+label policy to <cf/aggregate/.
+
+<p>Note that even BGP instances without MPLS channel and without local MPLS
+configuration can still propagate third-party MPLS labels, e.g. as route
+reflectors, they just will not assign local labels to imported routes and will
+not announce MPLS routes for local MPLS forwarding.
+
<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
BGP session (if acceptable), or the preferred address of an associated
interface.
+ <tag><label id="bgp-next-hop-prefer">next hop prefer global</tag>
+ Prefer global IPv6 address to link-local IPv6 address for immediate next
+ hops of received routes. For IPv6 routes, the Next Hop attribute may
+ contain both a global IP address and a link-local IP address. For IBGP
+ sessions, the global IP address is resolved (<ref id="bgp-gateway"
+ name="gateway recursive">) through an IGP routing table
+ (<ref id="bgp-igp-table" name="igp table">) to get an immediate next
+ hop. If the resulting IGP route is a direct route (i.e., the next hop is
+ a direct neighbor), then the link-local IP address from the Next Hop
+ attribute is used as the immediate next hop. This option change it to
+ use the global IP address instead. Note that even with this option
+ enabled a route may end with a link-local immediate next hop when the
+ IGP route has one. Default: disabled.
+
<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
be examined later by <cf/show route/, and can be used to reconfigure
import filters without full route refresh. Default: off.
+ Note that currently the import table breaks routes with recursive
+ nexthops (e.g. ones from IBGP, see <ref id="bgp-gateway" name="gateway
+ recursive">), they are not properly updated after next hop change. For
+ the same reason, it also breaks re-evaluation of flowspec routes with
+ <ref id="bgp-validate" name="flowspec validation"> option enabled on
+ flowspec channels.
+
<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
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,
+ capability, as described in <rfc id="8950">. 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-require-extended-next-hop">require extended next hop <m/switch/</tag>
+ If enabled, the BGP Extended Next Hop Encoding capability (<rfc id="8950">)
+ must be announced by the BGP neighbor, otherwise the BGP session will
+ not be established. Note that this option is relevant just for IPv4 /
+ VPNv4 channels, as IPv6 / VPNv6 channels use a different mechanism not
+ signalled by a capability. 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
+ (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
+ 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-require-add-paths">require add paths <m/switch/</tag>
+ If enabled, the BGP ADD-PATH capability (<rfc id="7911">) must be
+ announced by the BGP neighbor, otherwise the BGP session will not be
+ established. Announced directions in the capability must be compatible
+ with locally configured directions. E.g., If <cf/add path tx/ is
+ configured locally, then the neighbor capability must announce RX.
+ 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
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-local-role"
+ name="local role"> is configured it set automatically.
</descrip>
+<p>For attributes unknown by BIRD, the user can assign a name (on top level) to
+an attribute by its number. This defined name can be used then to get, set (as a
+bytestring, transitive) or unset the given attribute even though BIRD knows
+nothing about it.
+
+<p>Note that it is not possible to define an attribute with the same number
+as one known by BIRD, therefore use of this statement carries a risk of
+incompatibility with future BIRD versions.
+
+<tt><label id="bgp-attribute-custom">attribute bgp <m/number/ bytestring <m/name/;</tt>
+
<sect1>Example
<label id="bgp-exam">
</code>
+<sect>BMP
+<label id="bmp">
+
+<p>The BGP Monitoring Protocol is used for monitoring BGP sessions and obtaining
+routing table data. The current implementation in BIRD is a preliminary release
+with a limited feature set, it will be subject to significant changes in the
+future. It is not ready for production usage and therefore it is not compiled
+by default and have to be enabled during installation by the configure option
+<tt/--with-protocols=/.
+
+<p>The implementation supports monitoring protocol state changes, pre-policy
+routes (in <ref id="bgp-import-table" name="BGP import tables">) and post-policy
+routes (in regular routing tables). All BGP protocols are monitored automatically.
+
+<sect1>Example
+<label id="bmp-exam">
+
+<p><code>
+protocol bmp {
+ # The monitoring station to connect to
+ station address ip 198.51.100.10 port 1790;
+
+ # Monitor received routes (in import table)
+ monitoring rib in pre_policy;
+
+ # Monitor accepted routes (passed import filters)
+ monitoring rib in post_policy;
+}
+</code>
+
+
<sect>Device
<label id="device">
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.
+representing IP subnets of associated interfaces, are imported only with
+<cf/learn all/ enabled.
<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
Time in seconds between two consecutive scans of the kernel routing
table.
- <tag><label id="krt-learn">learn <m/switch/</tag>
+ <tag><label id="krt-learn">learn <m/switch/|all</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.
+ systems which support identification of route authorship. By default,
+ routes created by kernel (marked as "proto kernel") are not imported.
+ Use <cf/learn all/ option to import even these routes.
<tag><label id="krt-kernel-table">kernel table <m/number/</tag>
Select which kernel table should this particular instance of the Kernel
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
<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_lock_*/ and <cf/krt_feature_*/ have type bool, <cf/krt_congctl/ has type
+string, 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_ssthresh/, <cf/krt_lock_ssthresh/, <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_initcwnd/, <cf/krt_lock_initcwnd/, <cf/krt_initrwnd/, <cf/krt_lock_initrwnd/,
+<cf/krt_quickack/, <cf/krt_lock_quickack/, <cf/krt_congctl/, <cf/krt_lock_congctl/,
+<cf/krt_fastopen_no_cookie/, <cf/krt_lock_fastopen_no_cookie/,
<cf/krt_feature_ecn/, <cf/krt_feature_allfrag/
<sect1>Example
<p><code>
protocol kernel { # Primary routing table
learn; # Learn alien routes from the kernel
- persist; # Don't remove routes on bird shutdown
+ persist; # Do not remove routes on bird shutdown
scan time 10; # Scan kernel routing table every 10 seconds
ipv4 {
import all;
</code>
+<sect>L3VPN
+<label id="l3vpn">
+
+<sect1>Introduction
+<label id="l3vpn-intro">
+
+<p>The L3VPN protocol serves as a translator between IP routes and VPN
+routes. It is a component for BGP/MPLS IP VPNs (<rfc id="4364">) and implements
+policies defined there. In import direction (VPN -> IP), VPN routes matching
+import target specification are stripped of route distinguisher and MPLS labels
+and announced as IP routes, In export direction (IP -> VPN), IP routes are
+expanded with specific route distinguisher, export target communities and MPLS
+label and announced as labeled VPN routes. Unlike the Pipe protocol, the L3VPN
+protocol propagates just the best route for each network.
+
+<p>In BGP/MPLS IP VPNs, route distribution is controlled by Route Targets (RT).
+VRFs are associated with one or more RTs. Routes are also associated with one or
+more RTs, which are encoded as route target extended communities
+in <ref id="rta-bgp-ext-community" name="bgp_ext_community">. A route is then
+imported into each VRF that shares an associated Route Target. The L3VPN
+protocol implements this mechanism through mandatory <cf/import target/ and
+<cf/export target/ protocol options.
+
+<sect1>Configuration
+<label id="l3vpn-config">
+
+<p>L3VPN configuration consists of a few mandatory options and multiple channel
+definitions. For convenience, the default export filter in L3VPN channels is
+<cf/all/, as the primary way to control import and export of routes is through
+protocol options <cf/import target/ and <cf/export target/. If custom filters
+are used, note that the export filter of the input channel is applied before
+the route translation, while the import filter of the output channel is applied
+after that.
+
+<p>In contrast to the Pipe protocol, the L3VPN protocol can handle both IPv4 and
+IPv6 routes in one instance, also both IP side and VPN side are represented as
+separate channels, although that may change in the future. The L3VPN is always
+MPLS-aware protocol, therefore a MPLS channel is mandatory. Altogether, L3VPN
+could have up to 5 channels: <cf/ipv4/, <cf/ipv6/, <cf/vpn4/, <cf/vpn6/, and
+<cf/mpls/.
+
+<p><descrip>
+ <tag><label id="l3vpn-route-distinguisher">route distinguisher <m/vpnrd/</tag>
+ The route distinguisher that is attached to routes in the export
+ direction. Mandatory.
+
+ <tag><label id="l3vpn-rd">rd <m/vpnrd/</tag>
+ A shorthand for the option <cf/route distinguisher/.
+
+ <tag><label id="l3vpn-import-target">import target <m/ec/|<m/ec-set/</tag>
+ Route target extended communities specifying which routes should be
+ imported. Either one community or a set. A route is imported if there is
+ non-empty intersection between extended communities of the route and the
+ import target of the L3VPN protocol. Mandatory.
+
+ <tag><label id="l3vpn-export-target">export target <m/ec/|<m/ec-set/</tag>
+ Route target extended communities that are attached to the route in the
+ export direction. Either one community or a set. Other route target
+ extended communities are removed. Mandatory.
+
+ <tag><label id="l3vpn-route-target">route target <m/ec/|<m/ec-set/</tag>
+ A shorthand for both <cf/import target/ and <cf/export target/.
+</descrip>
+
+<sect1>Attributes
+<label id="l3vpn-attr">
+
+<p>The L3VPN protocol does not define any route attributes.
+
+<sect1>Example
+<label id="l3vpn-exam">
+
+<p>Here is an example of L3VPN setup with one VPN and BGP uplink. IP routes
+learned from a customer in the VPN are stored in <cf/vrf0vX/ tables, which are
+mapped to kernel VRF vrf0. Routes can also be exchanged through BGP with
+different sites hosting that VPN. Forwarding of VPN traffic through the network
+is handled by MPLS.
+
+<p>Omitted from the example are some routing protocol to exchange routes with
+the customer and some sort of MPLS-aware IGP to resolve next hops for BGP VPN
+routes.
+
+<code>
+# MPLS basics
+mpls domain mdom;
+mpls table mtab;
+
+protocol kernel krt_mpls {
+ mpls { table mtab; export all; };
+}
+
+vpn4 table vpntab4;
+vpn6 table vpntab6;
+
+# Exchange VPN routes through BGP
+protocol bgp {
+ vpn4 { table vpntab4; import all; export all; };
+ vpn6 { table vpntab6; import all; export all; };
+ mpls { label policy aggregate; };
+ local 10.0.0.1 as 10;
+ neighbor 10.0.0.2 as 10;
+}
+
+# VRF 0
+ipv4 table vrf0v4;
+ipv6 table vrf0v6;
+
+protocol kernel kernel0v4 {
+ vrf "vrf0";
+ ipv4 { table vrf0v4; export all; };
+ kernel table 100;
+}
+
+protocol kernel kernel0v6 {
+ vrf "vrf0";
+ ipv6 { table vrf0v6; export all; };
+ kernel table 100;
+}
+
+protocol l3vpn l3vpn0 {
+ vrf "vrf0";
+ ipv4 { table vrf0v4; };
+ ipv6 { table vrf0v6; };
+ vpn4 { table vpntab4; };
+ vpn6 { table vpntab6; };
+ mpls { label policy vrf; };
+
+ rd 10:12;
+ import target [(rt, 10, 32..40)];
+ export target [(rt, 10, 30), (rt, 10, 31)];
+}
+</code>
+
+
<sect>MRT
<label id="mrt">
authentication cryptographic;
password "abc" {
id 1;
- generate to "22-04-2003 11:00:06";
- accept from "17-01-2001 12:01:05";
+ generate to "2023-04-22 11:00:06";
+ accept from "2021-01-17 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";
+ generate to "2025-07-22";
+ accept from "2021-02-22";
algorithm hmac sha512;
};
};
options and there is a short variant <cf>dnssl <m/domain/</cf> that just
specifies one DNS search domain.
+ <tag><label id="radv-custom-option">custom option type <m/number/ value <m/bytestring/</tag>
+ Custom option definitions allow to define an arbitrary option to
+ advertise. You need to specify the option type number and the binary
+ payload of the option. The length field is calculated automatically.
+ Like <cf/rdnss/ above, multiple definitions are cumulative, they can
+ be used also as interface-specific options.
+
+ The following example advertises PREF64 option (<rfc id="8781">) with
+ prefix <cf>2001:db8:a:b::/96</cf> and the lifetime of <cf/1 hour/:
+
+ <label id="radv-custom-option-exam">
+<p><code>
+custom option type 38 value hex:0e:10:20:01:0d:b8:00:0a:00:0b:00:00:00:00;
+</code>
+
<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
<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.
+
+ <tag><label id="radv-iface-custom-local">custom option local <m/switch/</tag>
+ Use only local custom option definitions for this interface. See <cf/rdnss local/
+ option above. Default: no.
</descrip>
<p>Prefix specific options
roa6 { table <tab>; };
remote <ip> | "<domain>" [port <num>];
port <num>;
+ local address <ip>;
refresh [keep] <num>;
retry [keep] <num>;
expire [keep] <num>;
number is 323 for transport without any encryption and 22 for transport
with SSH encryption.
+ <tag>local address <m/ip/</tag>
+ Define local address we should use as a source address for the RTR session.
+
<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
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>The Static protocol can be configured as MPLS-aware (by defining both the
+primary channel and MPLS channel). In that case the Static protocol assigns
+labels to IP routes and automatically announces corresponding MPLS route for
+each labeled route.
+
<p>Global options:
<descrip>
<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/ [mpls <m/number/] 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.
+
+ When the Static protocol is MPLS-aware, the optional <cf/mpls/ statement
+ after <m/prefix/ specifies a static label for the labeled route, instead
+ of using dynamically allocated label.
- <tag>route <m/prefix/ recursive <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag>
+ <tag>route <m/prefix/ [mpls <m/number/] 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>
+ <tag>route <m/prefix/ [mpls <m/number/] 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/.
(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
+statement <cf>route 10.0.0.0/8 via 192.0.2.1 bfd weight 1 via 192.0.2.2 weight
+2;</cf> 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>
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-dev">dev <m/text/</tag>
+ The outgoing interface associated with the nexthop. Useful for
+ link-local nexthop addresses or when multiple interfaces use the same
+ network prefix. By default, the outgoing interface is resolved from the
+ nexthop address.
+
<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)
<p>The ROA config is just <cf>route <m/prefix/ max <m/int/ as <m/int/</cf> with no nexthop.
+<sect1>Autonomous System Provider Authorization
+
+<p>The ASPA config is <cf>route aspa <m/int/ providers <m/int/ [, <m/int/ ...]</cf> with no nexthop.
+ The first ASN is client and the following are a list of providers.
+ For a transit, you can also write <cf>route aspa <m/int/ transit</cf> to get
+ the no-provider ASPA.
+
<sect1>Flowspec
<label id="flowspec-network-type">
<cf>port 1..1023,1194,3306</cf>).
<tag><label id="flow-dport">dport <m/numbers-match/</tag>
- Set a mating destination port numbers (e.g. <cf>dport 49151</cf>).
+ 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>).
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 10.2.0.0/24 via "arc0"; # Direct route
+ route 10.2.2.0/24 via 192.0.2.1 dev "eth0" onlink; # Route with both nexthop and iface
route 192.168.10.0/24 via 198.51.100.100 {
ospf_metric1 = 20; # Set extended attribute
};
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:40::/48 via fe80::30 dev "eth1"; # Another link-local nexthop
+ route 2001:db8:50::/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
}
</book>
<!--
-LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
+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 Machek
+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 Ondrej Filip
+LocalWords: proto wildcard
-->
projects / thirdparty / bird.git / blobdiff