v2:
- Addressed Mark's comments:
- Renamed configuration.rst to configuration-examples.rst
and stripped the configuration reference sections that
duplicated the architecture document. The new document
focuses on worked examples with explanatory prose,
verification commands, and best practices.
- Added hub-spoke to the redistribution options list in
architecture.rst.
- Fixed VRF table ID accuracy in architecture.rst to list
all excluded values (0, 252-255, 4294967295) matching
the TABLE_ID_VALID macro.
- Improved connected-as-host + local-only grouping in
architecture.rst.
- Added Routing Protocol Redirect section to
architecture.rst.
- Added Port-to-Interface Mapping section to
architecture.rst.
- Expanded dynamic-routing-v4-prefix-nexthop description
in ovn-nb.xml with RFC 5549 explanation.
---
Documentation/automake.mk | 1 +
.../topics/dynamic-routing/architecture.rst | 68 +++-
.../configuration-examples.rst | 371 ++++++++++++++++++
.../topics/dynamic-routing/index.rst | 1 +
ovn-nb.xml | 8 +-
5 files changed, 441 insertions(+), 8 deletions(-)
create mode 100644
Documentation/topics/dynamic-routing/configuration-examples.rst
diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index aa286ebd9c..91582163e1 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -27,6 +27,7 @@ DOC_SOURCE = \
Documentation/topics/test-development.rst \
Documentation/topics/high-availability.rst \
Documentation/topics/dynamic-routing/architecture.rst \
+ Documentation/topics/dynamic-routing/configuration-examples.rst \
Documentation/topics/dynamic-routing/index.rst \
Documentation/topics/incremental-processing/datapath-sync-graph.png \
Documentation/topics/incremental-processing/evpn-arp-graph.png \
diff --git a/Documentation/topics/dynamic-routing/architecture.rst
b/Documentation/topics/dynamic-routing/architecture.rst
index e7c968330f..c517fe085f 100644
--- a/Documentation/topics/dynamic-routing/architecture.rst
+++ b/Documentation/topics/dynamic-routing/architecture.rst
@@ -288,6 +288,9 @@ accepts a comma-separated list of the following values:
- ``lb`` --- The VIP address of each load balancer associated with this
router and neighboring routers.
+- ``hub-spoke`` --- Routes learned through OVN Interconnection (OVN-IC)
+ from other routers, enabling hub-and-spoke propagation.
+
These options can also be set per logical router port, overriding the
router-level setting for routes associated with that specific port.
@@ -322,15 +325,18 @@ When the ``tracked_port`` field is set on an ``Advertised_Route`` record,
``ovn-controller`` adjusts the route metric based on whether the tracked
port is locally bound on this chassis. Routes for locally bound ports
receive a higher priority (lower metric value), which causes the routing
-daemon to prefer the chassis that actually hosts the workload. This
-mechanism is particularly useful for host routes generated by the
-``connected-as-host`` redistribution mode.
+daemon to prefer the chassis that actually hosts the workload.
The ``dynamic-routing-redistribute-local-only`` option further refines
this behavior: when set to ``true``, ``ovn-controller`` only installs
routes on the chassis where the ``tracked_port`` is locally bound,
preventing other chassis from advertising the route at all.
+This is particularly useful with ``connected-as-host`` redistribution
+to ensure host routes are only announced from the chassis that owns the
+workload, providing optimal traffic forwarding and avoiding unnecessary
+traffic tromboning.
+
IP Route Learning
-----------------
@@ -391,8 +397,9 @@ The VRF routing table ID is determined by one of the following, in order
of precedence:
1. The ``dynamic-routing-vrf-id`` option on the logical router, if set to
- a valid integer (1-4294967295, excluding reserved table IDs such as
- ``RT_TABLE_MAIN`` and ``RT_TABLE_LOCAL``).
+ a valid integer in the range (1-4294967294), excluding the reserved
+ table IDs 252 (``RT_TABLE_COMPAT``), 253 (``RT_TABLE_DEFAULT``),
+ 254 (``RT_TABLE_MAIN``), and 255 (``RT_TABLE_LOCAL``).
2. The tunnel key of the logical router datapath, used as a fallback
when ``dynamic-routing-vrf-id`` is not configured.
@@ -423,6 +430,57 @@ If ``dynamic-routing-maintain-vrf`` is ``false`` (the
default), the VRF
is expected to already exist on the chassis, managed by external tooling
or configuration management.
+Routing Protocol Redirect
+-------------------------
+
+OVN can optionally redirect routing protocol control plane traffic from
+a logical router port to a logical switch port where an external routing
+daemon is listening. This allows the routing daemon to peer using the
+router port's IP addresses through an OVN-managed logical switch port.
+
+Routing protocol redirect is entirely optional. The routing daemon can
+establish its BGP or BFD sessions completely outside of OVN --- for
+example, on a separate physical interface, a loopback, or any other
+interface that is not managed by OVN. Use this feature only when you
+want the routing daemon to peer using the logical router port's IP
+addresses through an OVN-managed logical switch port.
+
+The ``routing-protocols`` option on a ``Logical_Router_Port`` specifies
+which control plane protocols to redirect:
+
+- ``BGP`` --- Redirects TCP port 179 (BGP session establishment and
+ keepalives).
+
+- ``BFD`` --- Redirects UDP port 3784 (Bidirectional Forwarding
+ Detection).
+
+The ``routing-protocol-redirect`` option on the same port identifies the
+logical switch port where the routing daemon is bound. OVN installs
+logical flows to forward matching control plane traffic between the
+router port and the specified switch port.
+
+For BGP unnumbered deployments, periodic IPv6 Router Advertisements can be
+enabled on the logical router port via the ``ipv6_ra_configs`` column.
+This provides automatic link-local address discovery, which is required
+for establishing BGP sessions over IPv6-only peering links that carry
+both IPv4 and IPv6 routes. In order for this to function, automatic address
+discovery needs to also be supported and configured on remote BGP peer.
+
+Port-to-Interface Mapping
+-------------------------
+
+When a chassis has multiple links toward the fabric, each running BGP
+independently, the ``dynamic-routing-port-name`` option on a logical
+router port restricts route learning to a specific Linux interface.
+``ovn-controller`` resolves the port name to a Linux interface. If the
+referenced port is bound locally, the interface name is discovered
+automatically.
+
+When automatic discovery is not available (for example, the port is not
+bound locally), the ``dynamic-routing-port-mapping`` option on the
+``Open_vSwitch`` table provides an explicit mapping from logical port
+names to Linux interface names.
+
EVPN (Ethernet VPN) Integration
-------------------------------
diff --git a/Documentation/topics/dynamic-routing/configuration-examples.rst b/Documentation/topics/dynamic-routing/configuration-examples.rst
new file mode 100644
index 0000000000..7118588260
--- /dev/null
+++ b/Documentation/topics/dynamic-routing/configuration-examples.rst
@@ -0,0 +1,371 @@
+..
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance with the License. You may obtain
+ a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+
+ Convention for heading levels in OVN documentation:
+
+ ======= Heading 0 (reserved for the title in a document)
+ ------- Heading 1
+ ~~~~~~~ Heading 2
+ +++++++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+======================================
+Dynamic Routing Configuration Examples
+======================================
+
+Introduction
+------------
+
+This document provides configuration examples for OVN's dynamic routing
+feature. For the underlying architecture, data flow, and full description
+of each option, see :doc:`/topics/dynamic-routing/architecture` and
+``ovn-nb``\(5).
+
+Configuration Examples
+----------------------
+
+The following examples demonstrate complete configurations for common
+deployment scenarios.
+
+Example: Gateway Router with BGP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A centralized gateway router pinned to a specific chassis, peering
+with an external BGP speaker to advertise connected and static
+routes.
+
+::
+
+ External BGP Peer
+ |
+ | BGP peering
+ |
+ +---------+---------+
+ | LS-Fabric |
+ | 192.168.1.0/24 |
+ +---------+---------+
+ |
+ +---------+---------+
+ | Gateway Router | (lr-gw, pinned to chassis-1)
+ | 10.0.0.1/24 | dynamic-routing = true
+ +---------+---------+
+ |
+ +---------+---------+
+ | Logical Switch | (ls-internal)
+ | 10.0.0.0/24 |
+ +---------+---------+
+ |
+ VM1 VM2 VM3
+
+**Create the logical topology.**
+::
+
+ $ ovn-nbctl lr-add lr-gw
+ $ ovn-nbctl ls-add ls-internal
+ $ ovn-nbctl ls-add ls-fabric
+
+ # Router port toward the internal network.
+ $ ovn-nbctl lrp-add lr-gw lrp-internal \
+ 00:00:00:00:00:01 10.0.0.1/24
+ $ ovn-nbctl lsp-add-router-port ls-internal \
+ lsp-internal-to-gw lrp-internal
+
+ # Router port toward the fabric.
+ $ ovn-nbctl lrp-add lr-gw lrp-fabric \
+ 00:00:00:00:00:02 192.168.1.1/24
+ $ ovn-nbctl lsp-add-router-port ls-fabric \
+ lsp-fabric-to-gw lrp-fabric
+
+ # Localnet port for physical connectivity.
+ $ ovn-nbctl lsp-add-localnet-port ls-fabric \
+ lsp-fabric-ln physnet-fabric
+
+**Pin the router to a chassis and enable dynamic routing.**
+
+Enable IP route exchange on this logical router with
+``dynamic-routing=true``. The ``dynamic-routing-redistribute`` option
+controls which route types are advertised to external peers ---
+``connected`` advertises the subnet prefixes of the router's ports
+and ``static`` advertises all configured static routes. Set an
+explicit ``dynamic-routing-vrf-id`` so the VRF table ID is
+predictable in FRR configuration.
+
+::
+
+ $ ovn-nbctl set Logical_Router lr-gw \
+ options:chassis=chassis-1 \
+ options:dynamic-routing=true \
+ options:dynamic-routing-redistribute=connected,static \
+ options:dynamic-routing-vrf-id=100
+
+**Configure VRF management and routing protocol redirect.**
+
+Setting ``dynamic-routing-maintain-vrf=true`` on the fabric-facing
+port lets ``ovn-controller`` create and delete the VRF automatically
+when the port is bound or unbound.
+
+A dedicated logical switch port (``lsp-bgp``) is added for the BGP
+daemon. The ``routing-protocols`` and ``routing-protocol-redirect``
+options on the router port tell OVN to forward BGP (TCP 179) and BFD
+(UDP 3784) control plane traffic to that switch port, so FRR can peer
+using the router port's IP addresses.
+
+Periodic IPv6 Router Advertisements are enabled to support BGP
+unnumbered (RFC 5549), where the link-local nexthop is discovered
+automatically.
+
+::
+
+ # Let ovn-controller create/delete the VRF automatically.
+ $ ovn-nbctl set Logical_Router_Port lrp-fabric \
+ options:dynamic-routing-maintain-vrf=true
+
+ # Add a logical switch port for the BGP daemon.
+ $ ovn-nbctl lsp-add ls-fabric lsp-bgp
+ $ ovn-nbctl lsp-set-addresses lsp-bgp unknown
+
+ # Redirect BGP and BFD control plane traffic to lsp-bgp.
+ $ ovn-nbctl set Logical_Router_Port lrp-fabric \
+ options:routing-protocols=BGP,BFD \
+ options:routing-protocol-redirect=lsp-bgp
+
+ # Enable periodic RAs for BGP unnumbered peer discovery.
+ $ ovn-nbctl set Logical_Router_Port lrp-fabric \
+ ipv6_ra_configs:send_periodic=true \
+ ipv6_ra_configs:address_mode=slaac \
+ ipv6_ra_configs:max_interval=10 \
+ ipv6_ra_configs:min_interval=5
+
+**Bind the BGP interface on the chassis.**
+::
+
+ # Create an OVS internal port bound to the BGP LSP.
+ $ ovs-vsctl add-port br-int ext0-bgp -- \
+ set Interface ext0-bgp type=internal \
+ external-ids:iface-id=lsp-bgp
+
+ # Place the interface into the VRF.
+ $ ip link set dev ext0-bgp master ovnvrf100
+ $ ip link set dev ext0-bgp up
+
+**Configure FRR on the chassis.**
+::
+
+ configure terminal
+
+ vrf ovnvrf100
+ exit-vrf
+
+ router bgp 65000 vrf ovnvrf100
+ bgp router-id 192.168.1.1
+ neighbor ext0-bgp interface remote-as external
+ address-family ipv4 unicast
+ redistribute kernel
+ exit-address-family
+ address-family ipv6 unicast
+ redistribute kernel
+ neighbor ext0-bgp activate
+ exit-address-family
+
+Example: Distributed Router with Gateway Ports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A distributed logical router with a distributed gateway port,
+advertising connected, NAT, and load balancer routes. The
+``local-only`` option ensures host routes are announced only from the
+chassis hosting the workload.
+
+::
+
+ External BGP Peer
+ |
+ | BGP peering
+ |
+ +---------+---------+
+ | LS-Fabric |
+ | 172.16.0.0/24 |
+ +---------+---------+
+ |
+ +-------------+-------------------+
+ | Distributed LR |
+ | (lr-dist) |
+ | dynamic-routing = true |
+ | NAT: 172.16.0.10 -> 10.0.1.10 |
+ | LB VIP: 172.16.0.100 |
+ +--------+----------+-------------+
+ | |
+ +-----+------+ +-+---------+
+ | LS-A | | LS-B |
+ | 10.0.1/24 | | 10.0.2/24 |
+ +-----+------+ +-----+-----+
+ | |
+ VM-A1 VM-B1
+ (chassis-1) (chassis-2)
+
+**Create the distributed router with a gateway port.**
+::
+
+ $ ovn-nbctl lr-add lr-dist
+ $ ovn-nbctl ls-add ls-a
+ $ ovn-nbctl ls-add ls-b
+ $ ovn-nbctl ls-add ls-fabric
+
+ # Internal ports.
+ $ ovn-nbctl lrp-add lr-dist lrp-a \
+ 00:00:00:00:01:01 10.0.1.1/24
+ $ ovn-nbctl lsp-add-router-port ls-a lsp-a-to-lr lrp-a
+
+ $ ovn-nbctl lrp-add lr-dist lrp-b \
+ 00:00:00:00:01:02 10.0.2.1/24
+ $ ovn-nbctl lsp-add-router-port ls-b lsp-b-to-lr lrp-b
+
+ # Distributed gateway port.
+ $ ovn-nbctl lrp-add lr-dist lrp-gw \
+ 00:00:00:00:02:01 172.16.0.1/24
+ $ ovn-nbctl lsp-add-router-port ls-fabric \
+ lsp-fabric-to-lr lrp-gw
+
+ # Configure HA chassis group for the gateway port.
+ $ ovn-nbctl ha-chassis-group-add ha-gw
+ $ ovn-nbctl ha-chassis-group-add-chassis ha-gw \
+ chassis-1 10
+ $ ovn-nbctl ha-chassis-group-add-chassis ha-gw \
+ chassis-2 5
+ $ GRP=$(ovn-nbctl --bare --columns=_uuid \
+ find HA_Chassis_Group name=ha-gw)
+ $ ovn-nbctl set Logical_Router_Port lrp-gw \
+ ha_chassis_group=$GRP
+
+**Add NAT and load balancer.**
+::
+
+ $ ovn-nbctl lr-nat-add lr-dist dnat_and_snat \
+ 172.16.0.10 10.0.1.10
+ $ ovn-nbctl lb-add lb-web 172.16.0.100:80 \
+ 10.0.1.10:8080,10.0.2.10:8080
+ $ ovn-nbctl lr-lb-add lr-dist lb-web
+
+**Enable dynamic routing with NAT and LB redistribution.**
+
+Here ``dynamic-routing-redistribute`` includes ``nat`` (NAT external
+IPs) and ``lb`` (load balancer VIPs) in addition to ``connected``
+subnets. Setting ``dynamic-routing-redistribute-local-only=true`` on
+the gateway port ensures these host routes are only advertised from
+the chassis where the tracked workload port is locally bound,
+avoiding unnecessary traffic tromboning.
+
+::
+
+ $ ovn-nbctl set Logical_Router lr-dist \
+ options:dynamic-routing=true \
+ options:dynamic-routing-redistribute=connected,nat,lb \
+ options:dynamic-routing-vrf-id=200
+
+ $ ovn-nbctl set Logical_Router_Port lrp-gw \
+ options:dynamic-routing-maintain-vrf=true \
+ options:dynamic-routing-redistribute-local-only=true
+
+With ``local-only`` enabled, NAT and LB host routes are only
+advertised on the chassis where their traffic is processed,
+ensuring optimal traffic forwarding.
+
+**Set up routing protocol redirect and FRR** (same pattern as the
+gateway router example above).
+
+Verification
+------------
+
+Checking OVN State
+~~~~~~~~~~~~~~~~~~
+
+Verify that ``ovn-northd`` has populated the ``Advertised_Route``
+table::
+
+ $ ovn-sbctl list Advertised_Route
+
+Check for learned routes from external peers::
+
+ $ ovn-sbctl list Learned_Route
+
+Checking the VRF and Kernel Routes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Verify the VRF exists and is up::
+
+ $ ip link show type vrf
+
+List routes in the VRF table. Routes marked ``proto ovn`` were
+installed by ``ovn-controller``; routes with other protocol values
+(e.g., ``proto bgp``) were learned from the routing daemon::
+
+ $ ip route show table 100
+
+Checking FRR State
+~~~~~~~~~~~~~~~~~~
+
+Verify BGP peering is established::
+
+ $ vtysh -c "show bgp summary"
+
+Check received and advertised routes::
+
+ $ vtysh -c "show bgp ipv4 unicast"
+ $ vtysh -c "show bgp ipv6 unicast"
+
+Best Practices
+--------------
+
+**Use explicit VRF IDs.**
+Set ``dynamic-routing-vrf-id`` rather than relying on the datapath
+tunnel key. Explicit IDs make the VRF configuration predictable and
+easier to reference in FRR configurations and monitoring.
+
+**Use local-only for host routes.**
+When using ``connected-as-host`` redistribution, combine it with
+``dynamic-routing-redistribute-local-only=true`` to ensure host
+routes are only announced from the chassis that owns the workload.
+This provides optimal traffic forwarding and avoids unnecessary
+traffic tromboning.
+
+**Let ovn-controller manage VRFs when possible.**
+Set ``dynamic-routing-maintain-vrf=true`` on the logical router port
+to let ``ovn-controller`` handle VRF creation and deletion. This
+simplifies chassis provisioning and ensures VRF lifecycle matches
+port binding.
+
+**Configure BFD for fast failure detection.**
+Include ``BFD`` in the ``routing-protocols`` option and enable BFD
+in FRR for sub-second failure detection. This significantly improves
+convergence time compared to relying on BGP hold timers alone.
+
+**Use per-port redistribution for multi-homed setups.**
+When a chassis has multiple fabric links, use per-port
+``dynamic-routing-redistribute`` and ``dynamic-routing-port-name`` to
+control exactly which routes are advertised and learned on each link.
+
+See Also
+--------
+
+- :doc:`/topics/dynamic-routing/architecture` --- Architecture and
+ internal design of the dynamic routing feature.
+
+- ``ovn-nb``\(5) --- Full reference for all ``Logical_Router``
+ and ``Logical_Router_Port`` dynamic routing options.
+
+- ``ovn-sb``\(5) --- Documentation of the ``Advertised_Route``
+ and ``Learned_Route`` tables.
+
+- ``ovn-controller``\(8) --- Controller-side configuration options
+ including ``dynamic-routing-port-mapping``.
diff --git a/Documentation/topics/dynamic-routing/index.rst
b/Documentation/topics/dynamic-routing/index.rst
index eb61afb4a3..d5ef53d8ab 100644
--- a/Documentation/topics/dynamic-routing/index.rst
+++ b/Documentation/topics/dynamic-routing/index.rst
@@ -29,3 +29,4 @@ Dynamic Routing
:maxdepth: 2
architecture
+ configuration-examples
diff --git a/ovn-nb.xml b/ovn-nb.xml
index ed16da2772..15fb1d7e86 100644
--- a/ovn-nb.xml
+++ b/ovn-nb.xml
@@ -3670,9 +3670,11 @@ or
</p>
<p>
- This defines nexthop used by IPv4 advertised routes instead of the
- routes being advertised as blackhole. This can be either valid IPv4
- or IPv6 address.
+ This defines the nexthop used by IPv4 advertised routes instead of
+ the routes being advertised as blackhole. This can be either a
+ valid IPv4 or IPv6 address. When an IPv6 address is used, it
+ enables RFC 5549-style routing where IPv4 traffic is forwarded
+ over an IPv6-only peering link.
</p>
</column>
