Guest

Cisco IOS Software Releases 12.3 T

Crypto Conditional Debug Support

Hierarchical Navigation

Downloads

Table Of Contents

Crypto Conditional Debug Support

Contents

Prerequisites for Crypto Conditional Debug Support

Restrictions for Crypto Conditional Debug Support

Information About Crypto Conditional Debug Support

Supported Condition Types

How to Enable Crypto Conditional Debug Support

Enabling Crypto Conditional Debug Messages

Performance Considerations

Disable Crypto Debug Conditions

Enabling Crypto Error Debug Messages

debug crypto error CLI

Configuration Examples for the Crypto Conditional Debug CLIs

Enabling Crypto Conditional Debugging: Example

Disabling Crypto Conditional Debugging: Example

Additional References

Related Documents

Standards

MIBs

RFCs

Technical Assistance

Command Reference

debug crypto condition

debug crypto condition unmatched

debug crypto error

show crypto debug-condition


Crypto Conditional Debug Support

The Crypto Conditional Debug Support feature introduces three new command-line interfaces (CLIs) that allow users to debug an IP Security (IPSec) tunnel on the basis of predefined crypto conditions such as the peer IP address, connection-ID of a crypto engine, and security parameter index (SPI). By limiting debug messages to specific IPSec operations and reducing the amount of debug output, users can better troubleshoot a router with a large number of tunnels.

Feature History for Crypto Conditional Debug Support

Feature History
 
Release
Modification

12.3(2)T

This feature was introduced.


Finding Support Information for Platforms and Cisco IOS Software Images

Use Cisco Feature Navigator to find information about platform support and Cisco IOS software image support. Access Cisco Feature Navigator at http://www.cisco.com/go/fn. You must have an account on Cisco.com. If you do not have an account or have forgotten your username or password, click Cancel at the login dialog box and follow the instructions that appear.

Contents

•Prerequisites for Crypto Conditional Debug Support

•Restrictions for Crypto Conditional Debug Support

•Information About Crypto Conditional Debug Support

•How to Enable Crypto Conditional Debug Support

•Configuration Examples for the Crypto Conditional Debug CLIs

•Additional References

•Command Reference

Prerequisites for Crypto Conditional Debug Support

To use the new crypto CLIs, you must be using a crypto image, such as the k8 or k9 subsystem.

Restrictions for Crypto Conditional Debug Support

•This feature does not support debug message filtering for hardware crypto engines.

•Although conditional debugging is useful for troubleshooting peer-specific or functionality related Internet Key Exchange (IKE) and IPSec problems, conditional debugging may not be able to define and check large numbers of debug conditions.

Because extra space is needed to store the debug condition values, additional processing overhead is added to the CPU and memory usage is increased. Thus, enabling crypto conditional debugging on a router with heavy traffic should be used with caution.

Information About Crypto Conditional Debug Support

To enable the conditional crypto debug commands, you should understand the following concept:

•Supported Condition Types

Supported Condition Types

The new crypto conditional debug CLIs—debug crypto condition, debug crypto condition unmatched, and show crypto debug-condition—allow you to specify conditions (filter values) in which to generate and display debug messages related only to the specified conditions. Table 1 lists the supported condition types.

Table 1 Supported Condition Types for Crypto Debug CLI  

Condition Type (Keyword)
Description

connid1

An integer between 1-32766. Relevant debug messages will be shown if the current IPSec operation uses this value as the connection ID to interface with the crypto engine.

flowid1

An integer between 1-32766. Relevant debug messages will be shown if the current IPSec operation uses this value as the flow-ID to interface with the crypto engine.

FVRF

The name string of a virtual private network (VPN) routing and forwarding (VRF) instance. Relevant debug messages will be shown if the current IPSec operation uses this VRF instance as its front-door VRF (FVRF).

IVRF

The name string of a VRF instance. Relevant debug messages will be shown if the current IPSec operation uses this VRF instance as its inside VRF (IVRF).

peer group

A Unity group-name string. Relevant debug messages will be shown if the peer is using this group name as its identity.

peer hostname

A fully qualified domain name (FQDN) string. Relevant debug messages will be shown if the peer is using this string as its identity; for example, if the peer is enabling IKE Xauth with this FQDN string.

peer ipaddress

A single IP address. Relevant debug messages will be shown if the current IPSec operation is related to the IP address of this peer.

peer subnet

A subnet and a subnet mask that specify a range of peer IP addresses. Relevant debug messages will be shown if the IP address of the current IPSec peer falls into the specified subnet range.

peer username

A username string. Relevant debug messages will be shown if the peer is using this username as its identity; for example, if the peer is enabling IKE Extended Authentication (Xauth) with this username.

SPI1

A 32-bit unsigned integer. Relevant debug messages will be shown if the current IPSec operation uses this value as the SPI.

1 If an IPSec connid, flowid, or SPI is used as a debug condition, the debug messages for a related IPSec flow are generated. An IPSec flow has two connids, flowids, and SPIs—one inbound and one outbound. Both two connids, flowids, and SPIs can be used as the debug condition that triggers debug messages for the IPSec flow.


How to Enable Crypto Conditional Debug Support

This section contains the following procedures:

•Enabling Crypto Conditional Debug Messages

•Enabling Crypto Error Debug Messages

Enabling Crypto Conditional Debug Messages

To enable crypto conditional debug filtering, you must perform the following tasks.

Performance Considerations

•Before enabling crypto conditional debugging, you must decide what debug condition types (also known as debug filters) and values will be used. The volume of debug messages is dependent on the number of conditions you define.

Note Specifying numerous debug conditions may consume CPU cycles and negatively affect router performance.

•Your router will perform conditional debugging only after at least one of the global crypto debug commands—debug crypto isakmp, debug crypto ipsec, and debug crypto engine—has been enabled. This requirement helps to ensure that the performance of the router will not be impacted when conditional debugging is not being used.

Disable Crypto Debug Conditions

If you choose to disable crypto conditional debugging, you must first disable any crypto global debug CLIs you have issued; thereafter, you can disable conditional debugging.

Note The reset keyword can be used to disable all configured conditions at one time.

SUMMARY STEPS

1. enable

2. debug crypto condition [connid integer engine-id integer] [flowid integer engine-id integer] [fvrf string] [ivrf string] [peer [group string] [hostname string] [ipv4 ipaddress] [subnet subnet mask] [username string]] [spi integer] [reset]

3. show crypto debug-condition {[peer] [connid] [spi] [fvrf] [ivrf] [unmatched]}

4. debug crypto isakmp

5. debug crypto ipsec

6. debug crypto engine

7. debug crypto condition unmatched [isakmp | ipsec | engine] (optional)

DETAILED STEPS

 
Command or Action
Purpose

Step 1 

enable

Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2 

debug crypto condition [connid integer engine-id integer] [flowid integer engine-id integer] [fvrf string] [ivrf string] [peer [group string] [hostname string] [ipv4 ipaddress] [subnet subnet mask] [username string]] [spi integer] [reset]

Example:

Router# debug crypto condition connid 2000 engine-id 1

Defines conditional debug filters.

Step 3 

show crypto debug-condition {[peer] [connid] [spi] [fvrf] [ivrf] [unmatched]}

Example:

Router# show crypto debug-condition spi

Displays crypto debug conditions that have already been enabled in the router.

Step 4 

debug crypto isakmp

Example:

Router# debug crypto isakmp

Enables global IKE debugging.

Step 5 

debug crypto ipsec

Example:

Router# debug crypto ipsec

Enables global IPSec debugging.

Step 6 

debug crypto engine

Example:

Router# debug crypto engine

Enables global crypto engine debugging.

Step 7 

debug crypto condition unmatched [isakmp | ipsec | engine]

Example:

Router# debug crypto condition unmatched ipsec

(Optional) Displays debug conditional crypto messages when no context information is available to check against debug conditions.

If none of the optional keywords are specified, all crypto-related information will be shown.

Enabling Crypto Error Debug Messages

To enable crypto error debug messages, you must perform the following tasks.

debug crypto error CLI

Enabling the debug crypto error command displays only error-related debug messages, thereby, allowing you to easily determine why a crypto operation, such as an IKE negotiation, has failed within your system.

Note When enabling this command, ensure that global crypto debug commands are not enabled; otherwise, the global commands will override any possible error-related debug messages.

SUMMARY STEPS

1. enable

2. debug crypto {isakmp | ipsec | engine} error

DETAILED STEPS

 
Command or Action
Purpose

Step 1 

enable

Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2 

debug crypto {isakmp | ipsec | engine} error

Example:

Router# debug crypto ipsec error

Enables only error debugging messages for a crypto area.

Configuration Examples for the Crypto Conditional Debug CLIs

This section includes the following examples:

•Enabling Crypto Conditional Debugging: Example

•Disabling Crypto Conditional Debugging: Example

Enabling Crypto Conditional Debugging: Example

The following example shows how to display debug messages when the peer IP address is 10.1.1.1, 10.1.1.2, or 10.1.1.3, and when the connection-ID 2000 of crypto engine 0 is used. This example also shows how to enable global debug crypto CLIs and enable the show crypto debug-condition command to verify conditional settings. 

Router# debug crypto condition connid 2000 engine-id 1

Router# debug crypto condition peer ipv4 10.1.1.1

Router# debug crypto condition peer ipv4 10.1.1.2

Router# debug crypto condition peer ipv4 10.1.1.3

Router# debug crypto condition unmatched 

! Verify crypto conditional settings.

Router# show crypto debug-condition


Crypto conditional debug currently is turned ON

IKE debug context unmatched flag:ON

IPsec debug context unmatched flag:ON

Crypto Engine debug context unmatched flag:ON


IKE peer IP address filters:

10.1.1.1  10.1.1.2   10.1.1.3


Connection-id filters:[connid:engine_id]2000:1,

! Enable global crypto CLIs to start conditional debugging.

Router# debug crypto isakmp

Router# debug crypto ipsec

Router# debug crypto engine

Disabling Crypto Conditional Debugging: Example

The following example shows how to disable all crypto conditional settings and verify that those settings have been disabled: 

Router# debug crypto condition reset

! Verify that all crypto conditional settings have been disabled.

Router# show crypto debug-condition


Crypto conditional debug currently is turned OFF

IKE debug context unmatched flag:OFF

IPsec debug context unmatched flag:OFF

Crypto Engine debug context unmatched flag:OFF

Additional References

The following sections provide references to the Crypto Conditional Debug Support feature.

Related Documents

Related Topic
Document Title

IPSec and IKE configuration tasks

Cisco IOS Security Configuration Guide

IPSec and IKE commands

Cisco IOS Security Command Reference


Standards

Standards
Title

None

—


MIBs

MIBs
MIBs Link

None

To locate and download MIBs for selected platforms, Cisco IOS releases, and feature sets, use Cisco MIB Locator found at the following URL:

http://www.cisco.com/go/mibs


RFCs

RFCs
Title

None

—


Technical Assistance

Description
Link

Technical Assistance Center (TAC) home page, containing 30,000 pages of searchable technical content, including links to products, technologies, solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content.

http://www.cisco.com/public/support/tac/home.shtml


Command Reference

This section documents new commands. All other commands used with this feature are documented in the Cisco IOS Release 12.3 T command reference publications.

•debug crypto condition

•debug crypto condition unmatched

•debug crypto error

•show crypto debug-condition

debug crypto condition

To define conditional debug filters, use the debug crypto condition command in privileged EXEC mode. To disable conditional debugging, use the no form of this command.

debug crypto condition [connid integer engine-id integer] [flowid integer engine-id integer] [fvrf string] [ivrf string] [peer [group string] [hostname string] [ipv4 ipaddress] [subnet subnet mask] [username string]] [spi integer] reset]

no debug crypto condition [connid integer engine-id integer] [flowid integer engine-id integer] [fvrf string] [ivrf string] [peer [group string] [hostname string] [ipv4 ipaddress] [subnet subnet mask] [username string]] [spi integer]

Syntax Description

connid integer1

(Optional) Internet Key Exchange (IKE) and IP Security (IPSec) connection ID filter. Valid values range from 1 to 32766.

engine-id integer

(Optional) Crypto engine ID value, which can be retrieved via the show crypto isakmp sa detail command. Valid values are1, which represents software engines, and 2, which represents hardware engines.

flowid integer

(Optional) IPSec flow-ID filter. Valid values range from 1 to 32766.

fvrf string1

(Optional) Front-door virtual private network (VPN) routing and forwarding (FVRF) filter. The string argument must be the name string of an FVRF instance.

ivrf string1

(Optional) Inside VRF (FVRF) filter. The string argument must be the name string of an IVRF instance.

peer1

(Optional) IKE peer filter. At least one of the following keywords and arguments must be used:

•group string—Unity group name filter of the IKE peer.

•hostname string—Fully qualified domain name (FQDN) host name filter of the IKE peer.

•ipv4 ipaddress—IP address filter of the IKE peer.

•subnet subnet mask—Range of IKE peer IP addresses.

•username string—FQDN username filter of the IKE peer.

spi integer1

(Optional) Security policy index (SPI) filter. The integer must be a 32-bit unsigned integer.

reset

(Optional) Deletes all crypto debug filters.

Note It is suggested that you turn off all crypto global debugging before using this keyword; otherwise, your system may be flooded with debug messages.

1 Additional conditional filters (ipv4 address, subnet mask, username, hostname, group, connection-ID, flow-ID, SPI, FVRF, and IVRF) can be specified more than once by repeating the debug crypto condition command with any of the available filters.


Defaults

Crypto conditional debugging is not enabled.

Command Modes

Privileged EXEC

Command History

Release
Modification

12.3(2)T

This command was introduced.


Usage Guidelines

Before enabling the debug crypto condition command, you must decide what debug condition types (also known as debug filters) and values will be used. The volume of debug messages is dependent on the number of conditions you define.

Note Specifying numerous debug conditions may consume CPU cycles and have a negative effect on router performance.

To begin crypto conditional debugging, you must also enable at least one global crypto debug command—debug crypto isakmp, debug crypto ipsec, and debug crypto engine; otherwise, conditional debugging will not occur. This requirement helps to ensure that the performance of the router will not be impacted when conditional debugging is not being used.

Note Debug message filtering for hardware crypto engines is not supported.

Examples

The following example shows how to display debug messages when the peer IP address is 10.1.1.1, 10.1.1.2, or 10.1.1.3 and when the connection-ID 2000 of crypto engine 0 is used. This example also shows how to enable global debug crypto CLIs and enable the show crypto debug-condition command to verify conditional settings. 

Router# debug crypto condition connid 2000 engine-id 1

Router# debug crypto condition peer ipv4 10.1.1.1

Router# debug crypto condition peer ipv4 10.1.1.2

Router# debug crypto condition peer ipv4 10.1.1.3

Router# debug crypto condition unmatched 

! Verify crypto conditional settings.

Router# show crypto debug-condition


Crypto conditional debug currently is turned ON

IKE debug context unmatched flag:ON

IPsec debug context unmatched flag:ON

Crypto Engine debug context unmatched flag:ON


IKE peer IP address filters:

10.1.1.1  10.1.1.2   10.1.1.3


Connection-id filters:[connid:engine_id]2000:1,

! Enable global crypto CLIs to start conditional debugging.

Router# debug crypto isakmp

Router# debug crypto ipsec

Router# debug crypto engine

The following example show how to disable all crypto conditional settings via the reset keyword: 

Router# debug crypto condition reset

! Verify that all crypto conditional settings have been disabled.

Router# show crypto debug-condition


Crypto conditional debug currently is turned OFF

IKE debug context unmatched flag:OFF

IPsec debug context unmatched flag:OFF

Crypto Engine debug context unmatched flag:OFF

Related Commands

Command
Description

debug crypto condition unmatched

Displays crypto conditional debug messages when context information is unavailable to check against debug conditions.

show crypto debug-condition

Displays crypto debug conditions that have already been enabled in the router.

show crypto ipsec sa

Displays the settings used by current SAs.

show crypto isakmp sa

Displays all current IKE SAs at a peer.


debug crypto condition unmatched

To display crypto conditional debug messages when context information is unavailable to check against debug conditions, use the debug crypto condition unmatched command in privileged EXEC mode. To disable debugging, use the no form of this command.

debug crypto condition unmatched [isakmp | ipsec | engine]

no debug crypto condition unmatched [isakmp | ipsec | engine]

Syntax Description

isakmp | ipsec | engine

(Optional) One or more of these keywords can be enabled to display debug messages for the specified areas. If none of these keywords are entered, debug messages for all crypto areas will be shown.


Defaults

Debug messages that do not have context information to match any debug conditions (filters) will not be printed.

Command Modes

Privileged EXEC

Command History

Release
Modification

12.3(2)T

This command was introduced.


Usage Guidelines

After the debug crypto condition command has been enabled, you can use the debug crypto condition unmatched command to define whether the debug output is being printed when no context information is available in the code to check against the debug filters. For example, if the crypto engine's connection-ID is the filter that the debug conditions are being checked against, the debug crypto condition unmatched command displays debug messages in the early negotiation phase when a connection-ID is unavailable to check against debug conditions.

Examples

The following example shows how to enable debug messages for all crypto-related areas: 

Router# debug crypto condition unmatched

Related Commands

Command
Description

debug crypto condition

Defines conditional debug filters.

show crypto debug-condition

Displays crypto debug conditions that have already been enabled in the router.

show crypto ipsec sa

Displays the settings used by current SAs.

show crypto isakmp sa

Displays all current IKE SAs at a peer.


debug crypto error

To enable error debugging for a crypto area, use the debug crypto error command in privileged EXEC mode. To disable crypto error debugging, use the no form of this command.

debug crypto {isakmp | ipsec | engine} error

no debug crypto {isakmp | ipsec | engine} error

Syntax Description

isakmp

Debug messages are shown for Internet Key Exchange (IKE)-related error operations only.

ipsec

Debug messages are shown for IP Security (IPSec)-related error operations only.

engine

Debug messages are shown for crypto engine-related error operations only.


Defaults

Crypto error debugging is not enabled.

Command Modes

Privileged EXEC

Command History

Release
Modification

12.3(2)T

This command was introduced.


Usage Guidelines

The debug crypto error command will display only error-related debug messages; that is, an error debug will not be shown if the operation is functioning properly.

This command should be used when debug conditions cannot be determined; for example, enable this command when a random, small subset of IKE peers is failing negotiation.

Note The global crypto command-line interfaces (CLIs) (the debug crypto isakmp, debug crypto ipsec, and debug crypto engine commands) will override the debug crypto error command. Thus, this command should not be used in conjunction with the global CLIs because you may overwhelm the router.

Note Debug message filtering for crypto hardware engines is not supported.

Examples

The following example shows how to enable IPSec-related error messages: 

Router# debug crypto error ipsec error

show crypto debug-condition

To display crypto debug conditions that have already been enabled in the router, use the show crypto debug-condition command in privileged EXEC mode.

show crypto debug-condition {[peer] [connid] [spi] [fvrf] [ivrf] [unmatched]}

Syntax Description

peer

(Optional) Displays debug conditions related to the peer. Possible conditions can include peer IP address, subnet mask, host name, username, and group key.

connid

(Optional) Displays debug conditions related to the connection-ID.

spi

(Optional) Displays debug conditions related to the security parameter index (SPI).

fvrf

(Optional) Displays debug conditions related to the front-door virtual private network (VPN) routing and forwarding (FVRF) instance.

ivrf

(Optional) Displays debug conditions related to the inside VRF (IVRF) instance.

unmatched

(Optional) Displays debug messages related Internet Key Exchange (IKE), IP Security (IPSec), or the crypto engine, depending on what was specified via the debug crypto condition unmatched [isakmp | ipsec | engine] command.


Command Modes

Privileged EXEC

Command History

Release
Modification

12.3(2)T

This command was introduced.


Usage Guidelines

You can specify as many filter values as specified via the debug crypto condition command. (You cannot specify a filter value that you did not use in the debug crypto condition command.) If no keywords are specified, all configured crypto conditions will be shown.

Examples

The following example shows how to display debug messages when the peer IP address is 10.1.1.1, 10.1.1.2, or 10.1.1.3 and when the connection ID 2000 of crypto engine 0 is used. This example also shows how to enable global debug crypto CLIs and enable the show crypto debug-condition command to verify conditional settings. 

Router# debug crypto condition connid 2000 engine-id 1

Router# debug crypto condition peer ipv4 10.1.1.1

Router# debug crypto condition peer ipv4 10.1.1.2

Router# debug crypto condition peer ipv4 10.1.1.3

Router# debug crypto condition unmatched 

! Verify crypto conditional settings.

Router# show crypto debug-condition


Crypto conditional debug currently is turned ON

IKE debug context unmatched flag:ON

IPsec debug context unmatched flag:ON

Crypto Engine debug context unmatched flag:ON


IKE peer IP address filters:

10.1.1.1  10.1.1.2   10.1.1.3


Connection-id filters:[connid:engine_id]2000:1,

! Enable global crypto CLIs to start conditional debugging.

Router# debug crypto isakmp

Router# debug crypto ipsec

Router# debug crypto engine

The following example shows how to disable all crypto conditional settings via the reset keyword: 

Router# debug crypto condition reset

! Verify that all crypto conditional settings have been disabled.

Router# show crypto debug-condition


Crypto conditional debug currently is turned OFF

IKE debug context unmatched flag:OFF

IPsec debug context unmatched flag:OFF

Crypto Engine debug context unmatched flag:OFF

Related Commands

Command
Description

debug crypto condition

Defines conditional debug filters.

debug crypto condition unmatched

Displays crypto conditional debug messages when context information is unavailable to check against debug conditions.


Copyright © 2003 Cisco Systems, Inc. All rights reserved.