Table Of Contents
Creating Core Dumps
When a router crashes, it is sometimes useful to obtain a full copy of the memory image (called a core dump) to identify the cause of the crash. Core dumps are generally very useful to your technical support representative. Not all crash types will produce a core dump. The different crash types are discussed in more details in Appendix B, "Memory Maps."
Caution Use the commands discussed in this appendix only under the direction of a technical support representative. Creating a core dump while the router is functioning in a network can disrupt network operation.
Four basic ways exist for setting up the router to generate a core dump:
•Using Trivial File Transfer Protocol (TFTP)
•Using File Transfer Protocol (FTP)
•Using remote copy protocol (rcp)
•Using a Flash disk
If TFTP is used to dump the core file to the TFTP server, the router will dump only the first 16 MB of the core file. This is a limitation of most TFTP applications. Therefore, if your router's main memory is more than 16 MB, do not use TFTP.
The following is the router configuration needed for getting a core dump using TFTP:
exception dump a.b.c.d
Here, a.b.c.d is the IP address of the TFTP server.
The core dump is written to a file named hostname-core on the TFTP server, where hostname is the name of the router. You can change the name of the core file by adding the exception core-file filename configuration command.
Depending on the TFTP server application used, it may be necessary to create on the TFTP server the empty target file to which the router can write the core. Also make sure that you have enough memory on your TFTP server to hold the complete core dump.
To configure the router for core dump using FTP, use the following configuration commands:
ip ftp usename username
ip ftp password password
exception protocol ftp
exception dump a.b.c.d
Here, a.b.c.d is the IP address of the FTP server. If the username and password are not configured, the router will attempt anonymous FTP.
Remote copy protocol (rcp) can also be used to capture a core dump. Enabling rcp on a router will not be covered in this appendix. Refer to the Cisco IOS Software Configuration document for configuring rcp.
After rcp is enabled on the router, the following commands must be added to capture the core dump using rcp:
exception protocol rcp
exception dump a.b.c.d
Here, a.b.c.d is the IP address of the host enabled for rcp.
Using 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 good candidates for another means of capturing core dump. For information on the router platforms and IOS versions that support the Flash disk, refer to the Cisco IOS Release Notes.
The following is the router configuration command needed to set up a core dump using a Flash disk:
exception flash <procmem|iomem|all> <device_name[:partition_number]> <erase | no_erase>
The show flash all command will give you a list of devices that you can use for the exception flash command.
The configuration commands in this section may be used in addition to those described in the "Basic Setup" section.
During the debugging process, you can cause the router to create a core dump and reboot when certain memory size parameters are violated. The following exception memory commands are used to trigger a core dump:
exception memory minimum size
The previous code is used to define the minimum free memory pool size.
exception memory fragment size
The previous code is used to define the minimum size of contiguous block of memory in the free pool.
The value of size is in bytes and is checked every 60 seconds. If you enter a size that is greater than the free memory, and if the exception dump command has been configured, a core dump and router reload is generated after 60 seconds. If the exception dump command is not configured, the router reloads without generating a core dump.
In some cases, the technical support representative will request that debug sanity be enabled when setting up the core dump. This is a hidden command in most IOS releases, but it sometimes is necessary to debug memory corruption. With debug sanity, every buffer that is used in the system is sanity-checked when it is allocated and when it is freed.
The debug sanity command must be issued in privileged exec mode (enable mode) and involves some CPU utilization. However, it will not significantly affect the router's functionality.
Not all types of crash require debug sanity to be enabled. Use this command only when your technical support representative requires it.
To disable debug sanity, use the privileged exec command undebug sanity.
Testing the Core Dump Setup
When the router is configured for core dump, it may be useful to test whether the setup works.
The IOS provides a special command to test or trigger a core dump:
Use this command in privileged exec mode (enable mode). This command will cause a crash, and the content of the memory will be dumped accordingly. If it no core dump is generated, the whole setup and config must be reviewed.
Caution The write core command will have an impact on a production network. It will cause the router to crash and will prevent it from coming up before dumping the content of its memory. This might take some time, depending on the amount of DRAM present on the router. Use the command with utmost caution.