upgrade and restart

Pre-Alpha. This page describes behavior that may change.

The point of this page is one thing: how to replace the binary, reload the config, or restart the daemon without dropping your BGP sessions or black-holing traffic. There are three pieces and you should know which one is doing what when something goes wrong.

The three pieces are Graceful Restart (RFC 4724) on the wire, Long-Lived Graceful Restart (RFC 9494) for extended outages, and the bgp-persist plugin that puts the RIB on disk so it survives a process restart.

Reload without restart

Most config changes do not need a restart at all. The hot-reload path applies a new tree in place: peers are added or removed, capabilities are renegotiated when they have to be, and the rest of the subtree is patched without touching the running sessions.

ze signal reload                 # Re-parse the on-disk config and apply

signal reload goes through SSH. There is also a Unix signal path: kill -HUP <pid> does the same thing. Use the SSH path from scripts because it returns a non-zero exit code on failure.

If a commit forces a session reset (you changed a capability the peer cannot renegotiate, you changed the peer's local IP, you tightened authentication), Ze tells you what is going to bounce before it bounces it. You can dry-run with ze config diff against the running tree.

Graceful Restart

Graceful Restart preserves forwarding state across a session restart. When the session goes down, both sides keep using the routes they already have for a configurable window. When the session comes back, the new routes replace the stale ones, End-of-RIB is exchanged, and any leftover stale routes are purged.

GR is configured under each peer's capability block.

peer upstream {
    connection { remote { ip 10.0.0.1; } }
    session {
        asn { remote 65001; }
        capability {
            graceful-restart {
                restart-time 120;        # seconds, 0 to 4095
            }
        }
    }
    process gr  { receive [ state eor ]; }
    process rib { receive [ state ]; send [ update ]; }
}

The bgp-gr plugin and the bgp-rib plugin must both be loaded; bgp-gr declares the dependency, so the engine starts bgp-rib first. If the GR plugin crashes mid-restart, the RIB has its own safety net: stale routes are expired automatically restart-time + 5 seconds after the session went down.

Long-Lived Graceful Restart

LLGR (RFC 9494) is the second timer for extended outages. When the GR window expires without the peer reconnecting, instead of dropping every stale route, LLGR keeps them attached with the LLGR_STALE community and a deprioritised position in best-path selection. They lose to any non-stale route, but they keep traffic flowing while the peer is gone.

capability {
    graceful-restart {
        restart-time 120;
        long-lived-stale-time 3600;     # LLGR period in seconds
    }
}

LLGR only activates when both peers negotiate it. Routes carrying NO_LLGR (0xFFFF0007) are deleted on entry. Routes that survive get LLGR_STALE (0xFFFF0006) attached. If you want to skip standard GR entirely and go straight to LLGR, set restart-time 0 and a non-zero long-lived-stale-time.

Persisting the RIB across a binary upgrade

The bgp-persist plugin writes the RIB to disk so it can be reloaded on the next start. Combined with GR, this is what lets you replace the binary without dropping forwarding state. The shape of the workflow is the same as a normal restart: stop the daemon with the GR marker, replace the binary, start it again, and the RIB comes back with the persisted state while the peers reconnect.

ze signal restart                # Stop with GR marker (writes the marker file)
# replace /usr/local/bin/ze
ze start                         # Reload state, peers reconnect, GR completes

ze signal stop is the no-marker variant: it tears down with NOTIFICATION Cease and does not arm the GR side. Use it when you want a clean shutdown rather than a restart.

A practical upgrade

If you are doing a real upgrade in front of customers, the order is this.

1. Confirm GR is negotiated on the peers you care about (ze show peer <name> capabilities).
2. ze signal restart to stop with the GR marker armed.
3. Replace the binary.
4. ze start, watching ze cli monitor bgp from a second window for sessions to come back.
5. Confirm prefix counts have returned to baseline before walking away.

See also

• Configuration overview for hot reload and the commit workflow.
• Plugins for bgp-gr, bgp-rib, and bgp-persist.
• Monitoring to watch the restart in real time.

Adapted from main/docs/guide/operations.md and main/docs/guide/graceful-restart.md.