rustbgpd

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

ClassMeaning
liveChange 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-appliedChange 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-requiredChange 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-gatedEVPN 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:

RouteCandidateGuarantee
generationStatic 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_securityOne 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
sequentialNo 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 unchangedThe existing per-subsystem steps; a failure halts with an authoritative known-partial receipt or recovery-fences if state is ambiguous
rejectedDataset 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_blackholeNo 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 = true adds the peer disabled. It makes no connection attempts, refuses inbound connections, reads 0 in bgp_peer_admin_enabled, and stays listed in rbgp neighbor.
  • On reload, only a change to the resolved admin_down acts. Setting it disables the peer: an Established session receives Cease/Administrative Shutdown with admin_down_reason as 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 enable of a config-down peer therefore lasts until the next daemon restart or a reload that changes admin_down; a runtime disable of a config-up peer lasts the same way.
FieldClassNotes
addressrestart-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.
interfacerestart-required (identity)Part of the diff key. Same as address. Used by IPv6 link-local + BGP unnumbered peering.
remote_asnlive (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.
descriptionliveMetadata only; hot-applied in place — session task untouched.
admin_downliveHot-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_reasonliveRFC 9003 shutdown communication, at most 128 bytes. A change is recorded in place and sent with the next admin_down shutdown.
peer_grouplive (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_timelive (effective next session)Negotiated in OPEN. On SIGHUP the reconciler rebuilds the session immediately, so the new value is negotiated right away.
min_hold_timelive (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_timelive (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_pctlive (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_durationlive (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_isolationlive (session reset)Move a flagged-slow peer to the per-peer update path. Same capture and session-rebuild semantics as the threshold.
fast_external_failoverliveFast 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_prefixesliveThreshold re-evaluated on every received UPDATE.
max_prefixes_ipv4_unicastlivePer-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_unicastliveIPv6-unicast sibling of max_prefixes_ipv4_unicast (ADR-0108).
max_prefixes_received_ipv4_unicastlivePre-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_unicastliveIPv6-unicast sibling of max_prefixes_received_ipv4_unicast.
max_prefixes_l3vpn_ipv4_unicastlivePer-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_unicastliveSame as max_prefixes_l3vpn_ipv4_unicast, for its own family.
max_prefixes_ipv4_labeled_unicastliveSame as max_prefixes_l3vpn_ipv4_unicast, for its own family.
max_prefixes_ipv6_labeled_unicastliveSame as max_prefixes_l3vpn_ipv4_unicast, for its own family.
max_prefixes_l2vpn_evpnliveSame as max_prefixes_l3vpn_ipv4_unicast, for its own family.
max_prefixes_ipv4_flowspecliveSame as max_prefixes_l3vpn_ipv4_unicast, for its own family.
max_prefixes_ipv6_flowspecliveSame as max_prefixes_l3vpn_ipv4_unicast, for its own family.
max_prefixes_rtcliveSame as max_prefixes_l3vpn_ipv4_unicast, for its own family.
max_prefix_actionliveHot-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_percentliveHot-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_unicastliveRIB-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_unicastliveIPv6-unicast sibling of max_prefixes_out_ipv4_unicast.
max_prefix_restart_secondsliveManager-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_passwordlive (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_aolive (ordered rotation generations) / otherwise restart-requiredSIGHUP 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.
bfdreload-appliedSIGHUP 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_mssrestart-requiredTCP_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_securitylive (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_hopslive (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.
familieslive (effective next session)Address families to negotiate in OPEN. On SIGHUP the reconciler rebuilds the session immediately to negotiate the new set.
required_familieslive (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_restartlive (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_timelive (effective next session)Advertised in GR capability. On SIGHUP the reconciler rebuilds the session immediately to advertise the new value.
gr_peer_restart_time_maxliveLocal-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_timeliveUsed 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_timelivePlanned-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_timelive (effective next session)RFC 9494 LLGR capability stale time. On SIGHUP the reconciler rebuilds the session immediately to advertise the new value.
local_ipv6_nexthopliveUsed 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_clientlive (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_vantagelive (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_clientlive (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_communitieslive (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_bestlive (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_ownershiplive (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_rfc1997live (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_communitieslive (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.
rolelive (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_rolelive (effective next session)Strict-mode toggle. On SIGHUP the reconciler rebuilds the session immediately and applies the new requirement to OPEN negotiation.
prefix_orf_receivelive (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_unicastlive (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_hoplive (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_asliveApplied 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_attributeslive (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_pathlive (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_levellivePer-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_policyliveInline 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_policyliveInline export statements; re-evaluated against the Adj-RIB-Out on next distribution.
import_policy_chainliveNamed-chain reference; same re-evaluation behavior, including the Route Refresh and policy-presence qualifications above.
export_policy_chainliveNamed-chain reference; same re-evaluation behavior.
conditional_advertisementslive (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_dampeninglive (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:

ChangeEffect
Neighbor addedDiscovery 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 deletedIts 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 groupA 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 grouprestart-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_address and 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_level values are also refused when the sharing set includes a static neighbor. Interface-only neighbors sharing an address may differ in GTSM and log_level because 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.

FieldClassNotes
admin_downliveSame as neighbor for inheriting static members. Rejected on a group referenced by [[dynamic_neighbors]].
admin_down_reasonliveSame as neighbor.
hold_timelive (effective next session)Same as neighbor.
min_hold_timelive (effective next session)Same as neighbor; static members are rebuilt, while accepted dynamic members follow the group caveat above.
send_hold_timelive (effective next session)Same as neighbor.
slow_peer_threshold_pctlive (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_durationlive (session reset)Same as neighbor; same conservative-reshape fallback as the threshold.
slow_peer_isolationlive (session reset)Same as neighbor; same conservative-reshape fallback as the threshold.
fast_external_failoverliveSame as neighbor. Config-file-only, so the sequential route rejects a change to it alongside a TCP-AO or listener edit (see above).
max_prefixesliveSame as neighbor.
max_prefixes_ipv4_unicastliveSame as neighbor; per-family ADR-0108 cap inherited by group members.
max_prefixes_ipv6_unicastliveSame as neighbor.
max_prefixes_received_ipv4_unicastliveSame as neighbor; pre-policy received cap inherited by group members.
max_prefixes_received_ipv6_unicastliveSame as neighbor.
max_prefixes_l3vpn_ipv4_unicastliveSame as neighbor; inherited by group members.
max_prefixes_l3vpn_ipv6_unicastliveSame as neighbor; inherited by group members.
max_prefixes_ipv4_labeled_unicastliveSame as neighbor; inherited by group members.
max_prefixes_ipv6_labeled_unicastliveSame as neighbor; inherited by group members.
max_prefixes_l2vpn_evpnliveSame as neighbor; inherited by group members.
max_prefixes_ipv4_flowspecliveSame as neighbor; inherited by group members.
max_prefixes_ipv6_flowspecliveSame as neighbor; inherited by group members.
max_prefixes_rtcliveSame as neighbor; inherited by group members.
max_prefix_actionliveSame as neighbor; inherited by group members.
max_prefix_warning_percentliveSame as neighbor; inherited by group members.
max_prefixes_out_ipv4_unicastliveSame 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_unicastliveIPv6-unicast sibling of max_prefixes_out_ipv4_unicast.
max_prefix_restart_secondsliveInherited 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_passwordlive (effective next session)Same as neighbor — pinned by group, applied to the inheriting peer's next socket.
bfdreload-appliedSIGHUP 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_mssrestart-requiredInherited 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_securitylive (effective next session)
ttl_security_hopslive (effective next session)Same as neighbor; changes to a dynamic range's listener selector require SIGHUP.
familieslive (effective next session)
required_familieslive (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_restartlive (effective next session)
gr_restart_timelive (effective next session)
gr_peer_restart_time_maxliveInherited 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_timelive
gr_eor_grace_timeliveInherited 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_timelive (effective next session)
local_ipv6_nexthoplive
route_reflector_clientlive (effective next session)Same as neighbor; a toggle session-resets the inheriting static members.
orr_vantagelive (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_clientlive (effective next session)
send_non_transitive_extended_communitieslive (effective next session)Inherited plain-eBGP export opt-in; same session-rebuild semantics as the neighbor field.
per_client_bestlive (effective next session)Inherited per-client best-path mode; same semantics as the neighbor field.
next_hop_ownershiplive (effective next session)Inherited ADR-0107 ownership enforcement; same semantics as the neighbor field.
interpret_rfc1997live (effective next session)Same as neighbor.
rs_control_communitieslive (effective next session)Same as neighbor.
rolelive (effective next session)
strict_rolelive (effective next session)
prefix_orf_receivelive (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_unicastlive (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_hoplive (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_aslive
discard_path_attributeslive (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_pathlive (effective next session)
log_levelliveSame as neighbor — inherited per-peer tracing level, replaced on SIGHUP; it reaches the group's running sessions.
import_policyliveInline import statements inherited by peers that do not set their own import policy / chain.
export_policyliveInline export statements inherited by peers that do not set their own export policy / chain.
import_policy_chainliveNamed-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_chainliveNamed-chain reference inherited by peers that do not set their own export policy / chain.
conditional_advertisementslive (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_dampeninglive (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.

FieldClassNotes
prefixreload-appliedConsulted on every inbound TCP accept.
peer_groupreload-appliedInheritance resolves when a passive session promotes to a managed peer.
remote_asnreload-appliedValidated against the OPEN's my_as at promotion.
descriptionreload-appliedMetadata.
bfdreload-appliedAdding 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_aolive (ordered rotation generations) / otherwise restart-requiredAppend-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).

FieldClassNotes
root config_epochrestart-requiredADR-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.
asnrestart-requiredIdentity.
router_idrestart-requiredIdentity. Advertised in every OPEN.
listen_portrestart-requiredThe listen socket is created at startup.
listen_addressesrestart-requiredExact 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_idrestart-requiredRFC 4456 cluster identity; affects every iBGP advertisement.
honor_graceful_shutdownliveHot-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_blackholelive (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_policyrestart-requiredADR-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_discardrestart-requiredThe RFC 7999 kernel-discard reconciler spawns once at startup.
allow_blackhole_broad_prefixesrestart-requiredSame — feeds the discard-spawn gate.
blackhole_discard_max_activerestart-requiredThe reconciler captures the active-discard cap at startup; SIGHUP pins the running value.
blackhole_discard_install_rate_per_minuterestart-requiredThe reconciler captures the install-attempt rate at startup; SIGHUP pins the running value.
blackhole_discard_install_burstrestart-requiredThe reconciler captures the install-attempt burst at startup; SIGHUP pins the running value.
multipath_relaxrestart-requiredRIB best-path tie-break behavior; reconciling mid-flight would require an Adj-RIB-Out rebuild.
link_bandwidth_weightedrestart-requiredWeighted-multipath behavior (ADR-0068).
fast_external_failoverrestart-requiredDaemon-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_lengthrestart-requiredThreaded into each session's transport config when the peer is built; running sessions keep the ceiling they started with.
dynamic_neighbor_limitreload-appliedAdmission 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_threadsrestart-requiredTokio 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_ownersrestart-requiredThe 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_shutdownrestart-requiredThe shutdown checkpoint writer and its pinned runtime-state directory are selected at startup.
runtime_state_dirrestart-requiredFile-system paths (gr-restart.toml, fib-owned.json, grpc.sock) are bound at startup.
[global.unnumbered] (router_advertisements, ra_interval_secs)restart-requiredThe 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-In was 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, .rpol content, 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]

FieldClassNotes
prometheus_addrrestart-requiredThe exporter listener binds at startup.
dataplane_readinessrestart-requiredThe alpha /dp-readyz probe and its worker inventory are selected at startup.
log_formatrestart-requiredThe 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.

FieldClassNotes
addressrestart-requiredListener address.
enabled, max_tier, principalrestart-requiredThe whole listener config is pinned to the live listener on reload.
tls_expiry_warning_seconds (grpc_tcp)restart-requiredPinned with the rest of the listener config.
tls_client_crl_file path (grpc_tcp)restart-requiredAdding, 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 pathsreload-appliedStaged for all listeners and published as one atomic generation after the runtime reload is acknowledged; existing connections/streams survive.
token/TLS paths or auth moderestart-requiredListener shape and configured paths remain pinned.
path (grpc_uds)restart-requiredUDS path bound at startup.
mode (grpc_uds)restart-requiredPermissions 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.

FieldClassNotes
definitions (named)liveAdd/remove/edit named policy definitions; re-evaluated on the next distribution pass.
neighbor_sets (named)liveAdd/remove/edit named neighbor sets; the resolved set drives per-peer chain bindings.
import_chain (named)liveReorder, 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)liveReorder, 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_filesliveSIGHUP 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_rootsliveExtra 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_bytesliveRead 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_testsliveRead 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]liveSIGHUP 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] enabledrestart-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] capacityrestart-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]

SectionClassNotes
[rpki]restart-requiredRPKI VRP tables + cache connections stand up once at startup.
[bmp]restart-requiredBMP exporter binds once.
[mrt]restart-requiredThe 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]

SectionClassNotes
[gnmi_dialout] (whole section)reload-appliedSIGHUP 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.

SectionClassNotes
[[evpn_instances]]coordinator-gatedSupported 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_detectioncoordinator-gatedUses 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-gatedSupported 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-gatedSupported 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-gatedADR-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-requiredADR-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

SectionClassNotes
[[fib_tables]]reload-appliedHot-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-requiredSee [global] above.

[[bfd_profiles]]

SectionClassNotes
[[bfd_profiles]]restart-requiredpin_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.*]

FieldClassNotes
[security.grpc] enforcementrestart-requiredtier 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-requiredPrincipal → 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.

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

FieldClassNotes
enabledrestart-requiredOff (default) ⇒ accept behavior unchanged; the limiter is never built.
rate_per_minuterestart-requiredToken-bucket refill rate per source aggregate.
burstrestart-requiredToken-bucket depth per source aggregate.
v4_aggregation_lenrestart-requiredIPv4 bucket-key prefix length (8–32).
v6_aggregation_lenrestart-requiredIPv6 bucket-key prefix length (16–128); default /64 because per-/128 accounting is trivially evadable.
table_capacityrestart-requiredFixed 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 ruleTriggerNotes
route_flap_dampening effective enablementEligible static or dynamic eBGP neighbor resolves trueRuntime 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 invalidValidated even while disabled; suppress must not exceed the computed ceiling.
strict_role requires role[[neighbors]] strict_role = true without roleRFC 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 onlyThe combination is contradictory: the session could never negotiate any family.
link_local_next_hop requires an interface-bound link-local neighborEffective 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 fieldsMissing key, send_id, recv_id, or algorithmTCP-AO MKT is incomplete.
bfd.profile references unknown profileThe [[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 integritypeer_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 fieldCatches 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.

ConstraintWhat it enforces
Cross-section reservationE.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-formednessfamilies = ["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.toml

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

Source on GitHub

On this page