Routing¶
The routing app. Catalogs are tenant-wide and named; rule rows belong to
their list and carry no tenant of their own (they are scoped through it,
like an interface through its device); device-bound rows are site-scoped
through the device. Every model has a UUID primary key; catalogs and
device-bound rows carry numid, custom fields and tags.
Catalogs¶
Shared shape: tenant FK, name char(128), description text, unique
(tenant, name).
| Model | Own fields | Rules |
|---|---|---|
PrefixList |
family (ipv4/ipv6) |
PrefixListRule: sequence, action, prefix (normalised CIDR), prefix_obj FK → Prefix (optional), ge, le, description; unique (prefix_list, sequence) |
Community |
value (unique per tenant), kind (standard/large/extended) |
- |
CommunityList |
kind (standard/expanded/large/extended) |
CommunityListRule: sequence, action, communities M2M, regex, description |
ASPathList |
- | ASPathListRule: sequence, action, regex, description |
RoutingPolicy |
- | RoutingPolicyRule: sequence, action, description; match: match_prefix_lists, match_community_lists, match_as_path_lists M2M, match_next_hop FK → PrefixList, match_rpki (valid/invalid/notfound, blank = not matched; db_default=""), match_extra JSON; set: set_local_pref, set_med, set_weight, set_origin, set_next_hop, set_as_path_prepend, set_communities M2M, set_communities_additive, set_metric_type, set_extra JSON; continue_seq |
BFDProfile |
catalog; min_tx, min_rx (ms, ≥ 1), multiplier (≥ 1), echo |
(tenant, name) |
RoutingKeychain |
algorithm (md5/sha1/sha256/hmac-sha-256); SecretBackedPSK - psk_secret_provider, psk_secret_path reference the key in the secret store. Also holds the MKA CAK for an interface's MACsec (Interface.macsec_keychain, see Interface) |
- |
RPKICache |
address (IP or hostname), port (default 3323, 1-65535), transport (tcp/ssh), preference (1-255), ssh_username (required for SSH), ssh_host_key; SecretBackedPSK under routing-rpki-caches/<id> holds the SSH private key (API ssh_private_key, write-only). TCP refuses the SSH fields |
(tenant, name) |
ROA is not a named catalog: tenant, prefix (normalised CIDR, v4 or v6),
max_length (prefix length to 32/128), origin_asn FK → ASN (PROTECT),
aggregate FK → Aggregate (optional, SET_NULL; the prefix must sit inside
it), description, tags, custom fields, numid. Unique
(tenant, prefix, max_length, origin_asn). routing.viewsets.slurm_document
turns a queryset into RFC 8416 SLURM (GET /api/routing/roas/slurm/).
Migration routing/0020.
Static routes¶
StaticRoute
| Field | Type | Notes |
|---|---|---|
tenant |
FK → Tenant |
|
device |
FK → Device |
CASCADE |
vrf |
FK → VRF |
null = global table |
prefix |
char(64) | normalised with ip_network(strict=True) |
prefix_obj |
FK → Prefix |
optional, SET_NULL |
kind |
nexthop / interface / blackhole / reject |
an interface route needs next_hop_interface and no address |
next_hop |
char(64) | normalised address; blank for a blackhole/reject |
next_hop_interface |
FK → Interface |
must be on device |
next_hop_vrf |
FK → VRF |
route leaking |
table |
int | kernel table for policy routing; null = main or the VRF's. Exclusive with vrf; 0 and 253-255 refused |
distance, metric, tag |
int | nullable |
bfd |
bool | |
status |
FK → Status |
scope staticroute |
Unique (device, vrf, table, prefix, next_hop, next_hop_interface) with
nulls_distinct=False, so the same path twice is refused while the same
prefix through another next hop (ECMP), or in another table, is not.
Policy rules¶
PolicyRule - one ip rule on a device or VM.
| Field | Type | Notes |
|---|---|---|
tenant |
FK → Tenant |
|
device / virtual_machine |
FK | exactly one (policyrule_device_xor_vm) |
family |
ipv4 / ipv6 |
derived from the prefixes when given |
priority |
int | unique per (owner, family) |
action |
lookup / blackhole / unreachable / prohibit |
|
table |
int | for lookup; exclusive with vrf; 0 and 253-255 refused |
vrf |
FK → VRF |
for lookup: the VRF's table |
from_prefix, to_prefix |
char(64) | normalised CIDR; a host is its /32 or /128 |
iif, oif |
FK → Interface |
on device |
vm_iif, vm_oif |
FK → VMInterface |
on virtual_machine |
fwmark |
int | |
invert |
bool | not |
status |
FK → Status |
the static-route statuses (scope staticroute) |
Site-scoped as device__site|virtual_machine__site; audited; RBAC type
policyrule.
BGP¶
| Model | Fields | Unique |
|---|---|---|
BGPInstance |
device, vrf (null = global), asn FK → ASN, router_id, cluster_id, graceful_restart, distance_ebgp/distance_ibgp/distance_local (all three or none), bestpath_multipath_relax, MPLS L3VPN on a per-VRF instance: vpn_export, vpn_import, vpn_label_export (auto or a number), vpn_nexthop_export; rpki_caches M2M → RPKICache; bfd, status (scope routinginstance), description, extra JSON |
(device, vrf), nulls not distinct |
BGPAddressFamily |
instance, afi_safi, networks JSON [CIDR], maximum_paths, maximum_paths_ibgp, import_policy, export_policy, extra |
(instance, afi_safi) |
Redistribution |
one parent (bgp_af; OSPF/IS-IS instances follow), source, policy, metric, level + family (IS-IS only; blank = the instance's level, IPv4), extra |
- |
BGPPeerGroup |
catalog + the shared knobs; remote_asn int, remote_asn_mode (asn/external/internal), local_asn FK, update_source text |
(tenant, name) |
BGPSession |
instance, name, peer_group, remote_asn (+ mode), local_asn, local_address FK → IPAddress, remote_address text xor interface FK, remote_address_obj (auto-linked), peer_device, peer_session one-to-one, the shared knobs (all nullable = inherit), status (scope bgpsession), description |
(instance, remote_address) / (instance, interface) conditional |
The shared knobs (_PeerKnobs): address_families JSON list, import_policy,
export_policy, bfd, ebgp_multihop, next_hop_self,
route_reflector_client, send_community, keepalive, hold_time,
keychain, default_originate + default_originate_policy,
capability_extended_nexthop (RFC 5549), ttl_security_hops (GTSM),
maximum_prefix with its details (below), allowas_in, as_override,
remove_private_as, soft_reconfiguration, extra. BGPSession.effective() resolves session → group →
instance (bfd), merges extra, and derives update_source from the local
address's interface.
maximum_prefix carries three details, on the shared knobs and on
BGPNeighborAF alike, for maximum-prefix N [threshold] [restart M |
warning-only]: maximum_prefix_threshold (percent, 1-100),
maximum_prefix_restart (minutes, 1-65535) and
maximum_prefix_warning_only (nullable boolean, so a session can switch a
group's value off as well as on). Each is nullable and inherits exactly as
maximum_prefix does. restart and warning_only on the same row are a
field error. The resolved values drop all three when no maximum is in
effect, and where inheritance brings both restart and warning_only the
more specific of the two wins. A family row that sets a detail with no
maximum anywhere in its chain (the row, its neighbour, the peer group's
row, the peer group) is refused; a neighbour-level detail is not, because
it may serve family rows that set the maximum. Migration routing/0021
copied integer, in-range extra.maximum_prefix_threshold and
extra.maximum_prefix_restart values into the empty fields and left
extra as it was.
BGPNeighborAF - one address family of a neighbour, a session or a peer
group (bgpneighboraf_one_parent), unique per parent and afi_safi:
activate (off prints no neighbor X activate), import_policy,
export_policy, prefix_list_in, prefix_list_out, default_originate +
default_originate_policy, next_hop_self, route_reflector_client,
soft_reconfiguration, as_override, remove_private_as, send_community,
allowas_in, maximum_prefix + its three details, extra. Every knob is nullable: null
inherits. routing.models.effective_afs(session) resolves each family and
knob, most specific first: the session's row, the session's own field, the
peer group's row, the peer group's field. The family set is the session's
active rows when it has any, else the group's. Site-scoped through the
session's box; a peer group's rows are catalog rows. Audited.
The address_families JSON list on sessions and peer groups stays as the
v0.16 view of the rows - the families with activate on. Writing the list
reconciles the rows (a listed family gets a row with every knob null; a
dropped one is deleted, or switched off when it carries a knob), and writing
a row rewrites the list (sync_af_rows / sync_af_mirror, wired as
signals in routing/apps.py). Migration routing/0018 backfilled one row
per listed family with every knob null, so no render changed. The list is
deprecated and goes no earlier than two releases on.
OSPF and IS-IS¶
| Model | Fields | Unique |
|---|---|---|
OSPFArea |
catalog; area_id (normalised: a number stays a number, a quad is a quad), kind |
(tenant, name) |
OSPFInstance |
device, vrf, process_id text, version ⅔, router_id, reference_bandwidth, passive_by_default, default_originate, bfd, status (routinginstance), description, extra; redistribution rows |
(device, vrf, version, process_id) |
OSPFInterface |
instance, interface (same device), area FK, cost, network_type, passive (null = instance default), priority, hello, dead, bfd, mtu_ignore, authentication + keychain |
(instance, interface) |
ISISInstance |
device, vrf, process, net (checked), level, metric_style, bfd, authentication + keychain, lsp_gen_interval, spf_interval, lsp_mtu, spf_init_delay/spf_short_delay/spf_long_delay/spf_holddown/spf_time_to_learn (spf-delay-ietf: all five or none), log_adjacency_changes, default_originate_ipv4/_ipv6 (""/on/always), status, description, extra; redistribution rows |
(device, process) |
ISISInterface |
instance, interface, families JSON (ipv4/ipv6, defaults to ipv4), level, metric, metric_l2, network_type, passive, hello_interval, hello_multiplier, bfd, authentication + keychain |
(instance, interface) |
| EIGRPInstance | device, vrf, asn (1-65535), name (named mode), router_id, k_values (five 0-255, normalised), variance, maximum_paths, passive_by_default, stub, bfd, status, description, extra; redistribution rows | (device, vrf, asn) |
| EIGRPInterface | instance, interface (same device), passive, split_horizon (null = default), hello_interval, hold_time, bandwidth_percent, summary_addresses JSON (checked networks), bfd, authentication + keychain | (instance, interface) |
Every _DeviceInstance, _IGPInterface row and _PeerKnobs carrier has
bfd_profile (SET_NULL) beside bfd; BGPSession.effective() resolves it
session → group → instance.
Redistribution has exactly one parent - bgp_af, ospf_instance,
isis_instance or eigrp_instance (CheckConstraint); source gains
eigrp.
Overlay¶
| Model | Fields | Unique |
|---|---|---|
api.L2VPN (extended) |
vrf FK, allowed on EVPN_TYPES only (clean()); vtep_memberships reverse |
(tenant, identifier) for type in VXLAN_TYPES (uniq_l2vpn_vxlan_vni) |
VTEP |
device OneToOne, source_interface (same device), source_ip, anycast_ip (assigned to the device), anycast_gateway_mac (normalised lower-case), arp_suppression, status (vtep), description, extra |
device |
VTEPMembership |
vtep, l2vpn (VXLAN type), vlan (at the device's site), interface (optional FK → api.Interface on the VTEP's device - the leaf's vxlan netdev; the VNI stays on the L2VPN), rd, ingress_replication, mcast_group, extra |
(vtep, l2vpn) |
| EthernetSegment | catalog; esi (type 0, ten octets) or es_id + sys_mac (type 3, normalised), df_preference (the default for every member), interfaces M2M → api.Interface through EthernetSegmentMember - the LAG on each leaf that shares the segment, so the ports are on different devices by design | (tenant, name) |
| EthernetSegmentMember | the through row: segment, interface, df_preference (null = the segment's). It sits on the table the plain M2M created (routing_ethernetsegment_interfaces, adopted in routing/0016 without a copy) and keeps that table's bigint id rather than a UUID, so the upgrade rewrites nothing. Site-scoped interface__device__site; audited | (segment, interface) |
| api.Interface.evpn_mh_uplink | evpn mh uplink on a fabric-facing port of a multihomed leaf | - |
MPLS¶
| Model | Fields | Unique |
|---|---|---|
LDPInstance |
device (one per device; vrf must stay null - LDP labels the global table), router_id, transport_address (blank = the router id), label_allocation (host-routes/all), interfaces M2M (same device), bfd, status, description, extra |
device |
The VPN side of an L3VPN sits on the per-VRF BGPInstance (vpn_*); the RD
and route targets come from the VRF.
resolve_membership_vlan(m) is the leaf's VLAN for a VNI: own vlan, else
the L2VPN's termination at the device's site, else its sole VLAN
termination. FHRPGroup gains the anycast protocol for the shared SVI
address. Migrations api/0165 (L2VPN.vrf, VNI uniqueness, l2vpn
statuses) and routing/0006.
Rendering¶
routing/render.py:routing_context(device) builds the routing block the
config renderer and the Ansible inventory carry - plain dicts, sorted, every
row with its id, never a secret. Derived keys a template would otherwise
compute for itself: level_frr on an IS-IS instance, interface row and
redistribution (level-1 / level-1-2 / level-2-only), spf_delay_ietf
as one object or None, default_originate as {family: mode}, a BGP
instance's distance as one object or None, a session's
remote_asn_effective (the number a running config shows - the local AS for
internal) and route_reflector_client_from_group (the group already says
it, so print it once), and used_bfd_profiles (only the profiles this device
names; bfd_profiles stays the whole catalog). Multihoming and MPLS:
by_interface[<port>].es (the segment this port is in, with every member
on every device; df_preference there is the port's effective value and
segment_df_preference the segment's), by_interface[<port>].evpn_mh_uplink,
ethernet_segments (with local_df_preference) + es_count per device, ldp (one block or None),
and a per-VRF BGP instance's vpn object or None. RPKI: rpki_caches
at the top (every cache the box's instances name, by preference, with
key_set and never the key), each instance's rpki_caches as names, and
match.rpki on a policy rule. keychains[].placeholder
is <keychain:NAME>, the contract form a push tool substitutes
(routing.render.KEYCHAIN_PLACEHOLDER_RE). It is registered through
api.export_templates.register_context_provider("routing", …) from the app's
ready(), so api never imports routing.
Registries¶
auth_api/object_types.py (group Routing; routingkeychain and rpkicache honour
reveal), audit/apps.py, api/search_index.py, api/status_registry.py
(staticroute, bgpsession, routinginstance, l2vpn, vtep),
auth_api/site_paths.py (device-bound rows → device__site, instance rows
→ instance__device__site, vtepmembership → vtep__device__site,
redistribution → its BGP address family's or IGP instance's device or VM),
the router in api/api_urls.py under routing/.