debug ip bgp
Enables debugging of BGP events and updates to troubleshoot BGP neighbor relationships and route advertisement issues.
Definition: debug ip bgp is a Cisco IOS privileged exec command. Enables debugging of BGP events and updates to troubleshoot BGP neighbor relationships and route advertisement issues.
Overview
The `debug ip bgp` command is a powerful diagnostic tool used in Cisco IOS privileged EXEC mode to enable real-time logging of BGP (Border Gateway Protocol) events and updates. BGP is the de facto exterior gateway protocol used to exchange routing information between autonomous systems (ASes) on the Internet and in large enterprise networks. This command is essential for troubleshooting BGP neighbor relationships, route advertisement issues, and policy-based routing problems.
When a network engineer suspects issues such as flapping BGP sessions, missing routes, or incorrect path selection, `debug ip bgp` provides granular insight into the BGP state machine, update messages, and keepalive exchanges. Unlike `show ip bgp` commands that offer static snapshots, debugging reveals dynamic behavior in real time, making it invaluable for isolating transient problems. However, because BGP debugging can generate a high volume of output—especially in networks with many prefixes—it should be used with caution and typically only during maintenance windows or on low-traffic links.
The command does not alter the running configuration but does require privileged EXEC access (level 15). Output is buffered by default; to see it immediately, use `terminal monitor` if connected via Telnet/SSH. Alternatives include `debug ip bgp updates` for more focused update tracking or `debug ip bgp keepalives` for session health.
In the broader troubleshooting workflow, `debug ip bgp` is often preceded by verifying BGP summary and neighbor states with `show ip bgp summary` and `show ip bgp neighbors`, and followed by analyzing route tables with `show ip bgp` and `show ip route bgp`. It is a critical tool for CCNA and CCNP candidates to master, as BGP troubleshooting is a core competency for network professionals.
debug ip bgpWhen to Use This Command
- Diagnosing why a BGP session is flapping or not establishing
- Verifying BGP route advertisements and withdrawals between peers
- Troubleshooting BGP path selection or missing routes
- Monitoring BGP keepalive and update messages in real time
Parameters
| Parameter | Syntax | Description |
|---|---|---|
| A.B.C.D | A.B.C.D | Specifies the IP address of a BGP neighbor to limit debugging to that specific neighbor. This reduces output clutter when troubleshooting a single peer. Common mistake: using an incorrect or unreachable IP address, which results in no debug output for that neighbor. |
| updates | updates | Enables debugging of BGP update messages only, including route advertisements, withdrawals, and attribute changes. Useful for focusing on route exchange without session-level noise. Common mistake: forgetting that updates are a subset of general BGP debug; use this to filter out keepalives and notifications. |
| keepalives | keepalives | Enables debugging of BGP keepalive messages. Helpful for verifying that keepalive intervals and hold timers are functioning correctly. Common mistake: assuming keepalive debugs are low-volume; they can still be frequent (every 60 seconds by default) and may fill logs. |
| events | events | Enables debugging of BGP state machine events, such as neighbor transitions (Idle, Connect, Active, OpenSent, OpenConfirm, Established). Essential for troubleshooting session flapping. Common mistake: not using this parameter when the issue is session state-related; it provides the clearest view of state changes. |
| filters | filters | Enables debugging of BGP filter processing, including prefix-list, route-map, and distribute-list actions. Useful for verifying that inbound/outbound filters are applied correctly. Common mistake: expecting to see filtered routes in the debug output; this debug shows the filter evaluation, not the routes themselves. |
Command Examples
Basic BGP debugging with neighbor IP
debug ip bgp 192.168.1.1 updatesBGP: 192.168.1.1 sending UPDATE about 10.0.0.0/24 (path: 65001) - NEXT_HOP 192.168.1.1 BGP: 192.168.1.1 received UPDATE about 172.16.0.0/16 (path: 65002) - NEXT_HOP 192.168.1.2 BGP: 192.168.1.1 received UPDATE about 10.0.0.0/24 - withdrawn BGP: 192.168.1.1 sending KEEPALIVE BGP: 192.168.1.1 received KEEPALIVE
Each line shows a BGP event. 'sending UPDATE' indicates the router is advertising a route; 'received UPDATE' means it learned a route from the neighbor. The path shows AS_PATH. 'withdrawn' means the route is being removed. KEEPALIVE messages maintain the session.
Debug BGP events for all neighbors
debug ip bgp eventsBGP: 192.168.1.1 went from Active to OpenSent BGP: 192.168.1.1 went from OpenSent to OpenConfirm BGP: 192.168.1.1 went from OpenConfirm to Established BGP: 192.168.1.1 went from Established to Idle (Keepalive timer expired)
Shows state transitions of BGP neighbor sessions. 'Established' is the desired state. Transitions to 'Idle' indicate a problem, such as a keepalive timeout or configuration mismatch.
Understanding the Output
The debug ip bgp command outputs real-time BGP events. For updates, each line shows the neighbor IP, direction (sending/received), prefix, AS_PATH, and NEXT_HOP. 'withdrawn' indicates route removal.
For events, state transitions are shown: Idle, Active, OpenSent, OpenConfirm, Established. A healthy session stays in Established. Frequent transitions to Idle or Active indicate issues like misconfigured passwords, AS numbers, or network reachability.
Keepalive messages should appear periodically; missing keepalives may cause session drops. Use 'undebug all' to stop debugging.
Configuration Scenarios
Troubleshoot BGP neighbor flapping between two routers
A BGP session between R1 (AS 65001) and R2 (AS 65002) is flapping, causing intermittent route loss. The engineer needs to identify the cause of the state transitions.
Topology
R1(Gi0/0)---10.0.12.0/30---(Gi0/0)R2Steps
- 1.Step 1: Enter privileged EXEC mode on R1: enable
- 2.Step 2: Enable BGP event debugging for the specific neighbor: debug ip bgp events 10.0.12.2
- 3.Step 3: Observe the output for state transitions (e.g., Active -> Connect -> Idle). Look for error messages like 'BGPNotification sent' or 'hold timer expired'.
- 4.Step 4: If needed, also enable keepalive debugging: debug ip bgp keepalives 10.0.12.2
- 5.Step 5: After collecting sufficient data, disable debugging: undebug all
! No configuration changes needed for debugging R1# debug ip bgp events 10.0.12.2 R1# debug ip bgp keepalives 10.0.12.2
Verify: Use 'show ip bgp summary' to check neighbor state. Expected output shows state as Established and uptime increasing. Debug output should show stable keepalive exchanges and no state transitions.
Watch out: Forgetting to specify the neighbor IP address results in debug output for all BGP peers, which can overwhelm the console and mask the issue.
Verify BGP route advertisement with inbound prefix-list filtering
R1 (AS 65001) is not receiving a specific prefix (192.168.1.0/24) from R2 (AS 65002). The engineer suspects an inbound prefix-list on R1 is filtering the route.
Topology
R1(Gi0/0)---10.0.12.0/30---(Gi0/0)R2
R2 has loopback0: 192.168.1.1/24Steps
- 1.Step 1: Enter privileged EXEC mode on R1: enable
- 2.Step 2: Enable BGP update debugging for neighbor R2: debug ip bgp updates 10.0.12.2
- 3.Step 3: Also enable filter debugging: debug ip bgp filters 10.0.12.2
- 4.Step 4: On R2, advertise the prefix (if not already) or clear BGP session: clear ip bgp 10.0.12.1 soft out
- 5.Step 5: Observe debug output on R1. Look for 'UPDATE' messages and any 'filtered by prefix-list' or 'denied' messages.
- 6.Step 6: Disable debugging: undebug all
! On R1, enable debugging R1# debug ip bgp updates 10.0.12.2 R1# debug ip bgp filters 10.0.12.2 ! On R2, trigger update R2# clear ip bgp 10.0.12.1 soft out
Verify: Check 'show ip bgp neighbors 10.0.12.2 advertised-routes' on R2 to confirm the prefix is sent. On R1, 'show ip bgp' should show the prefix if not filtered. Debug output should indicate if the prefix was received and then filtered.
Watch out: The 'filters' debug only shows filter evaluation, not the actual route content. To see the route attributes, use 'debug ip bgp updates' without filters.
Troubleshooting with This Command
When using `debug ip bgp` for troubleshooting, it is crucial to understand what healthy output looks like versus indicators of problems. In a stable BGP session, the debug output for events should show periodic keepalive messages and no state transitions. For example, a healthy session will display 'BGP: 10.0.12.2 passive open' followed by 'BGP: 10.0.12.2 went from Active to OpenSent' and eventually 'BGP: 10.0.12.2 went from OpenConfirm to Established'.
After that, only keepalive messages (if enabled) or occasional updates appear. Problem indicators include repeated state transitions (e.g., from Established to Idle), 'BGPNotification sent' messages with error codes (such as 'Cease' or 'Open Message Error'), or 'hold timer expired' messages. The hold timer expiry often points to a mismatch in hold time configuration or connectivity issues.
Focus on the 'BGP: 10.0.12.2 went from X to Y' lines to track the state machine. Common symptoms this command helps diagnose include: session flapping (due to misconfigured timers, MTU issues, or authentication failures), missing routes (due to filtering or next-hop unreachability), and route advertisement delays. A step-by-step diagnostic flow: 1) Start with `debug ip bgp events` to see if the session is stable. 2) If flapping, look for error codes in notifications. 3) If routes are missing, enable `debug ip bgp updates` and `debug ip bgp filters` to see if updates are sent/received and if filters are applied. 4) Correlate with `show ip bgp neighbors 10.0.12.2` to verify timers and capabilities. 5) Use `show ip bgp` to confirm the route table.
Combine with `debug ip bgp keepalives` to verify keepalive exchange. Remember that debug output is high-priority and can impact router performance; always use specific neighbor IPs and disable debugging immediately after gathering data. Also, use `logging buffered` to capture output without overwhelming the console.
CCNA Exam Tips
Remember that 'debug ip bgp' is CPU-intensive; always use specific keywords like 'updates' or 'events' to limit output.
The CCNA exam may ask which debug command to use to see BGP route advertisements; answer: 'debug ip bgp updates'.
Know that BGP states (Idle, Active, OpenSent, OpenConfirm, Established) are tested; Established is the goal.
Be aware that 'debug ip bgp' requires privileged EXEC mode and can impact production routers.
Common Mistakes
Running 'debug ip bgp' without specifying a neighbor or filter, flooding the console with excessive output.
Forgetting to disable debugging with 'undebug all' or 'no debug ip bgp', causing performance degradation.
Misinterpreting 'withdrawn' as an error; it is normal when routes are removed due to policy or network changes.
debug ip bgp vs undebug all
These two commands are often paired because debugging BGP (debug ip bgp) generates high CPU load, and undebug all is the quickest way to stop all debugging, including BGP. They are considered together when troubleshooting BGP issues and then cleaning up.
| Aspect | debug ip bgp | undebug all |
|---|---|---|
| Scope | BGP events and updates only | All debug operations on the router |
| Persistence | Persists until manually disabled or router reload | Immediate and stops all debugs at once |
| Impact on CPU | Increases CPU load due to processing BGP messages | Reduces CPU load by stopping all debug output |
| Mode | Privileged EXEC | Privileged EXEC |
| Precedence | Overridden by undebug all | Overrides all individual debug commands |
| Typical use | Troubleshoot BGP neighbor relationships and route advertisements | Disable all debugging after troubleshooting or to recover from high CPU |
Use debug ip bgp when you need to monitor BGP updates and neighbor state changes to diagnose route advertisement or peering problems.
Use undebug all when you need to immediately disable all active debugging to restore normal CPU usage after troubleshooting.
Platform Notes
In IOS-XE (e.g., 16.x), the `debug ip bgp` command syntax and output are largely identical to classic IOS, but there may be slight differences in the formatting of timestamps and error messages. The command is fully supported. On NX-OS (Cisco Nexus switches), the equivalent command is `debug bgp` with similar sub-options like `events`, `updates`, and `keepalives`.
For example, `debug bgp events` and `debug bgp updates` work on NX-OS. However, NX-OS uses a different CLI structure; you must enter the `debug` command from the CLI without the `ip` keyword. Also, NX-OS requires `terminal monitor` to see debug output.
On ASA (Adaptive Security Appliance), BGP is not supported in most models; ASAs use OSPF or EIGRP for routing, so `debug ip bgp` does not apply. For IOS-XR (Cisco's carrier-grade OS), the command is `debug bgp` (similar to NX-OS) with options like `debug bgp updates` and `debug bgp events`. IOS-XR also supports `debug bgp neighbor <ip-address>` to filter.
Note that in IOS 12.x, the output may be less verbose than in 15.x/16.x, but the core functionality remains the same. Always check the specific platform documentation for exact syntax, as minor variations exist.
Related Commands
show ip bgp
Displays the BGP routing table, showing learned BGP routes and their attributes, used for troubleshooting BGP path selection and verifying route advertisement.
show ip bgp neighbors
Displays detailed information about BGP neighbor sessions, including state, timers, and advertised/received prefixes, used to verify BGP peering and troubleshoot neighbor relationships.
undebug all
Disables all active debug operations on the router, used to stop debugging output and reduce CPU load.
Practice for the CCNA 200-301
Test your knowledge with practice questions covering all CCNA 200-301 exam domains.
Practice CCNA 200-301 Questions