ovn-bgp-agent — Interactions

Interactions — ovn-bgp-agent — branch stable/2026.2

Branch stable/2026.2 @ f770768b41dc (7.0.0-2-gf770768) — repository https://opendev.org/openstack/ovn-bgp-agent — analysed on 2026-10-28 External references: ovsdbapp: = ovsdbapp stable/2026.2 @ 0fb5a1b9a675; neutron-lib: = neutron-lib stable/2026.2 @ 1ee72052251a.

The agent uses no database, no message bus, no cache and no REST API. It talks to six local or remote systems:

1. Privilege separation

All writes to the kernel, OVS and FRR go through oslo.privsep daemons started with [agent] root_helper (default sudo, ovn_bgp_agent/config.py:148-154, ovn_bgp_agent/config.py:258-259):

The privsep daemons receive whole requests (a route dict, a list of IPs, a command line). Read-only netlink dumps (get_exposed_ips, get_ovn_ip_rules, _get_table_routes…) run unprivileged in the agent process (ovn_bgp_agent/utils/linux_net.py:472, ovn_bgp_agent/utils/linux_net.py:539).

2. Local Open vSwitch database

• Connection: idl.Idl on Open_vSwitch, Bridge, Port, Interface, probe interval 60 s, ovsdbapp connection timeout 180 s (hard-coded, not ovsdb_connection_timeout) (ovn_bgp_agent/drivers/openstack/utils/ovs.py:274-284).
• Keys read in Open_vSwitch . external_ids (ovn_bgp_agent/drivers/openstack/utils/ovs.py:286-330):

• Write: add-br <bridge> through the IDL for EVPN NB wiring (ovn_bgp_agent/drivers/openstack/utils/wire.py:111).

3. OVN Southbound (SB drivers)

3.1 Connection and monitored tables

• OvnSbIdl builds the schema helper from the server, registers only the needed tables and, when a chassis is given, sets a monitor condition name == <system-id> on Chassis_Private (or Chassis), so only the own chassis row is received (ovn_bgp_agent/drivers/openstack/utils/ovn.py:95-114). SSL key/cert/CA are set process-wide with Stream.ssl_set_* when the remote starts with ssl (ovn_bgp_agent/drivers/openstack/utils/ovn.py:119-131). Transaction timeout ovsdb_connection_timeout (180 s); probe interval 60 s (ovn_bgp_agent/drivers/openstack/utils/ovn.py:133-139, ovn_bgp_agent/drivers/openstack/utils/ovn.py:466-468).

Port_Binding and Load_Balancer are monitored unconditionally: every node receives the whole table.

3.2 Columns and conventions read

3.3 Read queries (client-side, on the IDL cache)

All queries are db_find_rows/db_list_rows evaluated in the agent's replica; they cost CPU, not round trips. Main ones:

4. OVN Northbound (NB driver)

4.1 Connection and tables

• Tables Logical_Switch_Port, NAT, Logical_Switch, Logical_Router, Logical_Router_Port, Load_Balancer, DHCP_Options, NB_Global, no monitor condition (ovn_bgp_agent/drivers/openstack/nb_ovn_bgp_driver.py:44-46, ovn_bgp_agent/drivers/openstack/utils/ovn.py:53-92).
• Node-local cluster (exposing_method = ovn): Logical_Switch, Logical_Switch_Port, Logical_Router, Logical_Router_Port, Logical_Router_Policy, Logical_Router_Static_Route, Gateway_Chassis, Static_MAC_Binding (+ BFD used by bfd_add) with leader_only=True (ovn_bgp_agent/drivers/openstack/nb_ovn_bgp_driver.py:47-51, ovn_bgp_agent/drivers/openstack/nb_ovn_bgp_driver.py:240-245). Note: BFD is not in the registered list; bfd_add on an unregistered table is expected to fail [inferred, not run].

4.2 Columns read

4.3 Writes to the node-local NB (exposing_method = ovn)

4.4 Sample OVSDB frames

Monitor request sent by the SB IDL (abridged, one table shown) [inferred from ovs.db.idl behaviour; not captured]:

{"id": 3, "method": "monitor_cond_since",
 "params": ["OVN_Southbound", ["monid", "OVN_Southbound"],
  {"Chassis_Private": [{"columns": ["name", "chassis", "external_ids", "nb_cfg"],
                        "where": [["name", "==", "8f6c2c3e-…-system-id"]]}],
   "Port_Binding": [{"columns": ["logical_port", "type", "mac", "chassis", "up",
                                  "datapath", "nat_addresses", "options", "tag", "external_ids", "…"]}]},
  "00000000-0000-0000-0000-000000000000"]}

Update that fires PortBindingChassisCreatedEvent on chassis 8f6c… (VM bound and up):

{"method": "update3", "params": [["monid", "OVN_Southbound"], "…txn-id…",
 {"Port_Binding": {"5b1c…": {"modify": {
     "chassis": ["uuid", "a3d4…(row of Chassis 8f6c…)"],
     "up": true}}}}]}

5. Neutron conventions consumed (external_ids)

The agent relies on keys written by Neutron's OVN driver (and networking-bgpvpn). A re-implementation must read exactly these keys (ovn_bgp_agent/constants.py:33-125):

6. FRR (vtysh)

• Invocation: /usr/bin/vtysh --vty_socket /run/frr/ -f <tmpfile> to apply configuration; /usr/bin/vtysh --vty_socket /run/frr/ -c '<command>' to query (ovn_bgp_agent/privileged/vtysh.py:25-45, ovn_bgp_agent/constants.py:57). The temporary file is written by the unprivileged agent and read by the privileged daemon (ovn_bgp_agent/drivers/openstack/utils/frr.py:122-138).
• Query: show ip bgp summary json → ipv4Unicast.routerId, used when bgp_router_id is not configured (ovn_bgp_agent/drivers/openstack/utils/frr.py:116-119).
• Assumption: FRR runs with an integrated configuration and a pre-existing router bgp <bgp_AS> with its neighbours (see etc/frr/frr.conf); the agent never configures peers.

Configuration fragments applied (Jinja2, ovn_bgp_agent/drivers/openstack/utils/frr.py:31-113). Rendered LEAK_VRF_TEMPLATE with defaults (bgp_AS=64999, bgp_vrf=bgp-vrf, router-id 172.24.4.1, redistribute connected):

router bgp 64999
  address-family ipv4 unicast
    import vrf bgp-vrf
  exit-address-family

  address-family ipv6 unicast
    import vrf bgp-vrf
  exit-address-family

router bgp 64999 vrf bgp-vrf
  bgp router-id 172.24.4.1
  address-family ipv4 unicast
    redistribute connected
  exit-address-family

  address-family ipv6 unicast
    redistribute connected
  exit-address-family

ADD_VRF_TEMPLATE (EVPN, vni=1001, local_ip=10.0.0.1, no RD, RT 64999:1001):

vrf vrf-1001
  vni 1001
exit-vrf

router bgp 64999 vrf vrf-1001
  address-family ipv4 unicast
    redistribute connected
  exit-address-family
  address-family ipv6 unicast
    redistribute connected
  exit-address-family
  address-family l2vpn evpn
    advertise ipv4 unicast
    advertise ipv6 unicast
    rd 10.0.0.1:1001
    route-target import 64999:1001
    route-target export 64999:1001
  exit-address-family

The real texts also contain the blank lines left by the Jinja tags (ignored by vtysh); with advertisement_method_tenant_networks = subnet both redistribute connected and redistribute kernel appear. Without evpn_local_ip, the RD line is rendered as rd None:<vni> (defect D15, 02 § 4). DEL_VRF_TEMPLATE: no vrf vrf-<vni> / no interface veth-vrf-<vni> / no router bgp <as> vrf vrf-<vni>. CONFIGURE_ND_TEMPLATE: interface <veth> / ipv6 nd managed-config-flag / ipv6 nd rdnss <dns> / ipv6 nd prefix <prefix> [no-autoconfig] / no ipv6 nd suppress-ra. Exact renderings are recorded in _rewrite/side-effects_stable-2026.2.json (see 07).

7. Linux kernel

7.1 Devices

Interface names are truncated to 15 characters (neutron-lib:neutron_lib/constants.py:324); VLAN device names keep 10 characters of the bridge name so that .<4094> fits (ovn_bgp_agent/constants.py:97-98).

7.2 Addresses, routes, rules, neighbours (underlay)

For a provider IP 172.24.100.10 on network public → br-ex, table 200 (ip equivalents):

ip rule add to 172.24.100.10/32 table 200                       # rule_create   ovn_bgp_agent/utils/linux_net.py:703
ip route replace 172.24.100.10/32 dev br-ex table 200 scope link proto boot   # route_create  ovn_bgp_agent/utils/linux_net.py:753
ip addr add 172.24.100.10/32 dev bgp-nic                          # BGP announcement  ovn_bgp_agent/privileged/linux_net.py:586

For a router gateway (cr-lrp) 172.24.100.5, MAC fa:16:3e:aa:bb:cc, VLAN 100: same rule/route on br-ex.100, plus ip neigh replace 172.24.100.5 lladdr fa:16:3e:aa:bb:cc dev br-ex.100 nud permanent (ovn_bgp_agent/utils/linux_net.py:703-719) and, for IPv6, ip -6 nei add proxy <prefix> dev br-ex.100 (ovn_bgp_agent/privileged/linux_net.py:204-216). For a tenant subnet 10.0.0.0/24 behind that gateway: ip rule add to 10.0.0.0/24 table 200 and ip route replace 10.0.0.0/24 via 172.24.100.5 dev br-ex.100 table 200 proto boot; with advertisement_method_tenant_networks = subnet, also ip route replace 10.0.0.0/24 via 172.24.100.5 dev bgp-nic table 10 (ovn_bgp_agent/drivers/openstack/utils/wire.py:831-872).

• Routes are created with proto 3 (boot) and replace (ovn_bgp_agent/utils/linux_net.py:785-799, ovn_bgp_agent/privileged/linux_net.py:153-158); routes of proto 186 (FRR's BGP routes) are never considered leftovers (ovn_bgp_agent/utils/linux_net.py:618-623).
• Per-bridge routing tables are **declared in /etc/iproute2/rt_tables** (<number> <bridge>), created from /usr/share/iproute2/rt_tables if missing (ovn_bgp_agent/privileged/linux_net.py:328-348). Numbers are chosen at random in 1–252 among free ones; exhaustion calls sys.exit(1) (ovn_bgp_agent/utils/linux_net.py:256-265).

7.3 sysctl

net.ipv4.conf.<dev>.proxy_arp=1, net.ipv6.conf.<dev>.proxy_ndp=1 on bridges and VLAN devices (ovn_bgp_agent/utils/linux_net.py:439-446); EVPN NB also sets net.ipv4.ip_forward, net.ipv4.conf.all.forwarding, net.ipv6.conf.all.forwarding and per-interface forwarding (ovn_bgp_agent/utils/linux_net.py:449-463). Executed as sysctl -w <flag>=<value> (ovn_bgp_agent/privileged/linux_net.py:171-177).

8. Open vSwitch switch

The MAC-tweak flow is what makes egress work in underlay mode: packets leaving OVN towards the provider bridge get the bridge's own MAC as destination, so the kernel routes them (through the per-bridge table and its default route) instead of OVS switching them. ovs-ofctl is retried once with -O OpenFlow13 on failure (ovn_bgp_agent/privileged/ovs_vsctl.py:40-44).

9. Files

Source: reverse-spec-ovn-bgp-agent/03-interactions_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.