diff options
Diffstat (limited to 'doc/bird.sgml')
| -rw-r--r-- | doc/bird.sgml | 527 |
1 files changed, 472 insertions, 55 deletions
diff --git a/doc/bird.sgml b/doc/bird.sgml index 394ca86c..419a4537 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -341,10 +341,9 @@ Configuration keywords are <cf/flow4/ and <cf/flow6/. <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 @@ -403,6 +402,79 @@ 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. +<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"> @@ -631,6 +703,12 @@ include "tablename.conf";; 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> @@ -941,7 +1019,7 @@ inherited from templates can be updated by new definitions. <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. @@ -1043,6 +1121,100 @@ protocol bgp from { </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"> @@ -1404,22 +1576,18 @@ in the foot). 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 - in several ways: - - A sequence of hexadecimal digit pairs, optionally colon-separated. - A bytestring specified this way must be at least 16 bytes (32 digits) - long: <cf/01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef/ or - <cf/0123456789abcdef0123456789abcdef/. + compare bytestings (<cf/=, !=/). - A sequence of hexadecimal digit pairs of any lengh (including zero) - with the <cf/hex:/ prefix. Colon separators can be inserted - arbitrarily between any bytes: <cf/hex:/, <cf/hex:1234/, - <cf/hex:1234:56:78/. + 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 colons, hyphens and - spaces as byte separators: <cf/from_hex(" 1234 56:78 ab-cd-ef ")/. + 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 @@ -1547,7 +1715,7 @@ in the foot). 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 @@ -1885,6 +2053,29 @@ Common route attributes are: 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 @@ -2816,14 +3007,22 @@ using the following configuration parameters: 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. + 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 @@ -2840,11 +3039,16 @@ using the following configuration parameters: 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 @@ -2858,12 +3062,17 @@ using the following configuration parameters: 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, @@ -2883,11 +3092,21 @@ using the following configuration parameters: 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 @@ -2897,7 +3116,11 @@ using the following configuration parameters: capability-related error. <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), @@ -2945,6 +3168,23 @@ using the following configuration parameters: 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. @@ -3062,6 +3302,18 @@ together with their appropriate channels follows. </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 @@ -3211,15 +3463,30 @@ be used in explicit configuration. 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 @@ -3365,14 +3632,18 @@ some of them (marked with `<tt/O/') are optional. <tag><label id="bgp-otc">int bgp_otc [O]</tag> This attribute is defined in <rfc id="9234">. OTC is a flag that marks - routes that should be sent only to customers. If <ref id="bgp-role" - name="local Role"> is configured it set automatically. + 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 both set -(by a bytestring literal, transitive) or unset the given attribute even though -BIRD knows nothing about it: +<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> @@ -3429,10 +3700,9 @@ 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 is limited to monitor protocol state changes and routes -in <ref id="bgp-import-table" name="BGP import tables"> (not regular routing -tables), therefore import table must be enabled in BGP protocols. All BGP -protocols are monitored automatically. +<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"> @@ -3442,8 +3712,11 @@ protocol bmp { # The monitoring station to connect to station address ip 198.51.100.10 port 1790; - # required option + # Monitor received routes (in import table) monitoring rib in pre_policy; + + # Monitor accepted routes (passed import filters) + monitoring rib in post_policy; } </code> @@ -3568,9 +3841,8 @@ on the <cf/learn/ switch, such routes are either ignored or accepted to our table). <p>Note that routes created by OS kernel itself, namely direct routes -representing IP subnets of associated interfaces, are not imported even with -<cf/learn/ enabled. You can use <ref id="direct" name="Direct protocol"> to -generate these direct routes. +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 @@ -3601,10 +3873,12 @@ channels. 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 @@ -3714,7 +3988,7 @@ protocol kernel { <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; @@ -3732,6 +4006,140 @@ protocol kernel { # Secondary routing table </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"> @@ -4675,7 +5083,7 @@ definitions, prefix definitions and DNS definitions: <label id="radv-custom-option-exam"> <p><code> -custom option type 38 value hex:0e10:2001:0db8:000a:000b:0000:0000; +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> @@ -5454,6 +5862,11 @@ but only routes of the same network type are allowed, as the static protocol has just one channel. E.g., to have both IPv4 and IPv6 static routes, define two static protocols, each with appropriate routes and channel. +<p>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> @@ -5477,16 +5890,20 @@ static protocols, each with appropriate routes and channel. <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/. |