Repository navigation
BGP State Machine
Understanding BGP's RFC 4271 State Machine
The BGP Finite State Machine (FSM) defines the behavior of BGP sessions as they progress through connection establishment, capability negotiation, and route exchange. Understanding the FSM is essential for troubleshooting BGP sessions and understanding ExaBGP's behavior.
- Overview
- State Machine States
- State Descriptions
- State Transitions
- Common State Transition Scenarios
- ExaBGP FSM Behavior
- Troubleshooting with State Machine Knowledge
- See Also
- References
Reference: RFC 4271 Section 8 - BGP Finite State Machine
The BGP FSM consists of six states that a BGP session transitions through:
┌──────┐ Start ┌─────────┐ TCP OK, OPEN sent ┌──────────┐
│ Idle │────────>│ Connect │───────────────────────>│ OpenSent │
└──────┘ └─────────┘ └──────────┘
^ │ ^ │ ^
│ TCP fail │ │ ConnectRetry │ │ TCP OK, OPEN sent
│ v │ expires │ │
│ ┌─────────┐ │ ┌────────┐
│ │ Active │───────────────────────────┼─>│(Active)│
│ └─────────┘ │ └────────┘
│ OPEN received │
│ v
│ KEEPALIVE received ┌─────────────┐
│ ┌─────────────┐<───────────────────── │ OpenConfirm │
│ │ Established │ └─────────────┘
│ └─────────────┘
│ │
└─────────────┘
(Any error: NOTIFICATION, Hold Timer expiry, TCP failure)
| State | Number | Description | Next State (Success) |
|---|---|---|---|
| Idle | 1 | Initial state, awaiting Start event | Connect |
| Connect | 2 | Attempting TCP connection | OpenSent |
| Active | 3 | Retrying TCP connection after failure | OpenSent |
| OpenSent | 4 | TCP connected, OPEN message sent | OpenConfirm |
| OpenConfirm | 5 | OPEN received, KEEPALIVE sent | Established |
| Established | 6 | Peering session active, routes exchanged | (Session active) |
Waiting for Start event, normally initiated by operator (establishing new BGP session or resetting an existing session). After errors, BGP falls back to the Idle state.
Characteristics:
- No resources allocated
- No TCP connection
- Waiting for administrative or automatic start
Transitions: After a Start event, BGP:
- Initializes all BGP resources
- Resets ConnectRetryTimer
- Initiates TCP transport connection
- Listens for connections initiated by remote peer
- Moves to Connect state
Triggers:
- Manual BGP session start
- Automatic restart after error
- Configuration change
BGP is waiting for transport protocol connection to complete.
Characteristics:
- TCP connection in progress
- ConnectRetryTimer running
- Listening for incoming connections
Possible Transitions:
- TCP connection succeeds → OpenSent state, send OPEN message
- TCP connection fails → Active state
- ConnectRetryTimer expires → Remain in Connect, reset timer, retry connection
- Other events → Idle state
Typical Duration: Milliseconds to seconds (depending on network latency)
BGP is trying to initiate a transport protocol connection and acquire a peer.
Characteristics:
- Previous TCP connection attempt failed
- Actively retrying connection
- Still listening for incoming connections
- ConnectRetryTimer running
Possible Transitions:
- TCP connection succeeds → OpenSent state, send OPEN message
- ConnectRetryTimer expires → Restart timer, fall back to Connect state
- Incoming connection from peer → OpenSent state
- Other events → Idle state
Common Causes:
- Network unreachable
- Firewall blocking connection
- Peer not listening
- Incorrect peer IP/port
TCP connection established, OPEN message sent, waiting for OPEN from peer.
Characteristics:
- TCP session active
- OPEN message sent to peer
- Waiting for peer's OPEN message
- Validating peer's OPEN parameters
OPEN Message Validation: BGP checks:
- BGP version (must be 4)
- Peer AS number (matches configuration)
- BGP Identifier (valid, non-zero)
- Optional Parameters (capabilities)
Possible Transitions:
- Valid OPEN received → OpenConfirm state, send KEEPALIVE
- Invalid OPEN received → Send NOTIFICATION, return to Idle
- TCP connection fails → Idle state
- HoldTimer expires → Send NOTIFICATION, return to Idle
OPEN messages exchanged, KEEPALIVE sent, waiting for KEEPALIVE from peer.
Characteristics:
- Both OPEN messages validated
- KEEPALIVE sent to peer
- Waiting for peer's KEEPALIVE
- Almost ready for route exchange
Possible Transitions:
- KEEPALIVE received → Established state (session UP!)
- TCP connection fails → Idle state
- NOTIFICATION received → Idle state
- HoldTimer expires → Send NOTIFICATION, return to Idle
Typical Duration: Very brief (milliseconds)
BGP session is fully established and operational.
Characteristics:
- Peering session active
- Routes being exchanged (UPDATE messages)
- KEEPALIVE messages sent periodically
- Monitoring peer liveness
Activities:
- Receive UPDATEs: Process route advertisements
- Send UPDATEs: Announce local routes
- Send KEEPALIVEs: Maintain session liveness
- Monitor HoldTimer: Detect peer failure
Possible Transitions:
- NOTIFICATION received → Idle state
- TCP connection fails → Idle state
- HoldTimer expires → Send NOTIFICATION, return to Idle
- Administrative shutdown → Send NOTIFICATION, return to Idle
- OPEN received → answered with NOTIFICATION 5/3, Finite State Machine Error in the Established state (RFC 6608), return to Idle. 5/1 and 5/2, the errors for an unexpected message in OpenSent and OpenConfirm, carry the type of the message as their data
| Event | Description |
|---|---|
| Start | Manual/automatic session initialization |
| TCP Connection Valid | TCP three-way handshake succeeds |
| TCP Connection Fails | TCP connection refused/times out |
| BGP Open (valid) | Valid OPEN message received |
| BGP Open (invalid) | Invalid OPEN message received |
| BGP Header Error | Malformed BGP message |
| Keepalive Message | KEEPALIVE received |
| Update Message | UPDATE received |
| Notification Message | NOTIFICATION received (error) |
| Hold Timer Expires | No message received within HoldTime |
| ConnectRetry Timer Expires | Connection retry timeout |
Idle → Connect → OpenSent → OpenConfirm → Established
(Start) (TCP OK) (OPEN OK) (KEEPALIVE)
Timeline (typical):
- Idle: 0ms - Administrator enables BGP
- Connect: 0-100ms - TCP SYN, SYN-ACK, ACK
- OpenSent: 0-10ms - Send OPEN, receive OPEN
- OpenConfirm: 0-5ms - Send KEEPALIVE, receive KEEPALIVE
- Established: Session active
Total time: 10ms - 200ms (typical)
Idle → Connect → Active → Connect → Active → ...
(Start) (TCP fail) (Retry) (Fail)
Behavior:
- Oscillates between Connect and Active states
- ConnectRetryTimer governs retry interval, jittered by a random factor between 0.75 and 1 (RFC 4271 section 10), as is the keepalive interval
- Eventually gives up or succeeds
Idle → Connect → OpenSent → Idle
(Start) (TCP OK) (Bad OPEN, NOTIFICATION)
Common Reasons:
- AS number mismatch
- Unsupported BGP version
- Bad BGP Identifier (0.0.0.0 or duplicate)
- Unsupported capabilities
Idle → ... → Established → Idle
(NOTIFICATION or TCP fail)
Common Causes:
- Invalid UPDATE message
- HoldTimer expiration (peer dead)
- TCP connection lost
- Administrative shutdown
Standard Compliance:
- ✅ Fully RFC 4271 compliant FSM
- ✅ All six states implemented
- ✅ Proper timer handling (HoldTimer, ConnectRetryTimer)
ExaBGP-Specific Behavior:
- API Control: Your program can trigger Start events
- Graceful Restart: RFC 4724 extends FSM with restart state
- Connection Collision Detection: RFC 4271 Section 6.8. When the peer connects while our own connection is in OpenSent, ExaBGP sends its OPEN on the new connection and decides once the peer's OPEN has been read: the connection opened by the speaker with the higher BGP Identifier is kept, and when both identifiers are equal, which only an external peer may have, the one opened by the speaker with the larger AS number (RFC 6286 2.3). The other is closed with Cease 6/7. A new connection used to replace ours every time
- Graceful Restart reconnection: a peer which advertised Graceful Restart and connects again while established replaces the session once its new OPEN is found valid; see Graceful Restart
- API Notifications: ExaBGP sends FSM state changes to your program
State Change Notifications: with fsm; in the neighbor's api block, a process using
the JSON encoder receives each change of state, the state written in capitals (IDLE,
ACTIVE, CONNECT, OPENSENT, OPENCONFIRM, ESTABLISHED). ExaBGP 6.0 writes, on one line:
{ "exabgp": "6.0.0", "time": 1790848264.91, "host": "exabgp-host", "pid": 12345, "ppid": 1, "counter": 6, "type": "fsm", "neighbor": { "address": { "local": "192.0.2.2", "peer": "192.0.2.1" }, "asn": { "local": 65001, "peer": 65000 }, "router-id": "192.0.2.2", "state": "ESTABLISHED" } }The text encoder does not report these changes. With neighbor-changes;, both encoders report
the session going up and down, the text encoder as:
neighbor 192.0.2.1 connected
neighbor 192.0.2.1 up
neighbor 192.0.2.1 down - closing connection
Symptom: BGP stays in Connect state
Possible Causes:
- Firewall blocking TCP/179
- Peer not reachable (routing issue)
- Peer not listening on TCP/179
- Wrong IP address configured
Debugging:
# Check TCP connectivity
telnet 192.0.2.1 179
# Check ExaBGP logs
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf
# Look for:
# "connecting to peer 192.0.2.1"
# "connection refused" or "connection timeout"Symptom: BGP oscillates between Connect and Active
Possible Causes:
- Same as Connect state
- TCP connection fails repeatedly
Debugging:
# Check if peer is trying to connect to you
tcpdump -i eth0 'tcp port 179'
# Check firewall
iptables -L -n | grep 179Symptom: TCP connected, but no OPEN received
Possible Causes:
- Peer waiting for OPEN from you (version mismatch)
- Peer rejecting your OPEN (sending NOTIFICATION)
- HoldTimer too short
Debugging:
# ExaBGP logs show OPEN rejection reason
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf
# Look for:
# "received notification"
# "bad peer as" or "unsupported version"Common Errors:
-
AS mismatch:
peer-as 65001in config doesn't match peer's AS - Router-ID conflict: Duplicate router-id within one AS. Two speakers in different ASes may share a BGP Identifier (RFC 6286)
- Capability mismatch: Peer doesn't support required capability
Symptom: Session goes Established → Idle repeatedly
Possible Causes:
- HoldTimer expiration (peer not sending KEEPALIVEs)
- Invalid UPDATE messages
- TCP connection instability
- Your API program crashes
Debugging:
# Check for NOTIFICATION messages
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf
# Look for:
# "received notification"
# "hold timer expired"
# "invalid update message"
# Check if your API process is crashing
ps aux | grep your-api-program- RFC 4271 - BGP-4 - Complete BGP specification
- Operations: Debugging - Troubleshooting BGP sessions
- Configuration: Neighbor Configuration - BGP timers
- API: Error Handling - Handling FSM state changes
- Features: Graceful Restart - FSM extensions for restart
-
RFC 4271 - A Border Gateway Protocol 4 (BGP-4)
- Section 8: BGP Finite State Machine
- Section 6.8: BGP Connection Collision Detection
- RFC 4724 - Graceful Restart Mechanism for BGP
- Netcraftsmen BGP FSM Article - Classic FSM reference
-
ExaBGP Source:
src/exabgp/bgp/fsm.py- FSM states
Getting Started
Configuration
- Configuration Syntax
- Neighbor Configuration
- Directives A-Z
- Syntax Reference
- Templates
- Environment Variables
- Process Configuration
API
- API Overview
- Text API Reference
- JSON API Reference
- API Commands
- Writing API Programs
- Error Handling
- Production Best Practices
Address Families
- Overview
- IPv4 Unicast
- IPv6 Unicast
- FlowSpec
- EVPN
- L3VPN
- BGP-LS
- VPLS
- SRv6 / MUP
- Multicast
- RT Constraint
Features
Use Cases
Tools
Operations
Reference
- Architecture
- Design
- Attribute Reference
- Command Reference
- BGP State Machine
- Capabilities
- Communities
- Examples Index
- Glossary
- RFC Support
Integration
Migration
Community
External