Creating Core Dumps

Introduction

This document explains the various options you can use to enable core dumps in Cisco IOS® software.

Note: Core dumps can be difficult to obtain. Only Cisco technical personnel who have access to source code and detailed memory maps must attempt to interpret core dumps. On many platforms, the use of the crashinfo feature can make core dumps unnecessary. Refer to Retrieving Information from the Crashinfo File for more information.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• Troubleshooting Router Crashes

Components Used

The information in this document is based on these software and hardware versions:

• Cisco IOS Software Version 12.0 and later

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.

Conventions

Refer to Cisco Technical Tips Conventions for more information on document conventions.

How to Create Core Dumps

When a router crashes, remember to obtain a copy of the entire memory contents of the router, which is known as a core dump. Your technical support representative use the core dump to identify the cause of the crash. The router writes the memory contents to the server before a reload. Not all crashes produce a core dump. For more details, refer to Types of Crashes.

Always capture the console logs when the router attempts to dump a core. Console logs provide information about the crash. In addition, the ROM Monitor (ROMMON) normally prints information to the console (and only to the console) at the time of the crash.

Caution: Core dumps are not necessary to solve most crash cases. Creation of a core dump while the router is functioning in a network can disrupt network operation. Use the commands in this document only under the direction of a technical support representative.

Basic Setup

There are four basic ways to set up the router to generate a core dump:

• Through File Transfer Protocol (FTP)

• Through Remote Copy Protocol (RCP)

• Through a Flash Disk

• Through Trivial File Transfer Protocol (TFTP)

Each of these methods uses these configuration commands:

• exception region-size size

  This command specifies the size of the region for the exception-time memory pool. The exception-time memory pool is used in case the process memory becomes corrupt. The size parameter is expressed in bytes and you can configure the size from 1024 to 65536 bytes.

• exception core-file filename [compress]

  This command specifies a name for the core dump file other then the default name. In order to revert to the default name, use the no form of this command.

For more information on the commands in this document, refer to the Command reference tool (registered customers only) .

Use the exception region-size command to define a small amount of memory to serve as a fallback pool when the processor memory pool becomes corrupt. This helps to prevent memory failures during the core dump process. The size parameter is expressed in bytes and you can configure the size from 1024 to 65536 bytes, with a default value of 16384 bytes. Configure the exception region-size as 65536 bytes to increase the chance of a successful core dump.

By default, the processor memory core dump is written to a file named "hostname-core", where hostname is the name of the router, which the hostname configuration command defines. If the router has Input/Output (I/O) memory (for example, the Cisco 7200), an I/O memory core dump can also be created, written to the file "hostname-coreiomem".

Use the exception core-file command to override the default core dump filename. If the file server has a DOS FAT file system, do not specify a file name longer than six characters. For example, if you configure a router with "exception core-file foobar", the processor memory name of the core dump is "foobar" and the name of the I/O memory dump is "foobario" (enough to give you a hint that you have an I/O memory dump).

Make sure there is enough disk space on the file server to hold multiple complete core dumps. You can compress core dump files with the compress option.

Note:  Compress applies automatically when you write core dump files to the Flash disk. If you use RCP, the compress option is not supported.

Use File Transfer Protocol

Note: File Transfer Protocol (FTP) is the recommended method to configure a core dump.

In order to use FTP to configure the router for a core dump, use these commands:

• ip ftp username username —This command configures the username for File Transfer Protocol (FTP) connections. In order to configure the router to attempt anonymous FTP, use the no form of this command.

• ip ftp password password —This command configures the password for the FTP connection.

• exception protocol ftp—This command configures the protocol used for core dump FTP.

• exception region-size 65536 —This command configures the region size.

• exception dump ip-address —This command configures the ip address of the server to which the router sends the core dump in case of a crash.

Note: In order to avoid network congestion, Cisco highly recommends that you connect the router directly to the FTP server, with no intermediate hops. If you must go through one or more intermediate hops, you may need to use the ip ftp source-interface command to specify which interface to use in order to access the FTP server. Refer to Configuring a Router to Use FTP Connections for more information.

If you have no configured the username and password, the router attempts anonymous FTP.

When a Cisco technical support representative requests you for core dump files, you can send the core dump files to Cisco through anonymous FTP. The FTP server is ftp-sj.cisco.com and the directory is /incoming.

Note: The /incoming directory is invisible.

Make sure to set the transfer mode to binary. If the files are not already compressed, compress them with a common compression utility, for example, gzip or zip.

Also make sure to include the crashinfo file, if available, along with the core dump. The crashinfo file is available if the hardware or software supports this feature. Refer to Retrieving Information from the Crashinfo File for instructions on how to do this.

Make sure that FTP works first. Use this example:

c7500#copy running-config ftp: 
Address or name of remote host []? 172.18.125.3 
Destination filename [c7500-confg]? 
Writing c7500-confg ! 
2781 bytes copied in 0.944 secs 

Use Remote Copy Protocol

In order to use RCP to configure the router for a core dump, use these commands:

• ip rcmd remote-username username –This command configures the remote username for use when you request a remote copy through remote copy protocol (RCP).

• exception protocol rcp—This command configures the protocol used for core dumps as RCP.

• exception region-size 65536 —This command configures the region size.

• exception dump ip-address

If you have not configured the username, the router uses its hostname as the username for RCP.

Note: In order to avoid network congestion, Cisco highly recommends that you connect the router directly to the RCP server, with no intermediate hops. If you must go through one or more intermediate hops, use the ip rcmd source-interface command to specify which interface to use in order to access the RCP server. Refer to Configuring a Router to Use rsh and rcp for more information.

Make sure that RCP works first. Use this example:

c7500#copy running-config rcp: 
Address or name of remote host []? 172.18.125.3 
Destination username [c7500]? 
Destination filename [c7500-confg]? 
Writing c7500-confg ! 
2781 bytes copied in 0.944 secs 

Use a Flash Disk

Some router platforms support the Flash disk as an alternative to the linear Flash memory or PCMCIA Flash card. The large storage capacity of these Flash disks makes them a good medium to capture a core dump. For information on the router platforms and Cisco IOS software versions that support the Flash disk, refer to the Cisco IOS Release Notes .

Note: When you capture a core dump in a Flash disk, you must ensure that the Flash disk has more storage size than the DRAM memory that causes the core dump. For example, if you have a DRAM memory size of 128 MB, the Flash disk must have a storage capacity of more than 128MB. A larger flash disk memory is necessary to get the core dump correctly. If there is a memory shortage on the Flash disk, the core dump is not created.

In order to use a Flash disk to configure a router for a core dump, use this command:

exception flash procmem|iomem|all device_name [:partition_number] 

!--- This command uses a Flash disk to configure the router for a core dump.

The show flash all EXEC command lists the devices you can use for the exception flash command.

Use Trivial File Transfer Protocol

Due to a limitation of most TFTP applications, the router only dumps the first 16 MB of the core file. Therefore, if the main memory of your router is larger than 16 MB, do not use TFTP. Refer to Cisco IOS TFTP Client Cannot Transfer Files Larger than 16MB in Size for more information.

In order to use TFTP to configure a router for a core dump, use these commands:

• exception protocol tftp—This command configures TFTP as the protocol for core dumps.

• exception region-size 65536

• exception dump ip-address

TFTP is the default protocol for exception protocol.

Note: In order to avoid network congestion, Cisco highly recommends that you connect the router directly to the TFTP server, with no intermediate hops. If you must go through one or more intermediate hops, use the ip tftp source-interface command to specify which interface to use in order to access the TFTP server.

On the basis of the TFTP server used, you may need to create empty target file(s) with the appropriate permissions before the router can write to them.

Make sure that TFTP works first. Use this example:

c7500#copy running-config tftp: 
Address or name of remote host []? 172.18.125.3 
Destination filename [c7500-confg]? 
! 
2781 bytes copied in 0.944 secs 

Advanced Setup

Use the configuration commands in this section in addition to the commands in the Basic Setup section.

Exception Memory

In order to debug some memory problems, you can cause the router to create a core dump, and reboot in the event of violation of certain memory size parameters. Use these exception memory commands in order to trigger a core dump:

• exception memory minimum size —This command forces a crash if the amount of free processor memory shrinks below the configured threshold.

• exception memory fragment size —This command forces a crash if the Cisco IOS software cannot allocate a contiguous processor memory block larger than the configured threshold.

The size parameter is expressed in bytes, and is checked every 60 seconds by default.

These commands only cause the router to reboot when the configured conditions are met. If you also configure exception dump or exception flash, the router creates a core dump first. These commands help to diagnose memory leaks.

Debug Sanity

In some cases, the technical support representative requests you to enable debug sanity when you configure the core dump. The debug sanity command is a hidden command in most Cisco IOS software releases, and is sometimes necessary to debug memory corruption, especially I/O memory corruption. When you enable debug sanity, the system runs a sanity-check on every buffer that is allocated, and runs a sanity-check again when the buffer is freed.

You must issue the debug sanity command in privileged EXEC mode (or enable mode). Although this command uses some CPU capacity, debug sanity does not significantly affect the functionality of the router. Like other debug commands, debug sanity is not saved in the configuration and thus does not survive a reboot of the system.

Not all types of crashes require you to enable debug sanity. Use debug sanity only when your technical support representative requests you to enable this command.

In order to disable sanity-checks, use the undebug sanity privileged EXEC command.

Test the Core Dump Setup

When you have configured the router for core dump, test the setup.

Cisco IOS software provides the special write core command in privileged EXEC mode (or enable mode) to cause the router to generate a core dump without a reload.

If successful, the core dump file(s) are the size of the the respective memory regions. Remember that the entire memory region is dumped, not just the memory that is in use.

The write core command is also useful in case of a router that malfunctions, but has not crashed.

Related Information

• Configuring a Core Dump on a GSR Line Card
• Troubleshooting Router Crashes
• Troubleshooting Router Hangs
• Troubleshooting Memory Problems
• Routers Product Support
• Technical Support & Documentation - Cisco Systems