Reload Matrix

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, pin_unreconciled_daemon_runtime_fields, and the per-section error/warn arms) together with the pinning helpers 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

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 rustbgpd --diff prints its answer as SIGHUP reload route:

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.

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, max_prefixes, max_prefixes_ipv4, max_prefixes_ipv6, max_prefixes_received_ipv4, max_prefixes_received_ipv6, max_prefix_action, max_prefix_warning_percent, max_prefixes_out_ipv4, max_prefixes_out_ipv6, max_prefix_restart_seconds, gr_peer_restart_time_max, gr_stale_routes_time, local_ipv6_nexthop, remove_private_as, log_level, and the import/export policy and chain fields) 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, 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.

[peer_groups.<name>]

Peer-group fields mirror [[neighbors]] minus the identity triple (address, interface, remote_asn) and TCP-AO. 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.

[[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.

[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.

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]

[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.

[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.

[rpki], [bmp], [mrt]

ADR-0134 proposes reload-applying these sections for subsystems already enabled at startup; until an implementation ships they remain restart-required.

[gnmi_dialout]

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 is fail-stop: generations committed by earlier steps stay committed (no cross-step rollback), the model pins, and a re-SIGHUP after fixing the config converges only the remainder. 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.

[[fib_tables]] and FIB runtime

[[bfd_profiles]]

[security.grpc.*]

[event_history] (ADR-0072)

The durable event-history outbox is configured once at startup and its lifecycle (open / quarantine / diagnostic sidecar) is fixed for the process. Hot-reload of the outbox config is a P1 nice-to-have; v1 pins every field as restart-required and surfaces the change as an ERROR-level log line during reload so operators see exactly what's deferred.

[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.

[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.

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-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.

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
systemctl reload rustbgpd
# …or
kill -HUP $(pidof rustbgpd)

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.

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).