CCNA online course

Using the debug Command in Cisco IOS

Learn how Cisco IOS debug commands work, how to filter and interpret output, and how to troubleshoot safely without overwhelming a network device.

Cisco IOS debug commands produce real-time diagnostic messages about protocol and system activity. They can reveal what a router is doing while an adjacency forms, a DHCP transaction occurs, a NAT translation is created, or an authentication attempt succeeds or fails.

Debugging is powerful but potentially disruptive. Use it briefly, limit its scope, monitor device health, and disable it immediately after collecting the required evidence.

What Cisco IOS Debugging Does

The debug command family reports internal process activity and protocol events as they occur. Depending on the feature, output may show packets being sent or received, state transitions, timer events, neighbor messages, authentication decisions, or translation handling.

Debug Compared with Other Evidence Sources

Debug output: Real-time, detailed events from a selected IOS process. It is useful for seeing why an event is occurring, but it may be verbose and expensive to generate.

Show commands: Point-in-time state and counters, such as interface status, routing tables, ARP entries, neighbors, and NAT translations. Begin with these commands before enabling debug.

Logging: Messages retained or sent by IOS according to logging configuration and severity. Buffered logging provides a limited in-memory record; it is usually safer than watching a high-volume live stream.

Packet captures: Observations of packets on an interface or capture point. A capture can show wire-level fields that may not appear in an IOS debug, while debug can expose internal decisions that a packet capture cannot.

Appropriate Use Cases

  • Finding why an OSPF or EIGRP neighbor does not form.
  • Following DHCP Discover, Offer, Request, and Acknowledgment events.
  • Investigating ARP requests and replies.
  • Examining NAT translation creation and packet address handling.
  • Following RIP updates, PPP negotiation, or supported cryptographic and authentication events.
  • Confirming whether a suspected protocol process receives and processes an event.

Operational Risks and Safe-Use Principles

Debugging can consume CPU utilization, memory, console capacity, and management-session bandwidth. Packet-level or unrestricted protocol debugging can generate a message for every packet. Formatting and transmitting those messages may itself place significant load on the device.

On a busy production router, excessive debug output can delay control-plane work, make the console difficult to use, consume terminal bandwidth, and in severe cases make the device slow or unresponsive. A command that is safe in a quiet lab may be unsafe on a heavily loaded edge router.

  1. Use a maintenance window whenever possible.
  2. Establish the symptom with show commands first.
  3. Choose the least-invasive debug family and narrowest supported filter.
  4. Test one controlled transaction instead of observing unlimited normal traffic.
  5. Monitor CPU, memory, interfaces, and logs while debugging.
  6. Keep a console or second management session available for recovery.
  7. Stop debugging immediately after collecting the required evidence.
show processes cpu sorted
show memory statistics
show interfaces
show debugging

Starting Debug Output

Debug commands are entered from privileged EXEC mode. Use context-sensitive help because available options vary by IOS release, hardware platform, software image, and enabled features.

Router# debug ?
Router# debug ip ?

The question mark displays categories supported by that device. Common families include ip, arp, dhcp, eigrp, ospf, ip rip, ip nat, ppp, and crypto where supported. Do not assume that a command learned on one IOS platform exists on another.

For example, an IOS release may support an adjacency-focused OSPF command such as:

Router# debug ip ospf adj

Confirm the exact syntax with help before enabling it. A protocol command shown in a study guide may have different subcommands, filtering capabilities, or names on the target platform.

Viewing Debug Messages in the Correct Session

Console output and VTY output are not identical. A directly connected console commonly receives system messages by default, while an SSH or Telnet session generally requires terminal monitoring to display log and debug messages.

Router# terminal monitor
Router# terminal logging monitor
Router# terminal length 0

terminal monitor enables log and debug message display for the current remote terminal session. terminal logging monitor controls logging-message display for that session. Terminal settings are session-specific; enabling them in one SSH connection does not necessarily affect another.

terminal length 0 prevents paged output for commands such as show commands. It does not prevent asynchronous debug messages from appearing. Debug output may interrupt a command you are typing, making a separate management session useful for issuing commands and collecting evidence.

If no messages appear in SSH, check terminal monitoring, the active debug list, the conditions or filters, and whether the event has actually been reproduced.

Limiting Debug Scope

Conditional debugging restricts diagnostic output to selected interfaces, peers, addresses, traffic, or protocol processes. The IOS mechanism commonly called debug condition applies a condition to supported debug features. Exact criteria and syntax vary by platform.

Router# debug condition interface GigabitEthernet0/1
Router# debug condition ipv4 access-list 101
Router# show debugging

Some debug commands accept an ACL directly. An ACL filter is useful when only traffic matching selected source, destination, or protocol criteria should produce output. Build and validate the filter carefully: an overbroad ACL can be nearly as noisy as unrestricted debugging, while an overly narrow ACL can hide the fault.

Validate the interface, peer, address, or ACL condition before enabling a verbose diagnostic. When the test is complete, remove active debugging and any temporary conditions according to the platform's supported syntax.

Stopping and Verifying Debugging

Use show debugging to list active debug processes. Disable one feature with its corresponding no debug command when supported, or disable every active debug with undebug all. The common abbreviation is u all.

Router# show debugging
Router# no debug ip ospf adj
Router# undebug all
Router# u all

undebug all is the emergency cleanup command when you are unsure which debugs are active. Verify that debugging is off with show debugging. If the terminal is flooded, stop entering normal commands into the affected stream; use a console, a second management session, or the available escape and recovery method to issue undebug all. If the device is already unresponsive, prioritize out-of-band access and avoid repeatedly sending commands through an overloaded session.

Logging and Timestamp Support

Timestamps make it easier to correlate a debug event with a packet test, interface transition, routing change, or authentication attempt. Buffered logging retains selected messages in device memory for later review.

Router# configure terminal
Router(config)# service timestamps debug datetime msec
Router(config)# service timestamps log datetime msec
Router(config)# logging buffered 16384 debugging
Router(config)# end
Router# show logging

service timestamps adds time information to debug and log messages. The msec option includes milliseconds, which is useful when several protocol events occur close together. logging buffered stores messages in a memory buffer, and show logging displays that buffer and related logging status.

Use logging console and logging monitor carefully. Sending more messages to the console or to remote terminals increases visibility but can increase device and session load. Buffered logging is often a safer evidence location than continuously watching a console.

Core Cisco IOS Debug Control Commands

debug ? — Discover available debug categories. Typical use: inspect platform-specific choices. Safety note: help is safe; enabling a choice is not automatically safe.

show debugging — List enabled debug options. Typical use: baseline and cleanup verification. Safety note: use it before and after a test.

no debug <feature> — Disable one debug feature. Typical use: stop a selected protocol diagnostic. Safety note: confirm other debugs are not still active.

undebug all — Turn off all active debugging. Typical use: immediate cleanup or recovery. Safety note: use after every collection and during output flooding.

terminal monitor — Display log and debug messages in the current remote terminal. Typical use: SSH or Telnet troubleshooting. Safety note: message volume can overwhelm the session.

terminal logging monitor — Control logging-message display for the current terminal. Typical use: manage VTY visibility. Safety note: visibility and load increase with more messages.

show logging — Review buffered messages and logging status. Typical use: inspect timestamped evidence. Safety note: the buffer is limited and can overwrite older entries.

Common Debug Categories

OSPF: debug ip ospf adj or another supported OSPF pattern. Symptom: neighbor does not reach Full. Verify with show ip ospf neighbor, show ip ospf interface, and interface commands. Risk: medium to high depending on scope.

EIGRP: a supported EIGRP neighbor or packet debug pattern. Symptom: missing neighbor or route updates. Verify with show ip eigrp neighbors and show ip route. Risk: medium to high.

RIP: a supported debug ip rip pattern. Symptom: missing or unexpected RIP updates. Verify with show ip protocols and show ip route. Risk: medium.

DHCP: a supported DHCP debug pattern. Symptom: client receives no address. Verify VLAN and interfaces, relay configuration, reachability, and pool state. Risk: medium to high.

NAT: a supported debug ip nat pattern. Symptom: translation is absent or incorrect. Verify interfaces, ACLs, routes, and show ip nat translations. Risk: high if unrestricted.

ARP: a supported debug arp pattern. Symptom: unresolved next-hop or endpoint. Verify VLAN, subnet, interface state, and show ip arp. Risk: medium to high.

PPP: a supported PPP negotiation pattern. Symptom: serial or authenticated PPP link fails. Verify interface state and authentication configuration. Risk: medium.

ICMP: a supported ICMP pattern. Symptom: unexpected echo or unreachable behavior. Verify interfaces, routes, ACLs, and counters. Risk: high when packet volume is large.

How to Interpret Debug Output

Read a short sample line by line and identify the event sequence rather than trying to follow an unlimited stream. Depending on logging configuration and the feature, useful fields may include:

  • A timestamp, including milliseconds if configured.
  • A facility, subsystem, or process identifier.
  • A severity indicator when the message is also treated as a log message.
  • The interface associated with the event.
  • Source and destination addresses, ports, or protocol identifiers.
  • Neighbor, authentication, timer, or protocol state changes.
  • Whether IOS accepted, rejected, forwarded, translated, or discarded an event.

Correlate debug evidence with state and counters. For example, compare OSPF messages with show ip ospf neighbor and interface MTU or timer values; compare ARP messages with show ip arp and VLAN membership; compare NAT events with show ip nat translations, routes, ACL matches, and interface counters.

Collect a short, targeted sample with a known start time, a controlled test, and a known stop time. Save the relevant commands and output, but remove credentials, keys, and sensitive addresses before sharing the evidence.

Safety-First Troubleshooting Workflow

1. Baseline verification: Establish the symptom with show commands. Reason: debugging should test a hypothesis, not replace basic verification. Examples: show interfaces, show ip route, show ip arp, protocol neighbor commands.

2. Enable remote output visibility: Use terminal monitor and appropriate terminal settings. Reason: a VTY may not display debug messages otherwise. Example: terminal monitor.

3. Apply a filter or condition: Select an interface, peer, address, or ACL where supported. Reason: reduce output and device load. Example: debug condition interface GigabitEthernet0/1.

4. Enable targeted debug: Choose the narrowest protocol-specific command. Reason: align evidence with the hypothesis. Example: debug ip ospf adj.

5. Capture evidence: Reproduce one event and record timestamps, commands, output, and state changes. Reason: controlled samples are easier to interpret.

6. Disable debug: Use no debug <feature> or undebug all. Reason: remove unnecessary load immediately.

7. Validate resolution: Repeat show commands and the original test. Reason: confirm the protocol state and user symptom both improved.

Practical Scenario: OSPF Neighbor Not Reaching Full

  1. Check interface addressing, subnet masks, interface status, OSPF area assignment, passive-interface settings, timers, MTU, and current neighbor state.
  2. If the cause remains unclear, use an adjacency-focused debug supported by the IOS release.
  3. Look for hello exchange, area or timer mismatches, authentication failures, MTU problems, and database description negotiation.
  4. Stop the debug with undebug all and confirm the neighbor reaches Full with show ip ospf neighbor.

For configuration context, see Configure OSPF.

Practical Scenario: DHCP Client Receives No Address

  1. Verify the client VLAN, access or trunk path, interface status, relay configuration, helper address, server reachability, and address-pool availability.
  2. Enable the platform-supported DHCP debug only after the baseline checks.
  3. Follow Discover, Offer, Request, and Acknowledgment events.
  4. Use the sequence to distinguish a client or VLAN problem, relay problem, unreachable server, server-side failure, or exhausted pool.
  5. Disable the debug and retest the client.

Practical Scenario: NAT Translation Behavior

  1. Confirm inside and outside interface roles, the translation ACL, route availability, and existing translations.
  2. Use a narrowly scoped NAT debug if the platform supports one.
  3. Correlate source and destination addresses and ports in the debug with show ip nat translations and interface counters.
  4. Stop debugging and validate a new connection after remediation.

Practical Scenario: ARP Resolution Failure

  1. Check VLAN membership, interface state, IP subnet consistency, and the ARP table.
  2. Use ARP debugging only for the affected interface or endpoint when possible.
  3. Interpret request and reply activity: requests without replies may indicate a Layer 2 path, endpoint, VLAN, or subnet problem; replies received but not installed may indicate a local processing or configuration issue.
  4. Disable the debug and verify the ARP entry and connectivity.

Practical Scenario: Safely Debugging a Remote SSH Session

Router# terminal monitor
Router# terminal logging monitor
Router# show debugging
Router# show logging
Router# undebug all

Configure timestamps and optionally a bounded logging buffer before the test. Keep a second SSH session, console, or out-of-band path available. If output becomes excessive, issue undebug all from the alternate path, then inspect CPU, memory, and logs before trying again with a narrower condition.

Common Problems and Recovery

No Debug Lines Appear in SSH

  • Run terminal monitor.
  • Check show debugging to confirm the required category is active.
  • Check that terminal logging is enabled if log visibility is required.
  • Verify that a condition or ACL filter actually matches the test.
  • Generate the event being investigated; an idle protocol may produce no output.

The Router Becomes Slow or Unresponsive

  • Immediately issue undebug all from a console or alternate management session.
  • Check show processes cpu sorted, show memory statistics, and show logging.
  • Retry only with a less verbose debug and a narrow interface, peer, address, or ACL condition.

The Output Does Not Explain the Failure

  • Return to interface, VLAN, ARP, routing, and ACL verification.
  • Confirm the affected traffic reaches the device and that the test is generating the expected event.
  • Select a debug aligned with the suspected protocol stage and network layer.

The Output Is Too Noisy

  • Stop debugging.
  • Apply a supported conditional filter or ACL.
  • Run one controlled transaction during a quieter period.
  • Use timestamps and buffered logging to retain a short sample.

Exam-Relevant Notes

  • debug produces real-time diagnostic output; show commands display current state and counters.
  • A remote VTY session commonly needs terminal monitor to display debug messages.
  • show debugging verifies active debug processes.
  • undebug all and u all disable all active debugging.
  • no debug <feature> disables an individual debug feature when supported.
  • Debug syntax and available categories vary by IOS release, platform, and enabled features.
  • Use narrow, conditional debugging and monitor CPU utilization; never leave unnecessary debugging enabled.
  • Timestamped, short samples are more useful than unlimited terminal output.