Reload Matrix
See when each configuration change takes effect.
See when each configuration change takes effect.
Reference for every user-facing config key: what does it take to put a change into effect?
This doc is the operator-facing index. The authoritative classification
lives in the source — neighbor_runtime_equal(), config_field_impact(),
neighbor_change_hot_applicable(), classify_sighup_reload(),
plan_reload_peer_actions(), and ConfigDiff (in
src/config/mod.rs), reload.rs (the route dispatch, the sequential
changed-neighbor hot/rebuild partition, and the
per-section error/warn arms) together with the pinning helpers
pin_unreconciled_daemon_runtime_fields /
pin_tcp_ao_startup_only_runtime / pin_bfd_startup_only_runtime /
pin_rfc8212_posture_startup_only it
invokes from src/config/mod.rs, and
the parse-time ConfigError family in src/config/validation.rs. If
the matrix and the code disagree, the code is right and the matrix has a
bug — file an issue.
Reload classes
| Class | Meaning |
|---|---|
| live | Change applies in place on SIGHUP or a supported runtime CRUD RPC without requiring a replacement session task. Enforcement of the new setting can still stop BGP, such as a lowered prefix limit exceeded by the current route count. The diff routes through neighbor_runtime_equal() / diff_neighbors() / diff_policy(). |
| reload-applied | Change hot-applies to a running subsystem reconciler or derived matcher on SIGHUP / supported runtime CRUD, but unlike per-session live the in-memory config snapshot advances only after the subsystem or snapshot consumer acks the new desired set. Used by [[fib_tables]] (ADR-0061 FIB reconciler) and [[dynamic_neighbors]] matcher rebuilds. Surfaced under the reload_applied.* keys in rustbgpd --diff --json. |
| restart-required | Change is accepted at parse time but pinned back to the live value for the duration of this reload — the new value won't take effect until the next daemon restart. Surfaced as an ERROR-level log line during reload. Until restart, rbgp config diff /etc/rustbgpd/config.toml still lists it, because the running snapshot keeps the pinned value. rustbgpd --diff compares two files, so it shows the change only before the new file is installed. |
| coordinator-gated | EVPN runtime tables: supported shapes hot-apply through the ADR-0063 coordinator, and the runtime snapshot advances only after the daemon actors accept the change; unsupported shapes pin back to the committed model (see the EVPN section below). |
These classes describe accepted changes. A candidate that fails parse-time validation is refused whole and never reaches a field class: the daemon refuses to start, or a reload keeps the running config. See Rejected configurations and Validation-only constraints.
SIGHUP reload routes
The classes above say what happens to one field. classify_sighup_reload()
in src/config/mod.rs says how a whole candidate is executed, and
reject_unappliable_sequential_reload() then rejects a sequential candidate
that carries changes that route cannot apply (below). rustbgpd --diff
prints the result as SIGHUP reload route:
| Route | Candidate | Guarantee |
|---|---|---|
| generation | Static or interface-only [[neighbors]], [peer_groups], BFD member attachments (including a [[dynamic_neighbors]] range's bfd), inline policy / neighbor sets / global chains, [policy.conditional_advertisements] definitions and neighbor or peer-group attachments, .rpol content, dataset contents, dataset bindings (added, removed, or re-mapped [policy.datasets] entries), or outbound prefix maxima changed without an incompatible family. This includes adding or removing a whole static neighbor that carries md5_password or ttl_security | One owned runtime generation: one action per static neighbor from one resolved candidate; a later failure restores retained state and rejects cleanly when compensation is confirmed. Uncertain settlement recovery-fences the daemon |
| sequential | No generation-class or dataset change, or a generation-class change together with TCP-AO rotation or a listener MD5/GTSM edit while dataset contents, dataset bindings, and BFD attachments are unchanged | The existing per-subsystem steps; a failure halts with an authoritative known-partial receipt or recovery-fences if state is ambiguous |
| rejected | Dataset content/binding or BFD attachment changes combined with TCP-AO rotation or a listener MD5/GTSM edit; a sequential candidate that adds, removes or edits an interface-only neighbor; a sequential candidate whose peer-group edit adds or changes a config-file-only group field (below), or that changes a conditional-advertisement definition or neighbor attachment; or a generation-class/dataset change combined with [[dynamic_neighbors]], EVPN runtime tables, [[fib_tables]], or honor_graceful_shutdown / honor_blackhole | No effect; apply independently reloadable families separately |
The sequential route applies peer-group edits as SetPeerGroup definitions,
which cannot carry the config-file-only group fields: admin_down,
admin_down_reason, tcp_mss, role, strict_role,
prefix_orf_receive, disable_ipv4_unicast, link_local_next_hop, bfd, the slow-peer knobs,
the per-family and received prefix limits, max_prefix_action,
max_prefix_warning_percent, next_hop_ownership, interpret_rfc1997,
rs_control_communities, send_non_transitive_extended_communities,
fast_external_failover, log_level, route_flap_dampening,
gr_eor_grace_time, and conditional_advertisements. A sequential candidate that adds or changes one of them is
rejected, and the reason names the group and field, for example
peer group "edge" strict_role changed together with listener inbound MD5/GTSM inventory. Split the reload: apply the TCP-AO or listener change
and the peer-group change separately. Outbound prefix maxima of a group
that already exists apply through their own step and do not cause this
rejection; on a group the same reload adds, they do. A tcp_mss change the
reload pins until restart does not cause it either.
A listener MD5/GTSM edit changes the inbound MD5 password or GTSM setting of
a static neighbor that stays configured, directly or through its peer group,
or of a [[dynamic_neighbors]] range. A static neighbor joining or leaving
with its own md5_password or ttl_security is not an edit. The generation
installs the joining neighbor's listener key or GTSM selector before it adds
the session, and withdraws a departing neighbor's entry only after the
session is removed. If the generation fails, the peer manager restores the
prior sessions first, and then the listener's prior MD5 keys and GTSM
selectors return. A departing neighbor's entry is still in place when its
session is re-added. A re-added session is new: its TCP connection, uptime,
and counters start again. If the generation applies but the withdrawal step
cannot reach the listener, the reload returns a known-partial receipt. The
entries it leaves cover only addresses that are no longer configured.
Disabled [policy.route_flap_dampening] parameter edits use the generation
snapshot too. A sequential candidate with incompatible families that edits
the block is rejected before any effect; there is no RIB activation yet.
Daemon restart-required fields are pinned on every route.
An explain-only change stays sequential; [policy.explain] is carried with the
candidate when another change selects the generation route.
Session-establishment caveat
Several live fields bind at session establishment (OPEN negotiation,
socket creation, or registration with the RIB manager), not mid-session.
Examples: md5_password, families, add_path, graceful_restart,
hold_time, min_hold_time, route_reflector_client. These are not
restart-required, but applying them takes a session reset — and on
SIGHUP reload of a static neighbor the reconciler performs that reset
immediately: any changed session-reset-class field routes the
neighbor through the session rebuild path (delete + re-add of the
session task), so the new value is negotiated right away rather than
waiting for a natural flap. The matrix calls this out per row as
"live (effective next session)"; rustbgpd --diff annotates these
fields "session reset".
An ordinary rebuild closes the old session with Cease/Administrative Shutdown,
without an RFC 8538
Hard Reset. Routes learned from that session are withdrawn
and re-learned, with one exception: if the old session has graceful_restart
enabled and the peer advertised GR with the Notification (N) bit, routes in
the peer's advertised GR families are held stale. Other families are still
withdrawn. Retention ends when the replacement session completes recovery or
the GR (and, where negotiated, LLGR) timers expire. This uses the old session's
negotiated capabilities and running configuration, including when the reload
changes the GR settings themselves. The explicit purge reset for
discard_path_attributes bypasses this retention.
Static-neighbor edits whose every changed field is hot-applied
(description, admin_down, admin_down_reason, max_prefixes, max_prefixes_ipv4_unicast,
max_prefixes_ipv6_unicast, max_prefixes_received_ipv4_unicast,
max_prefixes_received_ipv6_unicast, the non-unicast max_prefixes_<family> keys,
max_prefix_action, max_prefix_warning_percent, max_prefixes_out_ipv4_unicast,
max_prefixes_out_ipv6_unicast, max_prefix_restart_seconds,
gr_peer_restart_time_max, gr_stale_routes_time, gr_eor_grace_time,
local_ipv6_nexthop, remove_private_as, fast_external_failover, log_level, the
import/export policy and chain fields, and conditional_advertisements on
the generation route) are applied in place without
replacing the session task. Policy edits trigger the usual Route Refresh /
Adj-RIB-Out re-emit. Enforcement of newly applied limits can still stop BGP:
for example, with max_prefix_action = "shutdown", lowering a per-family
inbound cap below the current count tears down the session immediately. Mixing
a hot-applied edit with a session-reset edit on the same neighbor applies both
through one session rebuild.
In rustbgpd --diff --json, a field's impact: "hot_applied" describes
this in-place application path; it is not a promise that BGP stays Established.
impact: "session_reset" and the summary.sessions_will_reset count describe
session replacements required to apply the configuration. The count does not
predict additional stops caused by enforcement of the new limits or admission
rules, which depend on runtime state.
Transaction overlay
The matrix above describes what SIGHUP reload or targeted runtime CRUD does with
each config field. ADR-0076 config transactions add a stricter overlay:
PlanConfigTransaction may reject a SIGHUP-hot-applied change unless the daemon
has a rollback-capable transaction executor for that exact impact shape.
Current transaction support includes pure [[fib_tables]], pure
[[dynamic_neighbors]], static [[neighbors]] add/delete/modify,
interface-only [[neighbors]] add/delete/modify (alone or with catalog,
live-policy or reshape changes; see
Interface-only neighbors), catalog-only
policy / neighbor-set / peer-group / global-chain changes, pure live
policy-chain impact for static neighbors or accepted dynamic peers, and
peer-group/session reshape impact. Reshapes include peer-group field edits or
static-neighbor peer-group reassignments that require affected sessions to be
rebuilt; the transaction executor captures prior static peer configs and
restores them if apply or persistence fails, and after a successful persist it
gracefully resets the live dynamic sessions accepted by an affected range so
they re-accept under the committed config (ADR-0086). Targeted peer-group RPCs
and SIGHUP partition a group edit's changed fields by impact class: an all-live
change set applies inherited runtime knobs in place to static and accepted
dynamic members without replacing sessions. A set mixing in a session-reset, restart-required, or
unclassified field reshapes static members; accepted dynamic sessions keep
their running session settings until reconnect, except for the explicit
discard_path_attributes purge. The peer-group section below describes the
separate policy, prefix-limit and restart-scheduling updates.
Dynamic-range
peer-group reassignments and mixed policy/session effective-impact candidates
remain rejected even though SIGHUP can hot-reconcile some of those shapes
best-effort.
Identical peer-group or peer-group-membership mutations are treated as runtime
no-ops: they return success without publishing a policy event or rebuilding
sessions.
For grouped export-only changes, ADR-0105 documents the single-owner transaction, its one-cohort-plus-remainder partition, the RIB-local atomic commit boundary, and the compensating rollback used across session and RIB actors.
[[neighbors]]
The diff key is the (address, interface) pair. Changing either is
treated as delete + add by the reconciler — the old neighbor is torn
down, the new one starts fresh. remote_asn is not part of the diff
key: an ASN edit flows through reconcile as an immediate session rebuild
under the new ASN (the same delete + re-add semantics, applied in one
reload).
An accepted IPv6 link-local peer retains its interface scope during unrelated reloads and hot updates, even if the interface is temporarily missing. Changes that add or replace a session, including an interface-name change, still require fresh interface resolution before any reload effects. Configuration impact planning and policy-only transactions also retain the scoped peer in their policy targets without requiring a fresh interface lookup. Transaction edits that rebuild sessions still require fresh scope resolution during planning.
Administrative state
admin_down is the configured boot state and the runtime
rbgp neighbor <addr> enable|disable toggle stays transient
(ADR-0043):
- At startup, and whenever a neighbor is added,
admin_down = trueadds the peer disabled. It makes no connection attempts, refuses inbound connections, reads 0 inbgp_peer_admin_enabled, and stays listed inrbgp neighbor. - On reload, only a change to the resolved
admin_downacts. Setting it disables the peer: an Established session receives Cease/Administrative Shutdown withadmin_down_reasonas its RFC 9003 shutdown communication, inside a Cease / Hard Reset when the peer negotiated RFC 8538 Notification Graceful Restart, so neither side keeps the other's routes as stale. Clearing it enables the peer. - While the resolved value is unchanged, a reload keeps the runtime toggle. A
runtime
enableof a config-down peer therefore lasts until the next daemon restart or a reload that changesadmin_down; a runtimedisableof a config-up peer lasts the same way.
| Field | Class | Notes |
|---|---|---|
address | restart-required (identity) | Part of the diff key. Edit = delete + add. To change the peer address in place, delete the old neighbor (gRPC or remove from config + reload), then add the new one. |
interface | restart-required (identity) | Part of the diff key. Same as address. Used by IPv6 link-local + BGP unnumbered peering. |
remote_asn | live (session reset, identity) | Not part of the diff key: on SIGHUP the reconciler rebuilds the session immediately with the new ASN. Equivalent to delete + add of the neighbor — no daemon restart needed. Annotated "session reset: peer re-established with new ASN" by rustbgpd --diff. |
description | live | Metadata only; hot-applied in place — session task untouched. |
admin_down | live | Hot-applied in place through the operator disable/enable path; see Administrative state. Setting it sends Cease/Administrative Shutdown with admin_down_reason; clearing it starts the session. Mixed with a session-reset edit, the peer is rebuilt once and comes back in the new state; a rebuild that takes the peer down also sends admin_down_reason. A reload that fails and is compensated restores each peer's prior administrative state, including a runtime toggle. |
admin_down_reason | live | RFC 9003 shutdown communication, at most 128 bytes. A change is recorded in place and sent with the next admin_down shutdown. |
peer_group | live (session reset) | A reassignment changes the peer's effective inherited config, so SIGHUP reconcile (and the transaction session-reshape executor) rebuild the session. Group field edits on an unchanged membership hot-apply per the [peer_groups.<name>] table below. |
hold_time | live (effective next session) | Negotiated in OPEN. On SIGHUP the reconciler rebuilds the session immediately, so the new value is negotiated right away. |
min_hold_time | live (effective next session) | Validates the peer's next OPEN proposal. On SIGHUP the reconciler rebuilds the session immediately; existing sessions are not re-evaluated in place. |
send_hold_time | live (effective next session) | RFC 9687 send hold timer. On SIGHUP it is classified as a runtime-neighbor change, so the reconciler rebuilds the session immediately; the replacement per-peer writer captures the new value (including 0 = disable) when its TCP connection is established. |
slow_peer_threshold_pct | live (session reset) | Slow-peer detection backlog threshold, percent of the outbound writer buffer. Captured into the session's transport config; on SIGHUP the reconciler rebuilds the session immediately, so the new value applies right away. Annotated "session reset: session re-establish" by rustbgpd --diff. |
slow_peer_duration | live (session reset) | Seconds the backlog must persist before the slow-peer flag raises; 0 disables detection. Same capture and session-rebuild semantics as the threshold. |
slow_peer_isolation | live (session reset) | Move a flagged-slow peer to the per-peer update path. Same capture and session-rebuild semantics as the threshold. |
fast_external_failover | live | Fast external failover opt-out. Hot-applied in place: the peer manager reads it when the next interface-down event arrives, so no session is reset. |
max_prefixes | live | Threshold re-evaluated on every received UPDATE. |
max_prefixes_ipv4_unicast | live | Per-family IPv4-unicast inbound cap (ADR-0108), enforced independently of the aggregate max_prefixes. Hot-applied in place; the new threshold governs the next received UPDATE. |
max_prefixes_ipv6_unicast | live | IPv6-unicast sibling of max_prefixes_ipv4_unicast (ADR-0108). |
max_prefixes_received_ipv4_unicast | live | Pre-policy IPv4-unicast received-prefix cap (ADR-0108 amendment), enforced independently of the accepted-route caps. Lowering below the announced count enforces immediately. Adding the cap to an Established session starts tracking rejected identities and requests a plain route refresh for the family so already-rejected announcements are recounted; without negotiated route refresh the count is exact only for announcements after the change (logged). Removing the cap drops the tracked rejected identities and the *_received metric scope. |
max_prefixes_received_ipv6_unicast | live | IPv6-unicast sibling of max_prefixes_received_ipv4_unicast. |
max_prefixes_l3vpn_ipv4_unicast | live | Per-family VPN-IPv4 inbound cap, enforced independently of the aggregate and every other family. Hot-applied in place: lowering below the family's current count enforces immediately under shutdown; removing the cap drops its metric scope. |
max_prefixes_l3vpn_ipv6_unicast | live | Same as max_prefixes_l3vpn_ipv4_unicast, for its own family. |
max_prefixes_ipv4_labeled_unicast | live | Same as max_prefixes_l3vpn_ipv4_unicast, for its own family. |
max_prefixes_ipv6_labeled_unicast | live | Same as max_prefixes_l3vpn_ipv4_unicast, for its own family. |
max_prefixes_l2vpn_evpn | live | Same as max_prefixes_l3vpn_ipv4_unicast, for its own family. |
max_prefixes_ipv4_flowspec | live | Same as max_prefixes_l3vpn_ipv4_unicast, for its own family. |
max_prefixes_ipv6_flowspec | live | Same as max_prefixes_l3vpn_ipv4_unicast, for its own family. |
max_prefixes_rtc | live | Same as max_prefixes_l3vpn_ipv4_unicast, for its own family. |
max_prefix_action | live | Hot-applied; the new action governs the next evaluation. Leaving block clears its episodes and requests one route refresh per affected family; without that capability, peer reannouncement or reset is required. Switching to shutdown re-evaluates every per-family bound immediately (an over-limit family tears down at once). Switching to block never prunes: a family already above its bound simply withholds net-new prefixes until usage falls back under. |
max_prefix_warning_percent | live | Hot-applied; the threshold is re-evaluated immediately and each scope's once-per-crossing latch re-arms from the new value. |
max_prefixes_out_ipv4_unicast | live | RIB-owned outbound capacity (ADR-0113). Applies without touching the session. Adding or lowering is accepted only when the peer currently advertises at or below the candidate: an over-limit family rejects the whole edit (SIGHUP abandons the reload; a config transaction fails its precondition) and leaves the running maxima, admission state, Adj-RIB-Out, and wire state untouched — lowering is not an implicit pruning policy. A valid raise or removal schedules one coalesced, family-scoped resync. Commit-confirmed transactions may only tighten, because their automatic undo only loosens. |
max_prefixes_out_ipv6_unicast | live | IPv6-unicast sibling of max_prefixes_out_ipv4_unicast. |
max_prefix_restart_seconds | live | Manager-owned hold-down policy. A successful value change hot-applies without touching the session and reschedules any armed countdown to now + the new duration (the superseded deadline never fires); removing the value cancels the countdown; a rejected change preserves it untouched. The field does not retroactively arm an indefinitely latched peer. |
md5_password | live (effective next session) | TCP-MD5 keys are per-socket. On SIGHUP the reconciler rebuilds the session immediately, so the new key is installed on the rebuilt socket right away. |
tcp_ao | live (ordered rotation generations) / otherwise restart-required | SIGHUP can append non-preferred successor MKTs, then on a later SIGHUP select an already-installed successor as local RNext. Selection is one-shot observed across the affected protected-session cohort; predecessor deprecation metadata commits in that same immutable generation only after verified successor traffic increases beyond each affected socket's baseline. A later SIGHUP may delete only deprecated, unselected MKTs while preserving the exact owner set, survivor order, key definitions, and selected key. Adding and selecting together, setting Current, key edits/reordering, non-deprecated/selected-key deletion, or owner changes are rejected/pinned. Runtime config transactions remain conservatively restart-required because they do not run the SIGHUP coordinator. |
bfd | reload-applied | SIGHUP adds, removes, enables, or disables the member's BFD session, including the first BFD session after startup. New sockets are prepared before peer changes; the actor acknowledges the new session set before the runtime snapshot advances. Strict mode can withhold BGP until BFD permits it. A runtime neighbor create or delete registers or removes the session its own or peer-group bfd resolves to; the first session in a socket family opens that family before the peer is added. A session that cannot be derived (for example, its interface scope no longer resolves) or a family that cannot open rejects the create with no effect; if the family open is unacknowledged, the create reports an ambiguous outcome and BFD is fenced as after an uncertain reload. A strict member is withheld until its session is Up. Profile definitions remain restart-required; config transactions that change BFD membership are rejected (apply them through SIGHUP). |
tcp_mss | restart-required | TCP_MAXSEG is installed when sockets are created. Active opens use the neighbor's effective value; each bound passive listener socket carries the smallest effective value across resolved static neighbors of its own address family, and every accepted child inherits its family's clamp. A family whose resolved static neighbors set no clamp is left unclamped, so an IPv4 tunnel constraint no longer down-clamps IPv6 sessions. SIGHUP keeps the startup values. |
ttl_security | live (effective next session) | On SIGHUP the reconciler rebuilds the static session and replaces the listener selector; GTSM takes effect on the replacement TCP connection. |
ttl_security_hops | live (effective next session) | Inherited GTSM distance; a static session is rebuilt and the listener's inbound minimum is replaced by the SIGHUP coordinator. Runtime transactions remain restart-required because they cannot update the listener inventory. |
families | live (effective next session) | Address families to negotiate in OPEN. On SIGHUP the reconciler rebuilds the session immediately to negotiate the new set. |
required_families | live (effective next session) | OPEN-time minimum negotiated family set. Static peers are rebuilt; accepted dynamic sessions keep their running config until reconnect unless a committed config transaction bounces the affected enabled range after persistence. |
graceful_restart | live (effective next session) | GR capability advertised in OPEN. On SIGHUP the reconciler rebuilds the session immediately; route retention follows the session-establishment caveat. |
gr_restart_time | live (effective next session) | Advertised in GR capability. On SIGHUP the reconciler rebuilds the session immediately to advertise the new value. |
gr_peer_restart_time_max | live | Local-only cap on the received GR Restart Time. Hot-applied in place; the new value governs the next GR peer-down event and never changes the OPEN capability. |
gr_stale_routes_time | live | Used by the local stale-route reaper for received GR routes. Hot-applied in place; the new value governs the next GR peer-down event. |
gr_eor_grace_time | live | Planned-restart End-of-RIB grace window. Read only when a marker-backed restart starts, so a reload stores the value for the next planned restart and never changes a window already running. No session reset. |
llgr_stale_time | live (effective next session) | RFC 9494 LLGR capability stale time. On SIGHUP the reconciler rebuilds the session immediately to advertise the new value. |
local_ipv6_nexthop | live | Used on outbound advertisements; new value applied on next route emission. An eBGP session (not a route-server client) that established with no IPv6 next hop and withheld the IPv6 unicast family exports the family once a reloaded value supplies one: the RIB sends that session its full IPv6 unicast table and an End-of-RIB, without a session reset. Removing the value later keeps the family, and the exact-export preflight refuses each IPv6 route (missing_ipv6_next_hop). |
route_reflector_client | live (effective next session) | RFC 4456 RR-client flag affects iBGP best-path and reflection behavior. Registered with the RIB manager at session establishment; on SIGHUP the reconciler rebuilds the session and re-advertises under the new flag. Route withdrawal and GR retention follow the session-establishment caveat. Annotated "session reset: session re-establish" by rustbgpd --diff. |
orr_vantage | live (effective next session) | RFC 9107 ORR vantage point (the client's IGP location as a BGP-LS topology node), or "peer_address" for the peer's own peering address. Resolved to a concrete address during neighbor resolution and registered with the RIB manager at session establishment; on SIGHUP the reconciler rebuilds the session so the new vantage applies right away. Drives the vantage registry, cached SPF state, per-vantage best-path selection, and rbgp orr status. |
route_server_client | live (effective next session) | Transparent RS-client behavior on egress. Bound at session establishment; on SIGHUP the reconciler rebuilds the session so the new mode applies right away. |
send_non_transitive_extended_communities | live (effective next session) | Plain-eBGP opt-in for exporting non-transitive Extended Communities. SIGHUP rebuilds the session and the replacement export profile applies the value to the next advertisement; iBGP and route-server-client sessions remain preserving. |
per_client_best | live (effective next session) | RFC 7947 §2.3.2 per-client best-path selection mode. Registered with the RIB manager at session establishment (like orr_vantage); on SIGHUP the reconciler rebuilds the session so the new mode applies right away. |
next_hop_ownership | live (effective next session) | ADR-0107 pre-policy NEXT_HOP ownership enforcement for route-server clients (RFC 7948 §4.8). Bound at session establishment; on SIGHUP the reconciler rebuilds the session so the new mode applies right away. Annotated "session reset: session re-establish" by rustbgpd --diff. |
interpret_rfc1997 | live (effective next session) | RFC 1997 NO_EXPORT egress enforcement (derived default: true unless route_server_client is set). Same session-re-establish bucket as next_hop_ownership. |
rs_control_communities | live (effective next session) | RFC 7947 §2.3.2 / RFC 8195 route-server control-community enforcement (derived default: true when route_server_client is set). Same session-re-establish bucket as next_hop_ownership. |
role | live (effective next session) | RFC 9234 BGP Role capability — advertised in OPEN. Compatibility check + NOTIFICATION 2/11 enforcement happen at OPEN time, so role changes require a session bounce to renegotiate. The §5 OTC procedures (driven by the local role) re-evaluate against the next received/emitted UPDATE. |
strict_role | live (effective next session) | Strict-mode toggle. On SIGHUP the reconciler rebuilds the session immediately and applies the new requirement to OPEN negotiation. |
prefix_orf_receive | live (effective next session) | RFC 5291/5292 Address-Prefix ORF receive capability — advertised in OPEN. Like add_path/role, a toggle is reconciled by the ReconcilePeers delete/re-add path and takes effect on the next session; an established session keeps whatever ORF it negotiated. Reported by describe_neighbor_changes; a transaction-model edit is a supported [[neighbors]] modify. |
disable_ipv4_unicast | live (effective next session) | IPv6-only peering: drops IPv4 unicast from the advertised MultiProtocol capability and suppresses the RFC 4760 §8 implicit-IPv4 fallback — both OPEN-time properties, so a toggle takes effect on the next session. Rejected at load when the effective families resolve to ipv4_unicast only. |
link_local_next_hop | live (effective next session) | Experimental Link-Local Next Hop capability 77, advertised in OPEN. A toggle is reconciled by the ReconcilePeers delete/re-add path and takes effect on the next session. Rejected at load unless the neighbor is interface-bound IPv6 link-local. |
remove_private_as | live | Applied to every outbound advertisement once the session accepts the new value. Routes already advertised are re-emitted in the background after the reload returns, one peer at a time. |
discard_path_attributes | live (purge session reset) | Effective-list changes purge-reset the primary and any inbound collision candidate before rebuilding the static peer. Ordinary GR retention is bypassed: Cease/4 is sent normally, or RFC 8538 Cease/9 wraps Administrative Reset when Notification GR is negotiated. Previously accepted routes disappear before the replacement session can relearn them. None and an explicit empty list are effective-equivalent. |
add_path | live (effective next session) | RFC 7911 Add-Path send/receive modes and experimental Paths-Limit receive_max are negotiated in OPEN. On SIGHUP the reconciler rebuilds the session immediately; a lowered receive cap starts with fresh path accounting on the replacement session. |
log_level | live | Per-peer tracing level, replaced on SIGHUP without a restart. Each event in a session's span is checked against the current levels, so an edit reaches sessions already running as well as new ones, and an unchanged reload keeps them. The global RUST_LOG filter, including any span directives written there, stays restart-required (read once at startup). |
import_policy | live | Inline import statements; re-evaluated against all received routes on reconcile through Route Refresh. An edit that changes the import chain of an Established peer that did not negotiate Route Refresh is rejected with nothing mutated, because the routes that peer already sent cannot be re-evaluated; disable the neighbor (which withdraws its routes), apply the edit, then enable it. When [global] ebgp_requires_policy is on, an edit that moves this direction between explicit policy and the ADR-0112 reserved deny is a policy-presence transition: every affected peer is qualified for Route Refresh before any peer is modified, and one Established peer without the capability — or one down peer whose GR/LLGR stale routes the RIB still holds — rejects the whole edit with nothing mutated. |
export_policy | live | Inline export statements; re-evaluated against the Adj-RIB-Out on next distribution. |
import_policy_chain | live | Named-chain reference; same re-evaluation behavior, including the Route Refresh and policy-presence qualifications above. |
export_policy_chain | live | Named-chain reference; same re-evaluation behavior. |
conditional_advertisements | live (generation route only) | Attached [policy.conditional_advertisements] names (ADR-0137). An attachment edit commits with the reload generation without a session reset; the neighbor's Adj-RIB-Out is re-evaluated through the gate and its update-group membership follows. The sequential route rejects a candidate that changes an attachment; reload it separately. |
route_flap_dampening | live (disabled-only schema) | Optional alpha override. Effective eligible enablement is refused until runtime integration exists. Accepted edits preserve the config snapshot without a session reset; no route behavior changes. |
Interface-only neighbors
An [[neighbors]] entry with interface and no address
(ADR-0142) is keyed by
its interface. SIGHUP, config transactions and the neighbor and peer-group
RPCs add, delete and edit these neighbors without a restart. A SIGHUP carries
the change as one owned generation; a candidate that would take the
sequential route is rejected. A transaction stages the full candidate, and
nothing happens until the commit. AddNeighbor and DeleteNeighbor select
the neighbor by an empty address and its interface, and a SetPeerGroup
edit reaches its members as a reload does (see the
API reference).
The peer manager then brings each interface's state in line with the running configuration:
| Change | Effect |
|---|---|
| Neighbor added | Discovery starts on the interface. Adding the first interface-only neighbor also starts the discovery actor. A peer is created once an address is learned, as at startup. |
| Neighbor deleted | Its session ends, its Adj-RIB-In (including retained Graceful Restart and LLGR routes) is purged, and its RIB identity is released. This also releases the learned address it held or reserved, so another neighbor may take that address. Discovery stops on the interface, after a final Router Advertisement with lifetime 0 when it was advertising, and its peer="interface:<name>" metric series, including bgp_unnumbered_*, are removed, bound or not. Deleting the last interface-only neighbor stops the discovery actor and closes its raw sockets. |
Session settings edited, directly or through the peer group (remote_asn, including "external"/"internal", peer_group membership, timers, families, admin_down, max-prefix settings, description, and so on) | A bound peer is rebound at once to the same learned address under the new settings, including an address learned from an inbound connection. This resets the session and keeps the neighbor's RIB identity and a max-prefix shutdown. A changed admin_down takes effect; otherwise an operator's enable or disable is kept, as for a static neighbor. An unbound neighbor uses the new settings when it next binds. rustbgpd --diff counts the neighbor as a session reset. |
ttl_security, directly or through the peer group | A session-settings edit, rebound as above. When the change gives an interface-only neighbor GTSM, the IPv6 listener's outbound Hop Limit is raised to 255 before the neighbor can bind, so an RA-silent GTSM peer that dials in is learned. It is never lowered. A deleted or rebound neighbor's listener selector is removed after its peer. |
Policy-only edit (import_policy*, export_policy*, policy definitions) | Live, as for a static neighbor; the session is kept. A config transaction applies it to the bound peer through the live-policy executor, which restores the prior chains if persistence fails. |
tcp_mss, directly or through the peer group | restart-required. SIGHUP keeps the running neighbor for this reload, with its running peer group if the reload removes that group, and logs an ERROR. A new neighbor that would take a clamp, its own or a new group's, is held until restart. rustbgpd --diff reports it with the other tcp_mss changes and routes the rest of the reload as SIGHUP applies it; a config transaction rejects it. |
Neighbors whose settings did not change keep their sessions.
These changes are refused before any effect, with the running configuration kept:
- Adding the first interface-only neighbor when the daemon lacks
CAP_NET_RAW(the error names it) or the link monitor is not running. - Adding a static link-local neighbor at an interface-only neighbor's
learned endpoint, its address on the same interface, bound or still
reserved. The error is
duplicate_link_local_addressand names the interface. Delete that neighbor in an earlier change first. - Adding a static link-local neighbor at an address a learned endpoint holds
while a BMP collector refuses identity conflicts (
bmp_identity_conflict). - Giving neighbors that share a link-local address BFD, TCP MD5 or TCP-AO;
the error names the feature. Differing GTSM policies or
log_levelvalues are also refused when the sharing set includes a static neighbor. Interface-only neighbors sharing an address may differ in GTSM andlog_levelbecause those settings use their interface-scoped identities.
A SIGHUP checks them before its first effect, including an outbound prefix
maximum or listener authentication change, and discovery cannot bind a
static link-local address of the new configuration until the reload has
applied. A config transaction
checks them when it plans and again when it stages the snapshot.
AddNeighbor checks them before it changes the running configuration and
returns FAILED_PRECONDITION.
[global.unnumbered] stays restart-required (see [global]).
[peer_groups.<name>]
Peer-group fields mirror [[neighbors]] minus the identity triple
(address, interface, remote_asn), description, peer_group, and
TCP-AO; conditional_advertisements is inherited by static members only.
Inheritance is resolved at
each reconcile. Neighbor-level policy fields override inherited peer-group
policy fields. TCP-AO is never inherited: static neighbors and dynamic ranges
configure their keyring directly.
For the rows below, "Same as neighbor" applies to inheriting static members.
Session-shaping changes rebuild those members on SIGHUP. Accepted dynamic
members keep their running session settings until reconnect, except for the
explicit discard_path_attributes purge described below. A committed config
transaction can reset enabled dynamic members after persistence; see the
transaction overlay.
An all-hot group change applies inherited runtime knobs to accepted dynamic members in place, both through targeted peer-group RPCs and SIGHUP. This includes inbound prefix limits, local GR helper timers, and export next-hop/private-AS knobs. SIGHUP captures each member's live prior for generation compensation; a lost acknowledgement or uncertain restoration fences the reload. Inheritance uses the group that accepted the dynamic member, and preserves its session identity, interface, learned ASN and administrative state.
A mixed session-shaping group edit retains the reconnect boundary for those dynamic transport knobs. Resolved policy chains, RIB-owned outbound prefix maxima and manager-owned max-prefix restart scheduling still update through their separate paths. Per-peer tracing directives remain scoped to configured static neighbors.
| Field | Class | Notes |
|---|---|---|
admin_down | live | Same as neighbor for inheriting static members. Rejected on a group referenced by [[dynamic_neighbors]]. |
admin_down_reason | live | Same as neighbor. |
hold_time | live (effective next session) | Same as neighbor. |
min_hold_time | live (effective next session) | Same as neighbor; static members are rebuilt, while accepted dynamic members follow the group caveat above. |
send_hold_time | live (effective next session) | Same as neighbor. |
slow_peer_threshold_pct | live (session reset) | Same as neighbor; a group slow_peer edit is never all-hot, so static members are session-reshaped via the conservative fallback. |
slow_peer_duration | live (session reset) | Same as neighbor; same conservative-reshape fallback as the threshold. |
slow_peer_isolation | live (session reset) | Same as neighbor; same conservative-reshape fallback as the threshold. |
fast_external_failover | live | Same as neighbor. Config-file-only, so the sequential route rejects a change to it alongside a TCP-AO or listener edit (see above). |
max_prefixes | live | Same as neighbor. |
max_prefixes_ipv4_unicast | live | Same as neighbor; per-family ADR-0108 cap inherited by group members. |
max_prefixes_ipv6_unicast | live | Same as neighbor. |
max_prefixes_received_ipv4_unicast | live | Same as neighbor; pre-policy received cap inherited by group members. |
max_prefixes_received_ipv6_unicast | live | Same as neighbor. |
max_prefixes_l3vpn_ipv4_unicast | live | Same as neighbor; inherited by group members. |
max_prefixes_l3vpn_ipv6_unicast | live | Same as neighbor; inherited by group members. |
max_prefixes_ipv4_labeled_unicast | live | Same as neighbor; inherited by group members. |
max_prefixes_ipv6_labeled_unicast | live | Same as neighbor; inherited by group members. |
max_prefixes_l2vpn_evpn | live | Same as neighbor; inherited by group members. |
max_prefixes_ipv4_flowspec | live | Same as neighbor; inherited by group members. |
max_prefixes_ipv6_flowspec | live | Same as neighbor; inherited by group members. |
max_prefixes_rtc | live | Same as neighbor; inherited by group members. |
max_prefix_action | live | Same as neighbor; inherited by group members. |
max_prefix_warning_percent | live | Same as neighbor; inherited by group members. |
max_prefixes_out_ipv4_unicast | live | Same maxima semantics as neighbor, evaluated by effective value: one over-limit member — static or accepted dynamic — rejects a group-wide lowering before any sibling changes. An all-live group edit swaps the maximum in place on every inheriting member, static and dynamic, without touching a session; a change set that also moves a session-reset field reshapes static members as before. Down children inherit the committed value when they reconnect. |
max_prefixes_out_ipv6_unicast | live | IPv6-unicast sibling of max_prefixes_out_ipv4_unicast. |
max_prefix_restart_seconds | live | Inherited by group members. An all-live group edit applies in place to static and dynamic members without bouncing them; a mixed change set reshapes static members and manager-syncs dynamic ones. Committed config transactions also bounce enabled dynamic sessions; disabled dynamic peers retain admin state and adopt the new duration. An armed countdown reschedules to now + the new duration; removing the duration cancels it. |
md5_password | live (effective next session) | Same as neighbor — pinned by group, applied to the inheriting peer's next socket. |
bfd | reload-applied | SIGHUP reconciles inherited BFD for static members. A neighbor's own bfd block still overrides its group. Profile definitions remain restart-required; config transactions do not apply BFD changes. |
tcp_mss | restart-required | Inherited by static group members and included in the passive-listener minimum for the member's own address family only after resolution. Groups referenced by dynamic-neighbor ranges cannot set it. |
ttl_security | live (effective next session) | |
ttl_security_hops | live (effective next session) | Same as neighbor; changes to a dynamic range's listener selector require SIGHUP. |
families | live (effective next session) | |
required_families | live (static session reset; dynamic next reconnect) | Non-empty neighbor value overrides; empty/absent inherits. A committed config transaction classifies the effective change as SessionReshape and bounces affected enabled dynamic ranges after persistence. |
graceful_restart | live (effective next session) | |
gr_restart_time | live (effective next session) | |
gr_peer_restart_time_max | live | Inherited local helper cap. An all-live SIGHUP or targeted peer-group RPC swaps the cap in place on static and dynamic members alike; a change set that also moves a session-reset field rebuilds static members and leaves accepted dynamic members on their running cap until reconnect. A committed config transaction follows the transaction-overlay behavior above and bounces enabled dynamic members. |
gr_stale_routes_time | live | |
gr_eor_grace_time | live | Inherited by static members only; dynamic members never take part in a planned restart. Config-file-only: SetPeerGroup does not carry it, and the sequential route rejects a candidate that changes it (see above). |
llgr_stale_time | live (effective next session) | |
local_ipv6_nexthop | live | |
route_reflector_client | live (effective next session) | Same as neighbor; a toggle session-resets the inheriting static members. |
orr_vantage | live (effective next session) | Inherited RFC 9107 vantage; same semantics as the neighbor field. "peer_address" on a group backing a [[dynamic_neighbors]] range gives every accepted peer its own vantage. |
route_server_client | live (effective next session) | |
send_non_transitive_extended_communities | live (effective next session) | Inherited plain-eBGP export opt-in; same session-rebuild semantics as the neighbor field. |
per_client_best | live (effective next session) | Inherited per-client best-path mode; same semantics as the neighbor field. |
next_hop_ownership | live (effective next session) | Inherited ADR-0107 ownership enforcement; same semantics as the neighbor field. |
interpret_rfc1997 | live (effective next session) | Same as neighbor. |
rs_control_communities | live (effective next session) | Same as neighbor. |
role | live (effective next session) | |
strict_role | live (effective next session) | |
prefix_orf_receive | live (effective next session) | Group-level ORF toggle is caught by diff_peer_groups (whole-record compare) and named by describe_peer_group_changes; effective on the inheriting peer's next session. |
disable_ipv4_unicast | live (effective next session) | Group-level IPv6-only toggle; same OPEN-time semantics as the neighbor field, effective on the inheriting peer's next session. |
link_local_next_hop | live (effective next session) | Group-level capability 77 opt-in; same OPEN-time semantics as the neighbor field. Every inheriting neighbor must be interface-bound IPv6 link-local, and dynamic ranges may not use such a group. |
remove_private_as | live | |
discard_path_attributes | live (purge session reset) | Inherited by route-server clients. Static inheritors are purged and rebuilt. Enabled accepted dynamic inheritors are purge-reset in every collision generation and re-accept under the committed group value; a signaling failure is surfaced rather than reported as a clean replacement. Disabled/down dynamic peers take the value on their next accepted connection. |
add_path | live (effective next session) | |
log_level | live | Same as neighbor — inherited per-peer tracing level, replaced on SIGHUP; it reaches the group's running sessions. |
import_policy | live | Inline import statements inherited by peers that do not set their own import policy / chain. |
export_policy | live | Inline export statements inherited by peers that do not set their own export policy / chain. |
import_policy_chain | live | Named-chain reference inherited by peers that do not set their own import policy / chain; inheriting peers take the same ADR-0112 policy-presence qualification. |
export_policy_chain | live | Named-chain reference inherited by peers that do not set their own export policy / chain. |
conditional_advertisements | live (generation route only) | Attached [policy.conditional_advertisements] names (ADR-0137) inherited by static members that set no list of their own; dynamic members do not inherit them. An edit commits with the reload generation without a session reset; each inheriting member's Adj-RIB-Out is re-evaluated through the gate. Config-file-only: SetPeerGroup keeps the value, and the sequential route rejects a candidate that changes it. |
route_flap_dampening | live (generation route only, disabled-only schema) | Config-file-only alpha override; SetPeerGroup preserves it. Effective eligible enablement is refused. Accepted edits adopt with the generation; incompatible sequential edits are rejected. No route behavior changes. |
[[dynamic_neighbors]]
Direct TOML edits are reload-applied: on SIGHUP the peer manager swaps the
runtime config snapshot and rebuilds the live inbound-accept matcher, so adding,
removing, or editing a [[dynamic_neighbors]] block changes which future
inbound connections are accepted without bouncing existing sessions. Runtime
gRPC CRUD — rbgp dynamic-neighbor {add,delete}
(AddDynamicNeighbor / DeleteDynamicNeighbor) — uses the same reload-applied
matcher-update path: it updates the runtime config snapshot and inbound-accept
matcher, then persists the accepted change back to the TOML. Runtime CRUD and
SIGHUP reload share a coordinator lock, held through the persistence
acknowledgement, so reload sees either the pre-mutation TOML or the committed
post-mutation TOML.
The exception is direct tcp_ao on a dynamic range. SIGHUP can append a
non-preferred successor to an unchanged protected prefix owner, then select
that installed successor in a later observation-gated immutable generation.
Adding and selecting together, moving, editing, or reordering protected
owners/keys remains restart-required and pinned. Deletion is live only for
deprecated, unselected MKTs in an otherwise identical owner/key order.
Disjoint unprotected range edits can still reload normally.
| Field | Class | Notes |
|---|---|---|
prefix | reload-applied | Consulted on every inbound TCP accept. |
peer_group | reload-applied | Inheritance resolves when a passive session promotes to a managed peer. |
remote_asn | reload-applied | Validated against the OPEN's my_as at promotion. |
description | reload-applied | Metadata. |
bfd | reload-applied | Adding or removing a range that runs BFD is one sequential SIGHUP. For an added range, the reload opens its BFD socket family before its first effect (failure: rejected, no effect; unacknowledged: fenced); a family opened by a reload that fails later stays open and inert. A removed range's running sessions keep their BFD sessions until they end. Editing bfd on an existing range is a BFD member attachment change: the reload generation registers, replaces or removes each running session's single-hop BFD session without a BGP reset, with the generation's preflight and fence. That edit combined with another range change is rejected with its own message. Runtime CRUD carries no bfd and cannot delete a range that runs it; config transactions that change a range's bfd are rejected. |
tcp_ao | live (ordered rotation generations) / otherwise restart-required | Append-only non-preferred successors install on SIGHUP; a later SIGHUP may select an installed successor and observation-gate predecessor deprecation in the same generation; a still-later SIGHUP may delete deprecated, unselected MKTs without changing the owner or survivor order. Protected owner/auth/key-order edits and non-deprecated/selected-key deletion remain pinned. Runtime CRUD/transactions remain restart-required. |
[global]
The [global] section is mostly restart-required because its values
feed daemon-wide subsystems (router-id, listen socket, telemetry sinks)
that are stood up once at startup. Three fields are not restart-required:
honor_graceful_shutdown, honor_blackhole (with a FIB-discard caveat), and
dynamic_neighbor_limit.
A restart-required [global] edit is reported by field, with its old and new
value where it can be displayed. gRPC bearer-token and TLS credential file
paths are redacted. The SIGHUP [global] changed ERROR line carries a
fields value such as router_id: 10.0.0.1 → 10.0.0.9, telemetry.log_format: json → text; rustbgpd --diff lists each field under [global] changed and
in the JSON global_changes array; and a config transaction's
restart_required_sections (shown by rbgp config plan and
rbgp config diff --history N) adds one [global].<field> name after
[global], without values. Fields reported on
their own terms stay out of that list on every surface: the honor knobs and
dynamic_neighbor_limit (hot-applied), the BLACKHOLE FIB discard knobs (their
own ERROR and blackhole_fib_discard_changed), and ebgp_requires_policy
(the RFC 8212 posture line).
| Field | Class | Notes |
|---|---|---|
root config_epoch | restart-required | ADR-0119 semantic epoch. Omission means epoch 1. A SIGHUP reports and pins raw/effective/source drift with the RFC 8212 boolean tuple. Epoch 2 with an omitted boolean resolves to the activated secure default: effective true, source epoch_2_default. Exception: a SIGHUP of a file carrying exactly the canonical form of the running tuple (the explicit effective epoch and boolean the daemon writes after a runtime mutation) keeps the running tuple without logging an ERROR, because the effective posture did not change. A partial edit or a changed effective value is still pinned and logged. |
asn | restart-required | Identity. |
router_id | restart-required | Identity. Advertised in every OPEN. |
listen_port | restart-required | The listen socket is created at startup. |
listen_addresses | restart-required | Exact passive-bind and active-open source endpoints are selected at startup. SIGHUP preserves the desired edit but pins the running endpoint set; a peer in a newly requested family is rejected before runtime mutation. |
cluster_id | restart-required | RFC 4456 cluster identity; affects every iBGP advertisement. |
honor_graceful_shutdown | live | Hot-applied by reload.rs. Re-evaluates the GShut LOCAL_PREF de-preference against existing Adj-RIB-In on toggle. Best-effort fan-out; see Honor-knob partial apply. |
honor_blackhole | live (with FIB-discard caveat) | Hot-applied when [global] install_blackhole_discard is false. When the FIB-discard reconciler is configured (install_blackhole_discard = true and the FIB table is set up), honor_blackhole is restart-required — toggling it would change the discard-spawn-gate decision made at startup. Logged as ERROR during reload in that case. Best-effort fan-out; see Honor-knob partial apply. |
ebgp_requires_policy | restart-required | ADR-0112/0119 RFC 8212 enforcement mode and raw-presence verdict. Pinned with config_epoch as one startup tuple: a SIGHUP reports value or representation drift in --diff and the v1 transaction rejection, logs an ERROR, and keeps the running import/export treatment and source verdict at startup. Exception: a SIGHUP of a file carrying exactly the canonical form of the running tuple (the explicit effective epoch and boolean the daemon writes after a runtime mutation) keeps the running tuple without logging an ERROR, because the effective posture did not change. A partial edit or a changed effective value is still pinned and logged. |
install_blackhole_discard | restart-required | The RFC 7999 kernel-discard reconciler spawns once at startup. |
allow_blackhole_broad_prefixes | restart-required | Same — feeds the discard-spawn gate. |
blackhole_discard_max_active | restart-required | The reconciler captures the active-discard cap at startup; SIGHUP pins the running value. |
blackhole_discard_install_rate_per_minute | restart-required | The reconciler captures the install-attempt rate at startup; SIGHUP pins the running value. |
blackhole_discard_install_burst | restart-required | The reconciler captures the install-attempt burst at startup; SIGHUP pins the running value. |
multipath_relax | restart-required | RIB best-path tie-break behavior; reconciling mid-flight would require an Adj-RIB-Out rebuild. |
link_bandwidth_weighted | restart-required | Weighted-multipath behavior (ADR-0068). |
fast_external_failover | restart-required | Daemon-wide default for the neighbor and peer-group knob. SIGHUP pins the running value; set the neighbor or peer-group key to change one session without a restart. |
max_as_path_length | restart-required | Threaded into each session's transport config when the peer is built; running sessions keep the ceiling they started with. |
dynamic_neighbor_limit | reload-applied | Admission cap compared live against the dynamic-peer counter (inbound admission and LRU eviction bound); nothing is pre-allocated. SIGHUP updates the admission ceiling immediately; existing dynamic sessions are preserved even if the new limit is below current occupancy, and headroom metrics update on the snapshot swap. |
worker_threads | restart-required | Tokio runtime worker-thread count; the runtime is built once at startup. Unset caps to min(CPU parallelism, 8); RUSTBGPD_WORKER_THREADS overrides. |
gr_eor_replay_owners | restart-required | The RIB takes the listed replay controllers once at startup, alongside the planned-restart End-of-RIB grace windows; SIGHUP pins the running list. |
warm_cache_checkpoint_on_shutdown | restart-required | The shutdown checkpoint writer and its pinned runtime-state directory are selected at startup. |
runtime_state_dir | restart-required | File-system paths (gr-restart.toml, fib-owned.json, grpc.sock) are bound at startup. |
[global.unnumbered] (router_advertisements, ra_interval_secs) | restart-required | The discovery actor takes its Router Advertisement template and timing when it starts. SIGHUP pins the running values and logs an ERROR; interface-only neighbors themselves still reload. |
Honor-knob partial apply
A honor_graceful_shutdown or honor_blackhole change recomputes the
effective import and export chains of every EBGP peer. The fan-out is
best-effort: the peer manager installs the new knob value even when it
leaves some peers behind, and the running config advances with it. A peer
is left behind when:
- its chains could not be resolved;
- its session did not acknowledge the new chains (a policy update timeout or a departed session task), so the daemon keeps recording its prior chains; or
- it took the new chains but still owes follow-up work: the RIB rejected its
new export chain, or the Route Refresh that re-evaluates its
Adj-RIB-Inwas rejected or withheld because its session state query was not answered. A peer positively known to be down owes no refresh and is not reported; it re-establishes under the new chains.
The reload receipt reports that step as known_partial. The step's [global]
target counts as applied. Each left-behind peer is a failure and an
unapplied identity named by its peer key, under the bucket
honor_graceful_shutdown.apply or honor_blackhole.apply. Unlike other
sequential-route failures, the reload continues with its remaining steps.
The receipt describes only the latest SIGHUP. The per-peer WARN log lines
remain.
Nothing retries a left-behind peer on a timer. The next SIGHUP does, even with
the file unchanged, so the operator action is to fix the cause and send
SIGHUP again (or run rbgp reload). After a known_partial honor step, each
later sequential-route SIGHUP, including the follow-up reload for a SIGHUP
coalesced during another reload, runs that step again with the unchanged knob
value. The re-drive retargets only the EBGP peers whose installed chains
differ from the running config or are unknown, or that still owe a Route
Refresh or export apply; every other peer gets no session command. The step
is then receipted applied once those peers acknowledge, or known_partial
again, naming each peer still behind. A peer deleted in the meantime is no
longer retried. Only a run of the step settles the retry: a reload rejected
before any effect, one that stops before its honor step, and one that takes
the generation route all leave it owed for the next sequential SIGHUP. The
retry is held in daemon memory, and a restart reapplies every peer anyway.
These also retarget a left-behind peer:
- The next reload that takes the generation route. That needs a
generation-class change (static or interface-only
[[neighbors]],[peer_groups], inline policies, neighbor sets, global chains,route_flap_dampening, conditional advertisements,.rpolcontent, datasets, BFD member attachments or outbound prefix maxima) without a TCP-AO rotation or listener MD5/GTSM edit, which move the reload to the sequential route (SIGHUP reload routes). The generation resolves each live peer against the candidate and reapplies each one whose installed chains differ or are unknown, or that still owes a refresh. A dynamic peer whose chains still cannot be resolved keeps its prior chains. The generation requires every reapplied peer to converge cleanly, so while a left-behind peer still does not answer, it rejects the operator's unrelated edit and restores the prior generation. - A later per-peer policy apply that reaches the peer: a sequential policy, peer-group or neighbor edit or a runtime policy mutation that touches it, or a full validation-state refresh, which delivers an owed Route Refresh.
- A later change to the knob, including reverting it.
- A daemon restart.
A session that did not acknowledge a policy update may still have installed it after the deadline. The daemon keeps recording the prior chain for that peer but treats the session's installed chain as unknown, so the next apply that reaches the peer, such as a revert of the knob, resends its chain and refreshes even when the chain matches the record. A later acknowledged update clears that state.
apply_bum_enforcement is restart-required but is a top-level
(document-root) key, not a [global] key — EVPN BUM-port enforcement is
pinned per ADR-0057.
[global.telemetry]
| Field | Class | Notes |
|---|---|---|
prometheus_addr | restart-required | The exporter listener binds at startup. |
dataplane_readiness | restart-required | The alpha /dp-readyz probe and its worker inventory are selected at startup. |
log_format | restart-required | The log subscriber is installed once at startup; a reload keeps the running "json" or "text" format. Other values fail config parsing before reload mutation. |
[global.telemetry.grpc_tcp] and [global.telemetry.grpc_uds]
Pinned by the reload path — both transports stand up once and don't rebind on reload.
| Field | Class | Notes |
|---|---|---|
address | restart-required | Listener address. |
enabled, max_tier, principal | restart-required | The whole listener config is pinned to the live listener on reload. |
tls_expiry_warning_seconds (grpc_tcp) | restart-required | Pinned with the rest of the listener config. |
tls_client_crl_file path (grpc_tcp) | restart-required | Adding, removing, or moving the CRL is pinned with the listener; the CRL bytes behind an unchanged path reload with the other credentials. |
| credential bytes behind unchanged token/TLS paths | reload-applied | Staged for all listeners and published as one atomic generation after the runtime reload is acknowledged; existing connections/streams survive. |
| token/TLS paths or auth mode | restart-required | Listener shape and configured paths remain pinned. |
path (grpc_uds) | restart-required | UDS path bound at startup. |
mode (grpc_uds) | restart-required | Permissions set at bind time. |
[policy]
The [policy] section is the one part of the config that supports
genuinely structural hot-reload — named definitions, neighbor-sets, and
chains all add/change/remove cleanly via reload.
| Field | Class | Notes |
|---|---|---|
definitions (named) | live | Add/remove/edit named policy definitions; re-evaluated on the next distribution pass. |
neighbor_sets (named) | live | Add/remove/edit named neighbor sets; the resolved set drives per-peer chain bindings. |
import_chain (named) | live | Reorder, add, or remove named imports. Removing the last entry while eBGP peers inherit it is a fleet-wide ADR-0112 policy-presence transition: it is qualified for Route Refresh across every affected peer first, and rejected whole if any peer cannot converge it. |
export_chain (named) | live | Reorder, add, or remove named exports. |
[policy.route_flap_dampening] | live (generation route only, disabled-only schema) | Validate the parameters and adopt the disabled block with the generation snapshot. Effective eligible enablement is refused in both modes. Incompatible sequential edits are rejected; there is no RIB install or route effect yet. |
[policy.conditional_advertisements] | live (generation route only) | Add, remove, or edit named conditional-advertisement definitions (ADR-0137). A definition must name defined policies and a nonempty set of exact unicast condition prefixes. Edits commit with the reload generation; the sequential route rejects a candidate that changes a definition. Unchanged content (mode, prefixes, settle_time, and both compiled policies) keeps its state and resyncs nothing; new or changed content, including an edit to a referenced policy, is evaluated immediately and resyncs the attached neighbors. A failed generation restores the prior applied state and settle deadlines. |
rpol_files | live | SIGHUP recompiles the referenced .rpol files and hot-applies materially changed chains to exactly the affected peers (Route Refresh for changed import chains). Config transactions reject a candidate whose compiled .rpol registry changed as unsupported — the files live outside the candidate TOML (src/config/mod.rs, transaction classification) — so apply .rpol changes via SIGHUP. |
rpol_roots | live | Extra import resolution roots; a change takes effect through the same SIGHUP recompile path (it matters only when it changes the resolved module graph's content, which reloads as an rpol content change). |
rpol_max_graph_bytes | live | Read from the incoming config on every load (load_rpol_files consumes it before compiling each unit), so the value in the reloaded file governs that same SIGHUP's recompile — no restart, no second reload. A candidate/reloaded config whose units exceed its own budget is rejected whole; the running generation is untouched. |
require_passing_tests | live | Read from the incoming config on every load, like rpol_max_graph_bytes: with it on, a SIGHUP whose .rpol units have a failing in-language test is rejected before any runtime effect (the error names the file, the test, and the expected and actual outcome), and the running generation is untouched. Turning it on while the loaded units fail their tests rejects that same reload. Config transactions reject a change to it as unsupported, like the other .rpol load settings. |
[policy.datasets] | live | SIGHUP stages content for generation settlement through the stable live handles and refreshes referencing peers. Export re-evaluation reaches every member of the referencing peers' update groups and takes one of three paths. A per-peer full resync is used when any of them has no live outbound registration or sends a family other than IPv4/IPv6 unicast and VPNv4/VPNv6, when a VPN best-path selection is held by graceful-restart deferral, or while any conditional advertisement is installed. Otherwise only the routes whose prefix (a VPN route's inner prefix) or origin AS the old and new contents answer differently are re-evaluated, provided every export chain probes the swapped dataset only with route.prefix in or route.origin-as in, no chain reads a different dataset handle of the same name, and no other publication of that dataset intervened. If any of those three conditions fails, the full re-evaluation runs once per update group and sends members only the routes whose export changed (see refresh and observability). Content-equal re-reads are no-ops; malformed input rejects before publication. Adding, removing, or re-mapping an entry (a member's datasets, say) rides in the same generation: a new dataset must load cleanly or the candidate is rejected at load, a removed one must no longer be declared, and a re-mapped one is a content change through its existing handle. Compensation restores prior contents at a new generation and the prior binding set with the prior config; see dataset settlement. |
[policy.explain] enabled (ADR-0073) | restart-required (per peer) | Read by build_transport_config when a session is constructed, so the new value is adopted into the config snapshot (sessions established after the reload honor it) but live sessions keep their current import-explain write behavior until they re-establish. Logged as WARN during reload when changed. Diagnostic retention only — never affects which routes are accepted. |
[policy.explain] cache_size (ADR-0073) | restart-required (per peer) | Same — the per-session LRU is sized at session construction. A live session's cache is not resized in place; the new capacity applies on its next establishment. |
[policy.reject_retention] enabled | restart-required (per peer) | Same contract as [policy.explain]: read by build_transport_config at session construction. Live sessions keep their current rejected-route retention behavior until they re-establish. Diagnostic retention only — never affects which routes are accepted. |
[policy.reject_retention] capacity | restart-required (per peer) | Same — the per-session rejected-route store is sized at session construction; the new capacity applies on the peer's next establishment. |
[rpki], [bmp], [mrt]
| Section | Class | Notes |
|---|---|---|
[rpki] | restart-required | RPKI VRP tables + cache connections stand up once at startup. |
[bmp] | restart-required | BMP exporter binds once. |
[mrt] | restart-required | The MRT manager takes its writer settings, including max_files, at startup; the output directory is prepared and checked before each dump. |
The SIGHUP error and config diff name the edited field, for example
cache_servers[0].refresh_interval under [rpki]. Indices are zero-based
positions in the configured lists. The JSON diff exposes rpki_changes,
bmp_changes and mrt_changes. Transaction responses retain each section
name and add its qualified field names to restart_required_sections.
The diff and log show old and new values for numeric endpoints, timers,
limits, flags and protocol settings. They show only the field name for RTR
MD5 passwords and TCP-AO keys, BMP system names and descriptions, and MRT
output directories and filename prefixes. The text diff marks those values
as <changed>. The JSON diff uses null for their old and new values,
including when a whole section or cache server is added or removed.
ADR-0134 proposes reload-applying these sections for subsystems already enabled at startup; until an implementation ships they remain restart-required.
[gnmi_dialout]
| Section | Class | Notes |
|---|---|---|
[gnmi_dialout] (whole section) | reload-applied | SIGHUP reconciles the dial-out target set in place: removed targets stop (their gnmi_dialout_connected{target} series is reaped), added targets start, changed targets tear down and redial, unchanged targets keep their live collector connection. The new section is validated during reload preflight; a rejected config leaves the running targets untouched. TLS key/cert file contents rotate without any reload — the files are re-read on every (re)connection attempt. |
EVPN coordinator sections
[[evpn_instances]], [[evpn_ip_vrfs]], and [[ethernet_segments]] reuse
the ADR-0063 EVPN runtime coordinator on SIGHUP for the same supported live
shapes as EvpnService.ApplyEvpnRuntime: single L2VNI/IP-VRF/ES
add/delete/redefine within the documented identity bounds, atomic tenant
teardown, ip_vrf relink, additive build-up, and standalone L2VNI swaps that
only combine L2VNI adds with standalone L2VNI deletes, plus L2VNI-only batch
redefines that do not relink IP-VRF membership. Mixed edits beyond those
shapes now hot-apply through the #268 plan decomposer: the candidate is
split into an ordered sequence of already-supported primitive plans (deletes
→ redefines → ip_vrf relink → adds), each committing its own runtime
generation — one SIGHUP produces N generations in rbgp/gRPC runtime
snapshots and logs, one per step. Every step is validated up front, before
anything commits; a candidate with an unsupported step (an IP-VRF
L3VNI/device/table identity redefine, or a shape the fixed phase order
cannot express — relink away from an IP-VRF deleted in the same candidate,
relink onto an IP-VRF added in the same candidate, an ES left memberless
mid-sequence) fails closed naming the offending step. A residual
mid-sequence convergence failure stops the sequence: generations committed by
earlier steps stay committed (no cross-step rollback). A fully compensated
failing step preserves the prior model; unrestored or unacknowledged effects pin
the coordinator. SIGHUP fences either partial sequence for recovery. The runtime
snapshot advances only after the coordinator and daemon actor converger
accept the candidate. Unsupported shapes, missing EVPN actors, or actor
convergence failure are pinned back to the committed runtime model and
logged at ERROR, so repeated SIGHUPs keep surfacing the drift. Static
rustbgpd --diff is shape-aware: it lists coordinator-supported EVPN edits
under reload-applied — a decomposable mixed edit shows as "hot-applied
through the ADR-0063 coordinator (decomposed: N steps, one runtime
generation each)" — and keeps undecomposable mixed edits or restart-only
identity changes in restart-required. The static diff still cannot predict
live actor availability or a later convergence failure; those remain runtime
SIGHUP outcomes.
| Section | Class | Notes |
|---|---|---|
[[evpn_instances]] | coordinator-gated | Supported ADR-0063 L2VNI shapes hot-apply, including standalone L2VNI swaps and L2VNI-only batch redefines; mixed edits decompose into ordered primitive steps (#268), one committed generation per step; undecomposable shapes, missing actors, or convergence failure pin/log. |
[[evpn_instances]].duplicate_ip_detection | coordinator-gated | Uses the full L2VNI redefine path even for a diagnostic-only edit: withdraws/replays local routes and clears duplicate-MAC quarantine. Clears IP move windows and removed-owner history while seeding preserved local/remote bindings without recounting them. Disabled by default. |
[[evpn_ip_vrfs]] | coordinator-gated | Supported IP-VRF add/delete/redefine and ip_vrf relink hot-apply, including decomposed mixed edits (#268); L3VNI/device/table identity changes stay restart-required by design — kernel VRF identity lifecycle (destroy + recreate); a runtime drain/recreate risks a dual-state window (see the ADR-0063 amendment). |
[[ethernet_segments]] | coordinator-gated | Supported ES add/delete/redefine and atomic tenant teardown hot-apply when the segment actor can converge; the first segment on a daemon started without one starts the actor live; mixed edits decompose (#268) with ES redefines applied one segment per generation. |
[evpn_core_isolation] | coordinator-gated | ADR-0140 core-isolation hold. Commits with the EVPN runtime config (a no-op plan for the EVPN model, like an interface-only edit), then republishes to the hold controller: enabled, uplinks and both timers apply live, and a changed timer keeps the hold's running clocks. Disabling the table or removing a binding releases the affected links at once; enabling it after startup arms no startup hold. rustbgpd --diff lists it with the EVPN runtime coordinator. See [evpn_core_isolation]. |
[managed_netdevs] | restart-required | ADR-0091 bridge, fixed-VNI VXLAN, SVD / collect-metadata VXLAN, VLAN upper, VRF, and L3VXLAN lifecycle is resolved at startup and reconciled by the dataplane actor (create, stamp, restart adoption, same-owner orphan reap). Managed netdevs are not live-mutable in this tranche. |
[[fib_tables]] and FIB runtime
| Section | Class | Notes |
|---|---|---|
[[fib_tables]] | reload-applied | Hot-applies to the running ADR-0061 FIB reconciler on SIGHUP (add/remove a table; change allowed_neighbors / allowed_peer_groups / max_routes / ECMP caps / families). Snapshot advances only after the actor acks. Starting FIB from an empty config (reconciler not spawned) still requires a restart. |
[global] install_blackhole_discard (FIB-side) | restart-required | See [global] above. |
[[bfd_profiles]]
| Section | Class | Notes |
|---|---|---|
[[bfd_profiles]] | restart-required | pin_bfd_startup_only_runtime preserves the running profile definitions. A member can attach to an existing profile on SIGHUP; adding or editing a profile requires a restart. A candidate that cannot resolve its BFD references against the running profiles is rejected before runtime mutation. |
[security.grpc.*]
| Field | Class | Notes |
|---|---|---|
[security.grpc] enforcement | restart-required | tier is the sole typed value, consumed by the gRPC interceptor at server bind time. Retired legacy is invalid config and receives migration guidance rather than a runtime class. |
[security.grpc.roles] | restart-required | Principal → role (observer / automation / operator) map read at bind. The per-method tier matrix is compiled into crates/api/src/authz.rs and is not runtime-configurable. |
[flowspec] (ADR-0135)
The RIB's receive-side feasibility mode is fixed at startup. SIGHUP retains that running value while keeping the operator's edited desired configuration; subsequent diffs still report the restart requirement. Config transactions reject changes to this section.
| Field | Class | Notes |
|---|---|---|
validation | restart-required | "off" (default, including an omitted table) preserves existing behavior. "rfc9117" enables received IPv4/IPv6 FlowSpec cross-RIB feasibility checks. Both enabling and disabling require a restart. |
[inbound_admission] (ADR-0120)
The per-source accept-rate limiter is built once by the accept-path
owner at startup; hot-applying an aggregation-length or capacity change
would invalidate every live bucket and re-open a fresh burst allowance
v1 pins every field as restart-required and surfaces the change as an
ERROR-level log line during reload.
| Field | Class | Notes |
|---|---|---|
enabled | restart-required | Off (default) ⇒ accept behavior unchanged; the limiter is never built. |
rate_per_minute | restart-required | Token-bucket refill rate per source aggregate. |
burst | restart-required | Token-bucket depth per source aggregate. |
v4_aggregation_len | restart-required | IPv4 bucket-key prefix length (8–32). |
v6_aggregation_len | restart-required | IPv6 bucket-key prefix length (16–128); default /64 because per-/128 accounting is trivially evadable. |
table_capacity | restart-required | Fixed LRU tracking-table capacity (64–65536). |
Rejected configurations (parse-time)
These are the ConfigError variants in src/config/validation.rs that
refuse a config outright. The daemon either fails to start (initial
load) or rejects the reload and keeps running on the previous config
(SIGHUP).
| Validation rule | Trigger | Notes |
|---|---|---|
route_flap_dampening effective enablement | Eligible static or dynamic eBGP neighbor resolves true | Runtime integration is not implemented; explicit true on iBGP or route-server clients is also refused. Inherited settings do not apply to these excluded roles. |
| Dampening parameter constraints | [policy.route_flap_dampening] timers or thresholds are invalid | Validated even while disabled; suppress must not exceed the computed ceiling. |
strict_role requires role | [[neighbors]] strict_role = true without role | RFC 9234 requires Roles to be configured before strict mode is meaningful. |
disable_ipv4_unicast requires a non-IPv4-unicast family | [[neighbors]] disable_ipv4_unicast = true with effective families resolving to ipv4_unicast only | The combination is contradictory: the session could never negotiate any family. |
link_local_next_hop requires an interface-bound link-local neighbor | Effective link_local_next_hop = true on a numbered neighbor, or on a peer group used by [[dynamic_neighbors]] | Capability 77 needs the interface scope that only an interface-bound IPv6 link-local session has. |
role requires eBGP | [[neighbors]] role = "..." on an iBGP session (remote_asn == global.asn) | RFC 9234 §4 scopes Roles to eBGP. |
tcp_ao mandatory fields | Missing key, send_id, recv_id, or algorithm | TCP-AO MKT is incomplete. |
bfd.profile references unknown profile | The [[bfd_profiles]] entry referenced by [[neighbors]] bfd.profile doesn't exist | |
| iBGP-only fields on eBGP (or vice versa) | route_reflector_client = true on eBGP, etc. | |
| Cross-section reference integrity | peer_group references a missing [peer_groups.<name>] entry, import_policy_chain names a policy that no [policy.definitions.<name>] or loaded .rpol file defines, etc. | |
TOML schema (#[serde(deny_unknown_fields)]) | Any misspelled or extraneous field | Catches typos before the daemon sees them. |
Validation-only constraints
These are checked at parse time but don't drive any runtime behavior of their own — they exist to keep the schema honest.
| Constraint | What it enforces |
|---|---|
| Cross-section reservation | E.g. static [[neighbors]] cannot set remote_asn = 0; that sentinel is reserved for [[dynamic_neighbors]] accept-any matching. Flagged at parse, no runtime effect of its own. |
| Address-family well-formedness | families = ["ipv4_unicast"] accepted; misspellings rejected at parse, used at session-establishment. |
How to verify a reload before applying
# Parse + validate, do not apply
rustbgpd --check /etc/rustbgpd/config.toml
# Compare the candidate file against the current on-disk config; print
# expected reload class per change (for a live-daemon comparison use
# `rbgp config diff`)
rustbgpd --diff /tmp/new-config.toml /etc/rustbgpd/config.toml
# Apply via SIGHUP and wait for the outcome (exit status 0 only for complete)
rbgp reload
# …or signal without waiting, then read the receipt
systemctl reload rustbgpd # or: kill -HUP $(pidof rustbgpd)
rbgp config last-reload
# After the reload: compare the installed file against the running config.
# Restart-required edits stay listed here until the next restart.
rbgp config diff /etc/rustbgpd/config.tomlThe two diff commands use different exit codes. rustbgpd --diff exits 0
for no actionable changes, 1 for actionable changes and 2 for a load error.
rbgp config diff exits 0 for no changes, 2 for changes and 1 for an error.
A SIGHUP that arrives while a reload is running is coalesced into one follow-up reload that re-reads the file after the running reload settles; see Configuration reload.
rustbgpd --diff calls into the same ConfigDiff machinery and route
classifier the reload path uses. Previews evaluate configuration and bindings,
not dataset file contents: when datasets are declared, rustbgpd --diff and
rbgp config diff report datasets: contents not compared (N declared); a reload re-reads them
rather than claiming No changes. SIGHUP re-reads the staged dataset files and
evaluates loader errors when it executes the generation route. rbgp config diff
resolves relative .rpol and dataset paths from the candidate file's directory
before sending the configuration to the daemon. Below operator_only, a
candidate sent over the API (diff, plan, or EVPN apply) may name only .rpol
files, rpol_roots and dataset files that resolve under the running config's
policy directories: its [policy] rpol_roots and the directories of its
.rpol and dataset files. The daemon resolves those directories when it
accepts the config at boot or on SIGHUP and holds them until the next accepted
reload, so a directory or symlink replaced in between does not move them; a
config committed over the API keeps the directories already resolved. An
rpol_roots entry that is a regular file admits only that file, as a path the
candidate names; the directory around it is not a policy directory. Unless
another policy directory covers that directory, this has two consequences below
operator_only. Another module cannot import that file. And import lines
written in it are looked up only under the candidate's policy directories,
never relative to the file's own directory: with
/etc/x/main.rpol and /etc/x/lib both listed in rpol_roots,
import "lib/common.rpol" in main.rpol is refused, while
import "common.rpol" resolves. Listing /etc/x in rpol_roots admits both.
The candidate's gRPC TLS and token file paths must be ones the running config
already uses. The file each of those paths resolved to when the config was
accepted is not admitted as a policy source until the next accepted reload,
across API commits, and neither is the file the path resolves to when a
candidate is loaded; a credential symlink rotated in between therefore keeps
both its old and its new target out. The check follows the configured path, so
a credential file moved aside by rename is not covered under its new name.
Operator callers may stage candidate sources
elsewhere, including on ApplyEvpnRuntime. For every API caller, compile and
dataset errors for those files report path, line and column without quoting file text; rbgp policy check
on the host shows the full diagnostic.
Related
docs/reference/configuration.md— field-by-field config reference.docs/reference/operations.md— operator runbook (startup, SIGHUP, upgrade).docs/adr/0061-opt-in-unicast-linux-fib-integration.md— FIB-discard reconciler scope.docs/adr/0067-bfd-single-hop.md— original BFD actor and coupling design; current reload behavior is specified above.docs/adr/0071-bgp-roles-otc.md— RFC 9234 roles + OTC reload semantics.docs/adr/0134-reload-monitoring-and-validation-endpoints.md— Proposed reload-applied reconciliation for BMP collectors, RPKI RTR caches, and MRT dumps (not shipped).