BFD: Bidirectional Forwarding Detection
BFD monitors connectivity between two systems so routing protocols can react to a forwarding failure before their own hold timers expire. Ze runs BFD as a plugin whose session service is used by BGP, OSPF, and static-route monitors.
The transport uses GTSM, outbound IP_TTL=255, SO_BINDTODEVICE for single-hop
and multi-VRF sockets, and RFC 5880 §6.8.7 transmit jitter. You can inspect
sessions with show bfd sessions and show bfd session address <peer>, view
profiles with show bfd profile, and monitor Prometheus ze_bfd_* metrics.
Adding bfd { ... } inside a
bgp peer connection block opens a per-peer BFD session on
Established and tears the BGP session down with RFC 9384 Cease
subcode 10 ("BFD Down") when BFD reports the forwarding path lost.
Adding strict true to that block runs
draft-ietf-idr-bgp-bfd-strict-mode instead: capability 74 is
negotiated, the BFD session opens before the BGP FSM starts, and the
BGP session is held out of Established until BFD is Up.
When to use it
| Scenario | BFD value |
|---|---|
| eBGP transit session | Sub-second failure detection without waiting for BGP hold time (default 90 s) |
| iBGP over a loopback | Multi-hop BFD can accelerate route reconvergence if the IGP alone is too slow |
| Static route to a gateway | Withdraw the route when the gateway stops forwarding, even if the physical link is up |
| OSPF adjacency | Detect a forwarding failure before the OSPF dead timer expires |
Do not use BFD between two routers where the IGP already runs fast BFD; the redundant sessions double the packet rate and can amplify instability.
Basic configuration
Profiles
Profiles are named bundles of timer and feature parameters. Sessions reference a profile by name and inherit every leaf from it. Profiles are optional: sessions can carry their parameters inline.
bfd {
profile fast-link {
desired-min-tx-us 50000; # 50 ms
required-min-rx-us 50000; # 50 ms
detect-multiplier 3; # 150 ms detection time
}
profile lan-default {
desired-min-tx-us 300000; # 300 ms
required-min-rx-us 300000;
detect-multiplier 3;
}
profile ibgp-loopback {
desired-min-tx-us 300000;
required-min-rx-us 300000;
detect-multiplier 5;
}
}
All interval fields are in microseconds because RFC 5880 expresses
every interval in microseconds. A future release may add -ms aliases.
| Leaf | Range | Default | Meaning |
|---|---|---|---|
desired-min-tx-us |
1 – 4 294 967 295 | 300 000 | Local target transmit rate. RFC §6.8.3 enforces a 1 000 000 µs floor while the session is not Up. |
required-min-rx-us |
0 – 4 294 967 295 | 300 000 | Minimum inter-packet gap the local end can handle. Zero means "do not send me periodic control packets." |
detect-multiplier |
1 – 255 | 3 | Number of consecutive missed packets that trigger a Down transition. |
passive |
boolean | false | Active sessions transmit from creation. Passive waits for the peer's first packet. See RFC 5883 §4.3 for the unidirectional-link use case. A single-hop session that uses a passive profile is refused: a configured session at load, and a BGP peer or static next-hop that names the profile at commit. RFC 5881 §3 requires both ends of a single-hop session to be Active. |
auth { type key-id secret | secret-hex } |
see below | none | RFC 5880 §6.7 cryptographic authentication (Stage 5). |
echo { desired-min-echo-tx-us } |
see below | none | RFC 5880 §6.4 Echo mode (single-hop only). |
Echo mode
Profiles may carry an echo { desired-min-echo-tx-us N } block
that opts sessions into RFC 5880 §6.4 Echo mode. The block is
valid only on single-hop sessions -- RFC 5883 §3 prohibits
multi-hop echo. A configured multi-hop session that uses an echo
profile is refused at load, and a multi-hop BGP peer that names one
is refused at commit, each with a descriptive error.
bfd {
profile fast-echo {
desired-min-tx-us 100000;
required-min-rx-us 100000;
echo {
desired-min-echo-tx-us 50000; # 50 ms
}
}
single-hop-session 203.0.113.9 {
profile fast-echo;
}
}
When a session inherits this profile, every outgoing Control
packet sets RequiredMinEchoRxInterval to the configured rate.
Peers that see a non-zero advertisement learn that the local end
is willing to reflect echo packets.
Current coverage: echo mode is fully implemented including the
YANG surface, wire advertisement, per-session TX scheduler, RX
demux with RTT measurement, echo detection timer, and async
slow-down (RFC 5880 §6.8.9). The ze_bfd_echo_tx_packets_total
and ze_bfd_echo_rx_packets_total Prometheus metrics are live.
Authentication
A profile can carry an auth { ... } block that enables RFC 5880 §6.7
authentication for every session that inherits the profile. Ze supports
the five types RFC 5880 defines: simple-password, keyed-md5,
meticulous-keyed-md5, keyed-sha1, and meticulous-keyed-sha1. There
is no default, so authentication runs only on the type you name.
simple-password (RFC 5880 §6.7.2) puts the password in clear in every
Control packet, and the authentication section is the same in each one.
It detects a misconfigured neighbor. It does not stop a listener on the
path, who reads the password from one packet, and it carries no Sequence
Number, so a captured packet can be replayed. Use a keyed type wherever
the path is not already trusted. The password must be 1 to 16 bytes: the
Auth Len field holds the password length plus three, so a longer password
has no wire encoding and the parser refuses it.
A keyed secret is at most 16 bytes for keyed-md5 and
meticulous-keyed-md5 (RFC 5880 §6.7.3) and at most 20 bytes for
keyed-sha1 and meticulous-keyed-sha1 (§6.7.4), the size of the slot the
key is padded into. The parser refuses a longer secret rather than
truncating it. A received Sequence Number must lie within 3 × Detect Mult
ahead of the last one accepted, and strictly ahead of it for the meticulous
types; a packet outside that window is discarded as a replay. The first
packet of a session sets that floor from its Sequence Number before its
digest is checked, in the order RFC 5880 §6.7.3 gives, so a first packet that
fails authentication is discarded and has still set the floor. Ze does not
yet clear the floor after two Detection Times without a packet (RFC 5880
§6.8.1), so such a floor stays until the session is recreated.
bfd {
persist-dir "/var/lib/ze/bfd";
profile authenticated-fast {
desired-min-tx-us 50000;
required-min-rx-us 50000;
detect-multiplier 3;
auth {
type meticulous-keyed-sha1;
key-id 7;
secret "BFD-SHARED-SECRET-V1";
}
}
}
The secret takes one of two forms, and a profile names exactly one. secret
is an ASCII string whose bytes are the key. secret-hex is any binary string
written in hexadecimal, two digits for each byte with no 0x prefix, so a key
holding a zero byte or a byte above 0x7F can be configured (RFC 5880 §6.7.2,
§6.7.3 and §6.7.4). The limits above apply to the decoded bytes, so a 20-byte
keyed-sha1 key is 40 hex digits. ze config validate refuses an odd digit
count, a character that is not a hex digit, and a profile that names both forms
or neither. Both forms are redacted from ze config show output.
auth {
type keyed-sha1;
key-id 7;
secret-hex "00ff4142434445464748494a4b4c4d4e4f5051ff";
}
The meticulous variants enforce strict monotonic sequence numbers;
non-meticulous variants allow a receiver to accept equal sequence
numbers across retransmits. A non-empty persist-dir leaf (top-level on
bfd { }) enables persistence of the last TX sequence under
meta/bfd/auth/<session> in the daemon's selected database/ tree. The leaf's
path is retained as an opt-in setting; it does not select a second directory.
A Meticulous session resumes above its saved sequence floor after a process
restart. Without persistence, it must re-synchronise with the peer's replay
window. Explicit-file startup selects the store beside that file without a
ze.config.dir pin.
Authentication failures increment ze_bfd_auth_failures_total{mode}.
Enabling BFD on a BGP peer
Adding a bfd { ... } container inside a BGP peer's
connection { ... } block opts that peer into BFD. On session
Established, the reactor calls the BFD plugin's api.Service.EnsureSession
with the peer's local / remote address and the configured mode; on
session teardown the handle is released. When BFD reports the
forwarding path Down, the reactor tears the BGP session with RFC 9384
Cease NOTIFICATION (subcode 10, "BFD Down") without waiting for the
hold timer.
A reload or a commit that adds, removes, disables or edits the opt-in of a
peer without strict true keeps the BGP session: an Established peer opens
its BFD session at once, a removed or disabled opt-in releases it, and an
edited one (another profile or mode) releases it and opens one under the new
request. The same holds for a dynamic group's template, on every running
dynamic peer of the group. A change with strict true before or after
restarts the BGP session, because strict mode is announced in the OPEN
(docs/guide/config-reload.md).
A released session does not leave show bfd sessions at once when it has
heard from its peer. It stays there in admin-down for three of its
Detection Times, because RFC 5880 Section 6.8.1 says its state "MUST be
preserved for at least one Detection Time" and Section 6.8.16 asks for
AdminDown Control packets for at least as long. A client that asks for
the same session inside that window revives it, discriminator included.
With strict true, the peer opens its BFD session before the BGP FSM starts
and keeps it across every retry, releasing it only when the peer itself stops
(draft-ietf-idr-bgp-bfd-strict-mode Section 7). "BFD strict mode" below
carries the whole difference.
BFD AdminDown does NOT tear the BGP session down, in either mode. RFC 5882 Section 4.2 says a client "SHOULD NOT take any control protocol action" on that transition, because Section 3.2 makes AdminDown say nothing about the data path.
Authenticate the BFD session of an EBGP peer. RFC 5882 Section 10.2 says
"BFD authentication SHOULD be used and is strongly encouraged" for a BFD
session that advises an EBGP session. The peer's bfd container carries no
key of its own: name a profile whose auth block configures the
authentication (see "Authentication" above), and the BFD plugin applies it to
the peer's session. The neighbor must be configured with the same type, key ID
and secret. A neighbor with a different secret, or one that sends no
authentication, never brings the session Up, so a strict-mode peer stays out
of Established. A peer that names no profile, or a profile with no auth
block, runs its BFD session unauthenticated, which the SHOULD permits. When an
EBGP peer enables BFD and names a profile with no auth block, the commit is
accepted and Ze logs one warning naming the peer and the profile. Its fix
field gives the auth { type ...; key-id ...; secret ...; } block to add under
that bfd profile, or the alternative of naming an authenticated profile in
the peer's connection { bfd { profile <name>; } }. When an EBGP peer enables
BFD and names no profile, the commit is accepted and Ze logs one warning naming
the peer, with no profile. Its fix field gives the profile with an auth
block to define and the connection { bfd { profile <name>; } } line that
names it. An IBGP peer, a profile with an
auth block, and a static next-hop's bfd-profile draw no warning, because
the recommendation covers the BFD session of an EBGP peer only.
bgp {
peer peer1 {
connection {
local {
ip 192.0.2.1
}
remote {
ip 192.0.2.2
}
bfd {
enabled true
mode single-hop
profile fast-link
}
}
session {
asn {
local 65001
remote 65002
}
router-id 192.0.2.1
family {
ipv4/unicast
}
}
}
}
With no bfd container, BGP behaves exactly as today. The container
has YANG presence: its mere existence opts in, and enabled false
suspends the opt-in without removing the config (useful during
maintenance). The profile name references a profile defined under the
top-level bfd { profile ... } block; the BFD plugin resolves it when
it receives EnsureSession, so the session runs at the profile's timers,
role and authentication. The running daemon checks the name against the
bfd block at startup, at a commit and at a SIGHUP reload alike: a
profile that is not defined, a passive profile on a single-hop peer,
and an echo profile on a multi-hop peer are each refused there, naming
the peer. An edit that touches only the bfd block is checked too, so
deleting a profile a peer still names is refused. At startup the check
stops the daemon, so a file whose peer names an undefined profile never
boots. ze config validate refuses a BGP peer or static next-hop
profile that is not defined, naming the profiles that exist, because both
leaves name the bfd-profile reference source; the editor completes the same
names. It does not run the passive and echo checks for a BGP peer: only the
daemon refuses those. A static next-hop's passive profile is checked by both.
A client that opts into BFD needs BFD running. A config in which a BGP
peer's connection bfd is enabled, a static next-hop names a
bfd-profile, or an OSPF interface sets bfd { enabled true; }, while
the config has no top-level bfd block, sets bfd { enabled false; },
or runs a build that carries no BFD, is refused: at commit, at reload,
and at startup, so the daemon does not boot with it. The refusal names
every client still opting in:
bfd: bfd { enabled false } is set, so no client may opt into BFD; remove the bfd opt-in of peer 192.0.2.1 first
BFD therefore cannot be removed or disabled from under a protected client. Remove the opt-ins first, in the same commit or an earlier one: a strict-mode peer then restarts, and a peer outside strict mode stays up. If a session is still refused at start for another reason, the peer logs the refusal and runs without BFD unless it is in strict mode, where it stays down.
Multi-hop
For iBGP between loopbacks or any peering that crosses more than one IP hop:
bgp {
peer loop4 {
connection {
local {
ip 10.255.255.1
}
remote {
ip 10.255.255.4
}
bfd {
enabled true
mode multi-hop
min-ttl 250
profile ibgp-loopback
}
}
session {
asn {
local 65000
remote 65000
}
router-id 10.255.255.1
family {
ipv4/unicast
}
}
}
}
mode multi-hop tells the plugin to use UDP port 4784 and skip GTSM.
min-ttl is a weaker replacement for GTSM. Packets arriving with a
TTL below the configured value are discarded. Choose min-ttl to be
256 - max-hops; for example, min-ttl 250 allows the packet to
cross up to 5 hops. min-ttl must be non-zero for multi-hop; the
parser rejects zero at config-validate time.
Strict mode
Plain BFD is a failure detector. It opens after the BGP session is up, so a peer whose control plane answers while its forwarding path is broken still establishes BGP and blackholes traffic until something else notices.
Strict mode closes that window. It is
draft-ietf-idr-bgp-bfd-strict-mode, and it holds the BGP session out of
Established until the BFD session to that neighbour is Up.
bgp {
router-id 192.0.2.254
session {
asn {
local 65000
}
}
peer peer1 {
connection {
local { ip 192.0.2.1 }
remote { ip 192.0.2.2 }
bfd {
enabled true
mode single-hop
profile fast-link
strict true
hold-time 30
}
}
}
}
strict true does three things.
| What | Detail |
|---|---|
| Advertises capability 74 | The BFD Strict-Mode Capability, code 74, length 0, in every OPEN. Draft Section 6 makes this a MUST for a speaker with strict mode enabled |
| Opens the BFD session early | Before the BGP FSM starts, and keeps it open while BGP is down. Draft Section 7 asks for both, so the BFD handshake is not serialized behind the BGP one |
| Withholds KEEPALIVE while BFD is pending | When both OPENs negotiate strict mode and BFD is neither Up nor AdminDown, Ze waits in OpenSent, or in Connect/Active if the OPEN arrived during DelayOpen. show bgp peer list and show bgp peer detail carry the corresponding bfd-sub-state while it waits |
A fourth leaf, hold-down, is optional and described below.
To combine this with delayed OPEN, add timer { delay-open 5; } inside the
same peer. An early remote OPEN still makes Ze send its OPEN, but not its
KEEPALIVE while BFD is pending. The displayed sub-state is
CONNECT-DELAYOPEN-BFD-UP-PENDING or ACTIVE-DELAYOPEN-BFD-UP-PENDING.
BFD Up, AdminDown or Disabled releases that wait to OpenConfirm. The bounds
below apply in those states too; DelayOpen does not introduce an unbounded
strict-mode wait. With delay-open 0, the existing OpenSent path is unchanged.
Both speakers must advertise it. Against a peer whose OPEN carries no capability 74, Ze establishes on the normal path and BFD stays a failure detector. That is deliberate: a one-sided strict mode is a session that never comes up.
hold-time bounds the wait, and only when the negotiated BGP hold time is
zero. A non-zero BGP hold time already bounds it, so the timer does not run.
On expiry Ze sends a NOTIFICATION with Cease and subcode 10 ("BFD Down"), and
the peer returns to Idle and retries. The default is 30 seconds, which is the
draft's own.
Nothing waits forever. Where the negotiated BGP hold time is non-zero, the ordinary RFC 4271 hold timer is what ends a wait for a BFD session that never comes up: Ze arms it at the negotiated value on the way into the wait, and its expiry sends NOTIFICATION code 4 (Hold Timer Expired) and returns the peer to Idle. That is why the draft arms its own BfdHoldTimer only for a negotiated hold time of zero.
hold-down damps a flapping link. It is how long the BFD session must stay Up
before Ze lets the BGP session establish, in milliseconds, and it is zero by
default: without it Ze establishes on the first BFD Up, which is what a peer
did before the leaf existed. A BFD session that goes down again inside the
interval never completes it, so a link that flaps carries no BGP session.
draft-ietf-idr-bgp-bfd-strict-mode Section 10 recommends the BFD hold-down and
BGP hold time "use similar values"; set the BGP hold time long enough to cover
the interval, or the far end times out waiting for you.
Two operational notes, both from the draft.
- Give the BGP hold time room (Section 10). It has to cover the time between OpenConfirm, the BFD hold-down interval, and the delay before the BFD session starts. Too short and the speaker that reached Established first times out waiting for the other to follow.
- Authenticate BFD (Section 12). A BGP session now depends on a BFD
session, so anything that can stop BFD coming Up can stop BGP. The
authblock above is the answer.
The BFD plugin must be loaded. A strict peer with no BFD plugin is held down rather than run without the check: establishing would deliver the opposite of what was configured. Ze logs an error naming the peer.
Standalone sessions
Some paths have no protocol client. For those, pin the session explicitly
in the top-level bfd block. It exists for the lifetime of the config.
bfd {
profile gateway {
desired-min-tx-us 200000;
required-min-rx-us 200000;
detect-multiplier 3;
}
single-hop-session 192.0.2.254 {
local 192.0.2.1;
interface eth0;
profile gateway;
}
multi-hop-session 198.51.100.7 {
local 10.0.0.1;
profile gateway;
min-ttl 254;
}
}
Standalone sessions are useful for monitoring a default gateway, a tunnel endpoint, or any path whose liveness a script or external tool wants to react to via the event stream.
local is the source address of every Control packet the session sends,
and it must be an address the host holds: on Linux a send from any other
address is refused and logged. Two sessions to the same peer from two local
addresses stay two sessions (RFC 5883 §4.1), and each sends from its own
address, so the peer can tell them apart. Off Linux the kernel chooses the
source address, and ze logs that once.
Administrative shutdown
shutdown; on a session puts it into AdminDown (RFC 5880 §6.8.16)
without removing the config. The peer sees AdminDown via the State field
and, per RFC 5882, clients with their own liveness signal keep running
while clients without one treat it as Down.
bfd {
single-hop-session 192.0.2.254 {
local 192.0.2.1;
interface eth0;
profile gateway;
shutdown;
}
}
Remove shutdown; (or set it to false in a tool-driven edit) to
re-enable the session; it transitions through Down and completes the
three-way handshake normally.
Session sharing
When multiple clients ask for the same path, the BFD plugin creates one underlying session and refcounts subscribers. The session runs with the timers of the request that created it: a later client joins it as it is, and its own timers do not change the session. For example, if BGP asks for a 50 ms session and OSPF later asks for a 300 ms session to the same peer, they share the 50 ms session.
One session carries one authentication configuration. A client whose profile resolves to a different authentication (another Auth Type, Key ID or secret, or authentication where the session has none, or none where it has some) is refused rather than joined: the session keeps the authentication it was built with, and the refused client logs the error, which names the peer, interface and VRF, says what differs, explains that one session per neighbor runs one authentication (RFC 5882 Section 4.4) so the client gets no BFD session, and gives the one fix for that case. A BGP peer then runs without BFD, a strict-mode BGP peer is held down, a static route's next-hop runs without BFD, a pinned session fails the apply of the commit that asked for it, and an OSPF neighbor runs on its hello and dead timers. Two profiles with the same auth block under different names share the session.
OSPF BFD runs unauthenticated: an OSPF interface's bfd block takes timers
only, with no profile and no auth block. OSPF can share a session with a BGP
peer, a static next-hop or a pinned session to the same neighbor only when
that session runs no authentication, so those clients' profiles carry no
auth block either; otherwise take OSPF out of BFD on that interface with
bfd { enabled false; } or by deleting its bfd block.
No fix the error names edits a profile. An edit to a profile reaches every client that names it, on any neighbor, at the commit: removing the auth block from a profile many BGP peers share, to fix one refused peer, would drop authentication for all of them. Each fix instead names a profile on the refused client, or copies an auth block into a profile only that client names, so it changes the refused client alone and takes effect when that client next asks for the session (see "Editing live"). The exception is a session whose profile was edited or removed after every client naming it had released the session, while clients of other profiles still hold it: it keeps running the authentication it was built with, and there only a release by every client helps:
| Live session | Refused client | Fix the error names |
|---|---|---|
| ✕ | Profile with an auth block | Name the profile the session was built from, or another profile with no auth block, on this client. When no client's profile built the session (an OSPF interface or a pinned session naming none), or that profile has since gained an auth block, been removed, or set an option the session's hop mode refuses, the error names only the second |
| Authentication | Profile with no auth block | Name the profile the session was built from on this client, or copy that profile's auth block into a profile only this client names |
| Authentication | ✕ | Name the profile the session was built from on this client, or, on an OSPF interface, set bfd { enabled false; } |
| Authentication | Profile with a different auth block | Name the profile the session was built from on this client, or copy that profile's auth block into a profile only this client names |
| Either | The profile the live session was built from, edited since | Release the session from every client (see "Editing live"), so the next client to ask builds it from the edited profile |
| Authentication | Any client, while the profile the session was built from has been edited or removed since, or now sets an option the session's hop mode refuses (passive on single-hop, echo on multi-hop) |
Release the session from every client (see "Editing live"). The error never names that profile then: copying it, or naming it, would give the client an authentication the session does not run, or a name the commit refuses |
The other way round, changing every other client to match the refused one, also works, but a live session keeps its authentication until every client has released it, so it needs the release in "Editing live" too.
Editing live
BFD configuration is reachable through the standard ze config edit CLI:
operator@router> configure
operator@router# edit bfd profile fast-link
operator@router# set desired-min-tx-us 100000
operator@router# show
profile fast-link {
desired-min-tx-us 100000;
required-min-rx-us 50000;
detect-multiplier 3;
}
operator@router# commit
On commit, the plugin receives the new bfd section and applies it.
A new pinned session starts, a removed one is released, and a change to a
pinned session's shutdown leaf takes effect at once. An edit to a profile
reaches at once, in place, every live session a client holds under it: a
pinned session, a BGP peer, or a static route next-hop. The session keeps
running, keeps its discriminator, and takes the edited timers (an Up session
through a Poll Sequence, so it stays Up). It takes an edited passive at once:
the role decides only whether the session may transmit before it has heard from
the neighbor, so a Down session that has not heard from it stops sending when
made passive and sends at once when made active, and an Up session keeps
sending either way. It takes an edited echo interval at once too: the next
Control packet advertises the new interval, a pending Echo packet moves to the
new cadence, an interval of zero stops Echo, and a nonzero one on a session
that ran none starts Echo as on a new session. It takes an edited auth block too,
when every client of the session asks for the same authentication after the
edit. When one does not, because it names another profile or none, the commit
is refused and none of its bfd changes is applied: the edited profile keeps
its previous auth block, every client keeps the session with its request, its
timers and its current authentication, and the error names the two clients by
profile. A client asking after the refusal gets the profile as it was before
the commit. Give both profiles the same auth block. When the other client
names no profile, restore the edited profile's auth block, or name the edited
profile on that client (an OSPF interface cannot name one: set
bfd { enabled false; } on it). Or release the other client first, as the
table below says, commit that, and then commit the edit again: with the other
client gone, the edit reaches the session. The release needs its own earlier
commit when the other client is a BGP peer, because a commit's BGP peer changes
are applied after its bfd changes.
A commit that deletes a profile together with the BGP peers and static routes naming it applies: a client still holding a session under the deleted profile keeps it as it runs until the client releases it in the same commit.
A session shared by several clients runs the fastest timers among them: those giving the shortest Detection Time (Detect Mult times Required Min RX). They are chosen again whenever a client joins or leaves, or the profile of any of its clients is edited, so a fast client speeds the session up and its departure slows it down again.
An OSPF interface names no profile: its timers are those of its own bfd
block, and an edit to them reaches the session when the interface next asks for
it. A released session that a client revives inside its Detection Time takes
that client's authentication as the profile holds it then, and its timers too.
To release the client that a refused edit names, or to make an edit to an OSPF
interface's bfd block or to a profile the session no longer follows take
effect, release the session from the clients that hold it, then let them ask
again:
| Client | Releases the session when | Asks again when |
|---|---|---|
Pinned single-hop-session or multi-hop-session |
It is removed from the config and committed | It is added back and committed. A refused pinned session asks again at each commit that changes the bfd section, and its refusal fails that commit's apply |
| BGP peer | Its session leaves Established, for instance after request peer <address> teardown 4 (Cease subcode 4, administrative reset) |
Its session next reaches Established, which a torn-down peer reaches again by itself |
| Strict-mode BGP peer | It is removed from the config, or deleted at runtime with delete bgp peer <address> (the only way for a peer made by create bgp peer) |
It is added back, at its first connection attempt. A refused strict-mode peer asks again at each connection attempt |
| Static route next-hop that names a profile | Its route is removed or changed | Its route is added back, or at once when it was changed |
| OSPF interface | bfd { enabled false; } is set on it, or its bfd block is deleted, and committed |
BFD is enabled again and committed (a neighbor already Full asks at once), or the neighbor next reaches Full. A refused interface also asks again at any commit that changes the ospf config |
Release the BGP peers last. A non-strict peer that is torn down reconnects by itself, and can join the old session again before the other clients have let go of it; if that happens, tear it down again once they have.
A client refused because its authentication differs from the live session's asks again at the same moments, so a fix to its own config takes effect then.
Observing state
The BFD commands show the engine's live session state and configured profiles. Their handlers return JSON payloads for scripts, which the interactive CLI can also render.
The terminal lab starts with an established FRR BGP peer and no BFD binding.
It loads the profile and peer opt-in through one live SSH candidate, then
checks Up, packet exchange and unchanged connection counts on both Ze and
FRR. FRR's counters also detect a reconnect hidden by recreating Ze's peer
object. Cutting frr0 exercises the detection-expired diagnostic and BGP's BFD notification
before its negotiated hold timer. The lab also checks released-session
retirement and restores the link without replacing the shown Ze process.
Let BFD protect a live BGP session
Commit BFD onto an established FRR BGP peer, cut the link, inspect diagnostics and peer history, then restore both sessions without restarting Ze.
Read the demonstration transcript
BFD live opt-in and link-failure walkthrough
Lab: one running Ze router and its established FRR BGP peer at 172.29.0.2.
$ ze-demo card topic-bfd overview
$ cat /src/tmp/terminal-demos/state/showcase-lab/ze.pid
$ ze cli -c 'show bfd sessions | no-more'
$ ip netns exec showcase-frr vtysh -c 'show bgp neighbor 172.29.0.1 json'
Load: profile fast and peer frr BFD binding, section by section in one SSH candidate.
$ sshpass -e ssh ze-demo
ze# load file absolute merge /src/demos/terminal/topics/bfd/1-profile.conf
ze# load file absolute merge /src/demos/terminal/topics/bfd/2-peer.conf
ze# show | compare
ze# commit now
Proof: show bfd sessions/profile/session and BGP detail expose Up, real packet counts and the negotiated hold timer.
$ ze-demo card topic-bfd proof
$ ze cli -c 'show bfd profile name fast | no-more'
$ ze cli -c 'show bfd session address 172.29.0.2 | no-more'
$ ze cli -c 'show bgp peer 172.29.0.2 detail | no-more'
$ ip netns exec showcase-frr vtysh -c 'show bgp neighbor 172.29.0.1 json'
Failure: bring frr0 down; inspect detection-expired transition, BFD Down notification and BGP history before hold expiry.
$ ze-demo card topic-bfd failure
$ ze-demo run showcase-lab control frr down
$ ze cli -c 'show bfd session address 172.29.0.2 | no-more'
$ ze cli -c 'show bgp peer 172.29.0.2 detail | no-more'
$ ze cli -c 'show bgp peer 172.29.0.2 history | no-more'
Fix: observe released-session retirement, restore frr0, require BFD Up and BGP Established, and print the same shown PID.
$ ze-demo card topic-bfd fix
$ ze cli -c 'show bfd sessions | no-more'
$ ze-demo run showcase-lab control frr up
$ ze cli -c 'show bfd session address 172.29.0.2 | no-more'
$ ze cli -c 'show bgp peer 172.29.0.2 detail | no-more'
$ cat /src/tmp/terminal-demos/state/showcase-lab/ze.pid
$ ze-demo card topic-bfd recap
List all sessions
operator@router> show bfd sessions
[
{"peer":"192.0.2.2","vrf":"default","mode":"single-hop","state":"up","diag":"no-diagnostic","local-discriminator":1,"remote-discriminator":2147518038,"tx-interval":50000000,"rx-interval":50000000,"detection-interval":150000000,"detect-multiplier":3,"profile":"fast-link","tx-packets":2312,"rx-packets":2310,"refcount":1,...},
{"peer":"198.51.100.7","vrf":"default","mode":"multi-hop","state":"down","diag":"control-detection-time-expired","tx-interval":200000000,"rx-interval":200000000,"detection-interval":600000000,"detect-multiplier":3,"profile":"gateway",...}
]
Fields are sorted stably by (mode, vrf, peer) so successive scrapes
produce diff-able output.
Session detail
show bfd session address <peer> returns the same struct for one session
plus the most recent state transitions kept in a bounded in-memory
ring (eight entries by default -- see api.TransitionHistoryDepth):
operator@router> show bfd session address 192.0.2.2
{
"peer": "192.0.2.2",
"local": "192.0.2.1",
"interface": "eth0",
"vrf": "default",
"mode": "single-hop",
"state": "up",
"diag": "no-diagnostic",
"profile": "fast-link",
"local-discriminator": 1,
"remote-discriminator": 2147518038,
"tx-interval": 50000000,
"rx-interval": 50000000,
"detection-interval": 150000000,
"detect-multiplier": 3,
"tx-packets": 2312,
"rx-packets": 2310,
"refcount": 1,
"transitions": [
{"when":"2026-04-11T09:14:22Z","from":"down","to":"init","diag":"no-diagnostic"},
{"when":"2026-04-11T09:14:23Z","from":"init","to":"up","diag":"no-diagnostic"}
]
}
List profiles
show bfd profile returns every resolved (post-default) profile
stored by the plugin. Passing a name filters to one entry; an unknown
name returns an error:
operator@router> show bfd profile fast-link
{"name":"fast-link","detect-multiplier":3,"desired-min-tx-us":50000,"required-min-rx-us":50000,"passive":false}
Prometheus metrics
The plugin registers five metric families via
internal/component/bfd/metrics.go. The families appear on the
telemetry endpoint when telemetry { prometheus { enabled true } }
is set.
| Metric | Type | Labels | Meaning |
|---|---|---|---|
ze_bfd_sessions |
gauge | state, mode, vrf | Live session count, updated on every show bfd sessions scrape |
ze_bfd_transitions_total |
counter | from, to, diag, mode | Every session state change |
ze_bfd_detection_expired_total |
counter | mode | Detection-timer expirations (RFC 5880 §6.8.4) |
ze_bfd_tx_packets_total |
counter | mode | Control packets transmitted |
ze_bfd_rx_packets_total |
counter | mode | Control packets received (after the TTL gate) |
Operational guidance
Picking timers
| Situation | TX / RX | Mult | Detection |
|---|---|---|---|
| LAN between routers | 50 ms / 50 ms | 3 | 150 ms |
| Metro eBGP | 100 ms / 100 ms | 3 | 300 ms |
| iBGP over IGP | 300 ms / 300 ms | 5 | 1.5 s |
| WAN over uncertain media | 500 ms / 500 ms | 5 | 2.5 s |
Err on the slow side. A session that runs too fast on a link with jitter produces false-positive failures that tear down routing state. BFD is worse than useless in that mode: it amplifies instability instead of damping it.
TTL security on single-hop
Single-hop BFD enforces GTSM (RFC 5082): packets are sent with TTL=255
(IP_TTL socket option applied at Start) and received packets with any
other TTL are silently discarded by the engine. There is nothing for the
operator to configure -- ze sets the TTL automatically and the engine's
TTL gate fails closed when the kernel cannot extract the received TTL
(for example, when running on a platform without IP_RECVTTL).
Multi-hop sessions have no GTSM equivalent; instead each multi-hop-session
carries a min-ttl leaf (default 254). Packets arriving with a TTL below
that floor are discarded before reaching the FSM. Pick min-ttl to be
256 - max-hops.
Multi-VRF and interface binding
A single-hop session to an IPv6 link-local peer (fe80::/10) must name its
link in interface, in the default VRF and in any other: the same address can
be in use on every link, and the interface is what says which one. One peer on
two links is two entries:
bfd {
single-hop-session fe80::b { interface eth0; }
single-hop-session fe80::b { interface eth1; }
}
Ze refuses a link-local entry with no interface, and refuses a peer or
local written with a zone (fe80::b%eth0): write the address without the
zone and the link in interface. A global IPv6 or an IPv4 peer needs no
interface.
Any IPv6 peer also needs bfd { bind-v6 true; }. The leaf defaults to false,
and then each session loop holds only an IPv4 socket. A protocol that asks for
a session to an IPv6 neighbour (OSPFv3, a BGP peer over IPv6) is then refused
with an error that names the leaf, rather than given a session that can never
send. An IPv4-mapped address (::ffff:192.0.2.1) travels on the IPv4 socket
and needs no IPv6 one.
Single-hop pinned sessions may specify an interface leaf. When every
pinned session in the same (vrf, single-hop) pair names the same
interface, the plugin binds the socket to that interface via
SO_BINDTODEVICE so egress and ingress are guaranteed to traverse the
named device. If a pinned set mixes interfaces in the same VRF, the
bind-to-device fallback is disabled (a warning is logged) and the
engine-side TTL gate remains the sole protection.
Non-default VRFs bind the socket to the VRF device name (Linux's
SO_BINDTODEVICE accepts VRF masters as device names). Both paths
require CAP_NET_RAW at daemon startup on Linux.
SO_BINDTODEVICE can only name one device per socket, so under a
non-default VRF the session interface leaf is ignored -- the socket
binds to the VRF master and receives packets from every slave device
in that VRF. Ze logs an Info line naming the dropped interface leaves
whenever this override fires so the operator can correlate a reload
with the behaviour change. If you need per-interface pinning in a
non-default VRF, stand up separate sessions per slave device outside
the shared VRF.
Only a PINNED session binds the socket to a device. A session a protocol
asks for at runtime, which is every BGP peer and every OSPF neighbor,
never does: one socket serves every session of a (VRF, mode) pair, so a
device chosen for the first request would decide where every later session
in that VRF transmits from. The binding is resolved across the whole pinned
set of one apply instead, and a loop that is already running cannot be
rebound, because a socket cannot. A reload that asks for a different device
therefore does not get one: Ze logs a Warn naming both devices and the
effect, and every session on that loop keeps transmitting from the device
the loop was created with. Restart Ze to rebind.
A session's own interface leaf keeps its two other jobs whatever the
socket is bound to: it is part of the session key, and the RFC 5881
Section 5 TTL gate is applied per session.
The socket also asks the kernel for IP_PKTINFO and IPV6_RECVPKTINFO.
Those are what tell Ze which of its own addresses a packet was sent to and
which link it arrived on, which is how a Control packet carrying no
discriminator finds its session (RFC 5880 Section 6.8.6). They are Linux
control messages: on any other platform that lookup has neither field.
Transmit jitter
RFC 5880 §6.8.7 requires the TX interval to be reduced by 0-25% on each
packet, and the reduction must be at least 10% when detect-multiplier
is 1 so the receiver cannot detect before the next packet arrives. Ze
implements both bands via engine.Loop.applyJitter; operators do not
configure it.
GC pause sensitivity
At 50 ms intervals with mult=3, a 150 ms GC pause looks indistinguishable
from a real failure. Ze's BFD plugin uses pool-backed buffers and runs
every session on a dedicated goroutine (the "express loop") to minimise GC
pressure on the session-driving thread. On a heavily loaded ze instance,
watch for detection-timer expirations that coincide with high allocation
rates elsewhere in the daemon. The metric surface (coming with the wiring
commit) will expose bfd_control_detection_time_expired_total per session
so the correlation is visible in Prometheus.
Interop
ze's wire format matches FRR bfdd, BIRD 3.x, and Junos. Interop tests
against FRR are the primary validation; test/plugin/bfd/ will carry a
namespace-based scenario once the functional tests land.
What is not yet supported
| Feature | RFC | Status |
|---|---|---|
| Demand mode | 5880 §6.6 | Not implemented; rarely deployed. |
| Seamless BFD (S-BFD) | 7880, 7881 | Not implemented. |
| Micro-BFD on LAG | 7130 | Not implemented. |
| Multipoint BFD | 8562 | Not implemented. |
| Data-plane offload | FRR bfddp_packet.h |
Future work. |
The skeleton is intentionally minimum-viable. See the architecture document for the full gap list and the intended follow-up order.
Reference
- Protocol details:
rfc/short/rfc5880.md,rfc5881.md,rfc5882.md,rfc5883.md - Internal architecture:
docs/architecture/bfd.md - Implementation research:
docs/research/bfd-implementation-guide.md