Cisco IOS Configuration Fundamentals and Network Management Command Reference, Release 12.3
CFR Commands: clock update-calendar -- escape-character

Table Of Contents

clock update-calendar

cns config cancel

cns config connect-intf

cns config initial

cns config notify

cns config partial

cns config retrieve

cns connect

cns event

cns exec

cns id

cns image

cns image password

cns image retrieve

cns image retry

cns inventory

cns mib-access encapsulation

cns notifications encapsulation

cns template connect

cns trusted-server

config-cli

config-register

configure memory

configure network

configure overwrite-network

configure terminal

confreg

continue

copy

copy erase flash

copy verify bootflash

copy verify flash

copy verify

crypto mib topn

databits

data-character-bits

data-pattern

default-value exec-character-bits

default-value special-character-bits

delete

diag

dir

disable

disconnect-character

discover (cns)

dispatch-character

dispatch-machine

dispatch-timeout

distributions-of-statistics-kept

do

downward-compatible-config

editing

enable

end

enhanced-history

erase

erase bootflash

escape-character


clock update-calendar

To perform a one-time update of the hardware clock (calendar) from the software clock, use the clock update-calendar command in user EXEC or privileged EXEC mode.

clock update-calendar

Syntax Description

This command has no arguments or keywords.

Command Modes

User EXEC

Privileged EXEC

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Some platforms have a hardware clock (calendar) in addition to a software clock. The hardware clock is battery operated, and runs continuously, even if the router is powered off or rebooted.

If the software clock and hardware clock are not synchronized, and the software clock is more accurate, use this command to update the hardware clock to the correct date and time.

Examples

The following example copies the current date and time from the software clock to the hardware clock:

Router> clock update-calendar

Related Commands

Command
Description

clock read-calendar

Performs a one-time update of the software clock from the hardware clock (calendar).

ntp update-calendar

Periodically updates the hardware clock from the software clock.


cns config cancel

To remove a partial Cisco Networking Services (CNS) configuration from the list of outstanding partial configurations, use the cns config cancel command in EXEC mode.

cns config cancel queue-id

Syntax Description

queue-id

Indicates which partial configuration in the list of outstanding partial configurations to remove from the list. This list can be displayed by issuing the show cns config outstanding command in EXEC mode.


Defaults

No default behavior or values.

Command Modes

Privileged EXEC

Command History

Release
Modification

12.2(2)T

This command was introduced.

12.0(18)ST

This command was integrated into Cisco IOS Release 12.0 ST.

12.0(22)S

This command was integrated into Cisco IOS Release 12.0 S.

12.2(8)T

This command was implemented on additional platforms.


Usage Guidelines

Incremental (partial) configurations take place in two steps:

1. The configuration agent receives the partial configuration. It checks the configuration commands for syntax, publishes the success or failure of the read and syntax-check operation to the sync-status subject "cisco.cns.config.sync-status," and stores the configuration.

2. The configuration agent receives a second event message directing it to either apply or cancel the stored configuration.

Use the cns config cancel command in error scenarios where the second event message is not received and you need to remove the configuration from the list of outstanding configurations. Currently the maximum number of outstanding configurations is one.

Examples

The following example shows the process of checking the existing outstanding CNS configurations and cancelling the configuration with the queue-id of 1:

Router# show cns config outstanding
The outstanding configuration information:
queue id   identifier       config-id
1          identifierREAD   config_idREAD

Router# cns config cancel 1

Router# show cns config outstanding
The outstanding configuration information:
queue id   identifier       config-id

Related Commands

Command
Description

cns config partial

Starts the CNS configuration agent, which provides CNS configuration services to Cisco IOS clients.

cns event

Configures the CNS event gateway, which provides CNS event services to Cisco IOS clients.

show cns event connections

Displays the status of the CNS event agent connection.

show cns config outstanding

Displays information about incremental CNS configurations that have started but not yet completed.


cns config connect-intf


Note Effective with Cisco IOS Releases 12.3(8)T and 12.3(9), the cns config connect-intf command is replaced by the cns connect and cns template connect commands. See the cns connect and cns template connect commands for more information.


To specify the interface for connecting to the Cisco Networking Services (CNS) configuration engine, use the cns config connect-intf command in global configuration mode. To disable this interface for the connection, use the no form of this command.

cns config connect-intf type number [ping-interval seconds] [retries number]

no cns config connect-intf type number

Syntax Description

type number

Interface type and number for the connecting interface.

ping-interval seconds

(Optional) Interval between successive ping attempts. Values are from 1 to 30 seconds. The default is 10 seconds.

retries number

(Optional) Number of times that a ping will be retried. Values are from 1 to 30 seconds. The default is 5 seconds.


Defaults

The ping interval defaults to 10 seconds.

The number of retries defaults to 5.

Command Modes

Global configuration

Command History

Release
Modification

12.2(8)T

This command was introduced.

12.3(8)T

This command was replaced by the cns connect and cns template connect commands.

12.3(9)

This command was replaced by the cns connect and cns template connect commands.


Usage Guidelines

Use this command to connect to the CNS configuration engine using a specific type of interface. You must specify the interface type but need not specify the interface number; the router's bootstrap configuration finds the connecting interface, regardless of the slot in which the card resides or the modem dialout line for the connection, by trying different candidate interfaces or lines until it successfully pings the registrar.

Use this command to enter CSN Connect-interface configuration mode (config-cns-conn-if). Then use one of the following bootstrap-configuration commands to connect to the registrar for initial configuration:

config-cli followed by commands that, used as is, configure the interface.

line-cli followed by a command to configure modem lines to enable dialout and, after that, commands to configure the modem dialout line.

The config-cli command accepts the special directive character "&," which acts as a placeholder for the interface name. When the configuration is applied, the & is replaced with the interface name. Thus, for example, if we are able to connect using FastEthernet0/0, the config-cli ip route 0.0.0.0 0.0.0.0 & command generates the ip route 0.0.0.0 0.0.0.0 FastEthernet0/0 command. Similarly, the config-virtual terminal line (vty) cns id & ipaddress command generates the cns id FastEthernet0/0 ipaddress command.

Examples

In the following example, the user connects to a configuration engine using the asynchronous interface and issues a number of commands:

Router(config)# cns config connect-intf Async
Router(config-cns-conn-if)# config-cli encapsulation ppp
Router(config-cns-conn-if)# config-cli ip unnumbered FastEthernet0/0
Router(config-cns-conn-if)# config-cli dialer rotary-group 0
Router(config-cns-conn-if)# line-cli modem InOut
Router(config-cns-conn-if)# line-cli
.
.
.
Router(config-cns-conn-if)# exit

These commands result in the following configuration being applied:

line 65
modem InOut
.
.
.
interface Async65
encapsulation ppp
dialer in-band
dialer rotary-group 0

Related Commands

Command
Description

cns config cancel

Cancels an incremental two-phase synchronization configuration.

cns config initial

Starts the CNS configuration agent and initiates an initial configuration.

cns config notify

Detects CNS configuration changes and sends an event containing the previous and current configuration.

cns config partial

Starts the CNS configuration agent, which provides CNS configuration services to Cisco IOS clients.


cns config initial

To enable the CNS configuration agent and initiate a download of the initial configuration, use the cns config initial command in global configuration mode. To remove an existing cns config initial command from the running configuration of the routing device, use the no form of this command.

cns config initial {ip-address | host-name} [encrypt] [port-number] [page page] [syntax-check] [no-persist] [source ip-address] [event] [inventory]

no cns config initial

Syntax Description

ip-address

IP address of the configuration server.

host-name

Host name of the configuration server.

encrypt

(Optional) Uses a Secure Socket Layer (SSL) encrypted link to the event gateway.

port-number

(Optional) Port number of the configuration service. The value is from 0 to 65535. The default is 80 with no encryption and 443 with encryption.

page page

(Optional) Web page where the configuration is located. The default is /cns/config.asp.

syntax-check

(Optional) Turns on syntax checking.

no-persist

(Optional) Suppresses the default automatic writing to NVRAM of the configuration pulled as a result of issuing the cns config initial command. If not present, issuing the cns config initial command causes the resultant configuration to be automatically written to NVRAM.

source ip-address

(Optional) IP address to use as the source of CNS communications.

event

(Optional) Sends an event to the Event Bus notifying successful completion of the configuration or warning that the configuration contained errors. If the CNS event agent is not configured, the event will be saved until the CNS event agent is enabled. If the event keyword is not specified, a log message is sent to the console of the device after the configuration is complete.

inventory

(Optional) Sends an inventory of the line cards and modules in the router to the CNS configuration engine as part of the HTTP request.


Defaults

The port number defaults to 80 with no encryption and 443 with encryption.
Default web page of the initial configuration is /cns/config.asp.

Command Modes

Global configuration

Command History

Release
Modification

12.2(2)T

This command was introduced.

12.0(18)ST

This command was integrated into Cisco IOS Release 12.0(18)ST.

12.0(22)S

This command was integrated into Cisco IOS Release 12.0(22)S.

12.2(2)XB

This command was implemented on Cisco IAD2420 series Integrated Access Devices (IADs).

12.2(8)T

The source and encrypt keywords were added.

12.3(1)

The inventory keyword was added.


Usage Guidelines

Use this command when a basic configuration—called a bootstrap configuration—is added to multiple routers before being deployed. When a router is initially powered (or each time a router is reloaded when the no-persist keyword is used) the cns config initial command will cause a configuration file—called an initial configuration—for the router to be downloaded from the configuration server. The initial configuration can be unique for each router.

When the configuration has been received by the router, each line of the configuration will be applied in the same order as it was received. If the Cisco IOS parser has an error with one of the lines of the configuration, then all the configuration up to this point will be applied to the router, but none of the configuration beyond the error will be applied. If an error occurs, the command will retry until it successfully completes. Once the configuration has successfully completed the cns config initial command will be removed from the running configuration. By default, NVRAM will be updated except when the no-persist keyword is configured.

When this command is used with the event keyword, a single message will be published on the event bus after the configuration is complete. The event bus will display one of the following status messages:

cisco.mgmt.cns.config.complete—CNS configuration agent successfully applied the initial configuration.

cisco.mgmt.cns.config.warning—CNS configuration agent fully applied the initial configuration, but encountered possible semantic errors.

Examples

The following example shows how to enable the CNS configuration agent and initiate an initial configuration:

Router# cns config initial 10.19.4.5 page /cns/config/first.asp

Related Commands

Command
Description

cns config connect-intf

Specifies the interface for connecting to the CNS configuration engine.

cns config notify

Detects CNS configuration changes and sends an event containing the previous and current configuration.

cns config retrieve

Returns the configuration of a routing device if the CNS configuration agent is enabled and the partial configuration is complete.

cns event

Configures the CNS event gateway, which provides CNS event services to Cisco IOS clients.

show cns config status

Displays information about the status of the CNS configuration agent.


cns config notify

To notify CNS agents of configuration changes on Cisco IOS devices, use the cns config notify command in global configuration mode. To disable notifications, use the no form of this command.

cns config notify {all | diff} [interval minutes] [no_cns_events] [old-format]

no cns config notify {all | diff} [interval minutes] [no-cns-events] [old-format]

Syntax Description

all

Captures all configuration commands for the config-changed event output.

diff

Captures commands that change configuration for the config-changed event output.

interval minutes

(Optional) Specifies the amount of time after the last configuration change that the config-changed event is sent. The default is 5 minutes. The timer starts when you make a configuration change and you remain in configuration mode after the configuration change. If you enter the end command, the config-changed event is sent immediately.

no_cns_events

(Optional) Disables event notification for configurations changed through an XML file. If the configuration is changed using the command-line interface (CLI), the config-changed event will be sent.

old-format

(Optional) Provides the event notification in the old XML format for backwards compatibility.


Defaults

The interval defaults to 5 minutes.

Command Modes

Global configuration

Command History

Release
Modification

12.2(8)T

This command was introduced.

12.2(11)T

The diff keyword was removed.

12.3(1)

The diff and old-format keywords were added.


Usage Guidelines

When the cns config notify command is enabled, commands entered in configuration mode are detected. If the all keyword is specified, the command is stored for future notification. If the diff keyword is specified, the command is stored for future notification if the software determines that the command will cause a configuration change. The diff keyword also allows the software to store information about the command including previous configuration states, source of the change (for example, a telnet user), and the time of configuration.

The stored information is formatted in XML and sent as part of a CNS config agent change notification event. A CNS config agent change notification event is sent to the CNS Event Bus when configuration mode is exited or no activity from that source has occurred for the configured interval time.

You must enable the CNS event agent using the cns event command before configuring this command. If the CNS event agent is not configured, the notification event will be queued and sent when the CNS event agent is enabled. If the CNS config notify queue is full, subsequent events are dropped and a "lost" CNS config change notification is sent when the CNS event agent is enabled.

Use the no_cns_events for applications that already record configuration changes sent to the routing device through the CNS Event Bus.

Use the old-format keyword to generate XML output—only the entered command and previous configuration state—that is compatible with the versions of this commands when the diff keyword was removed.

Examples

The following example detects configuration changes for all configuration commands:

Router(config)# cns config notify all

Related Commands

Command
Description

cns config cancel

Cancels an incremental two-phase synchronization configuration.

cns config connect-intf

Specifies the interface for connecting to the CNS configuration engine.

cns config initial

Starts the CNS configuration agent and initiates an initial configuration.

cns config partial

Starts the CNS configuration agent, which provides CNS configuration services to Cisco IOS clients.

cns event

Enables and configures CNS event agent services.


cns config partial

To start the CNS configuration agent and accept a partial configuration, use the cns config partial command in global configuration mode. To shut down the CNS partial configuration agent, use the no form of this command.

cns config partial {ip-address | host-name} [encrypt] [port-number] [source ip-address] [inventory]

no cns config partial

Syntax Description

ip-address

IP address of the configuration server.

host-name

Host name of the configuration server.

encrypt

(Optional) Uses a Secure Socket Layer (SSL) encrypted link between the router and the web server.

port-number

(Optional) Port number of the configuration service. The value is from 0 to 65535. The default is 80 with no encryption and 443 with encryption.

source ip-address

(Optional) IP address to use for source of this device.

inventory

(Optional) Sends an inventory of the line cards and modules in the router to the CNS configuration engine as part of the HTTP request.


Defaults

The port number defaults to 80 with no encryption and 443 with encryption.

Command Modes

Global configuration

Command History

Release
Modification

12.2(2)T

This command was introduced.

12.0(18)ST

This command was integrated into Cisco IOS Release 12.0(18)ST.

12.0(22)S

This command was integrated into Cisco IOS Release 12.0(22)S.

12.2(2)XB

This command was implemented on Cisco IAD2420 series Integrated Access Devices (IADs).

12.2(8)T

The source and encrypt keywords were added.

12.3(1)

The inventory keyword was added.


Usage Guidelines

Use this command to start the CNS partial configuration agent. You must enable the CNS event agent using the cns event command before configuring this command. The CNS event agent sends an event with the subject "cisco.mgmt.cns.config.load" to specify whether configuration data can be pushed to the CNS partial configuration agent or pulled from a configuration server by the CNS partial configuration agent.

In the push model, the event message delivers the configuration data to the partial configuration agent.

In the pull model, the event message triggers the partial configuration agent to pull the configuration data from the CNS configuration engine. The event message contains information about the CNS configuration engine, not the actual configuration data. The host name or IP address is the address of the CNS configuration engine from which the configuration is pulled. Use the cns trusted-server command to specify which CNS configuration engines can be used by the CNS partial configuration agent.

When the configuration has been received by the router, each line of the configuration will be applied in the same order as it was received. If the IOS parser has an error with one of the lines of the configuration, then all the configuration up to this point will be applied to the router, but none of the configuration beyond the error will be applied. If an error occurs, the command will retry until it successfully completes. In the pull mode, the command will not retry after an error. By default, NVRAM will be updated except when the no-persist keyword is configured.

A single message will be published on the CNS Event Bus after the partial configuration is complete. The CNS Event Bus will display one of the following status messages:

cisco.mgmt.cns.config.complete—CNS configuration agent successfully applied the partial configuration.

cisco.mgmt.cns.config.warning—CNS configuration agent fully applied the partial configuration, but encountered possible semantic errors.

cisco.mgmt.cns.config.failure—CNS configuration agent encountered an error and was not able to apply the configuration.

Examples

The following example shows how to configure the CNS partial configuration agent to accept events from the event gateway at 172.28.129.22. The CNS partial configuration agent will connect to the CNS configuration server at 172.28.129.22, port number 80. The CNS partial configuration agent requests are redirected to a configuration server at 172.28.129.40, port number 80.

Router(config)# cns event 172.28.129.22
Router(config)# cns trusted-server config 172.28.129.40
Router(config)# cns config partial 172.28.129.22

Related Commands

Command
Description

cns config initial

Starts the CNS configuration agent and initiates an initial configuration.

cns event

Enables and configures CNS event agent services.

cns trusted-server

Specifies a trusted server for CNS agents.

show cns config outstanding

Displays information about incremental CNS configurations that have started but are not yet completed.


cns config retrieve

To request the configuration of a routing device, use the cns config retrieve command in EXEC mode.

cns config retrieve {ip-address | host-name} [encrypt] [port-number] [page page] [overwrite-startup] [syntax-check] [no-persist] [source ip-address] [event] [inventory]

Syntax Description

ip-address

IP address of the configuration server.

host-name

Host name of the configuration server.

encrypt

(Optional) Uses a Secure Socket Layer (SSL) encrypted link to the event gateway.

port-number

(Optional) Port number of the configuration service. The value is from 0 to 65535. The default is 80 with no encryption and 443 with encryption.

page page

(Optional) Web page where the configuration is located. The default is /cns/config.asp.

overwrite-startup

(Optional) Replaces the startup configuration file. Does not apply to the running configuration file.

syntax-check

(Optional) Turns on syntax checking.

no-persist

(Optional) Suppresses the default automatic writing to NVRAM of the configuration pulled as a result of issuing the cns config retrieve command. If not present, issuing the cns config retrieve command causes the resultant configuration to be automatically written to NVRAM.

source ip-address

(Optional) IP address to use as the source of CNS communications.

event

(Optional) Sends an event to the CNS Event Bus stating successful completion of the configuration, a warning that the configuration contained errors, or a message noting that the configuration failed. If the CNS event agent is not configured, the event will be saved until the CNS event agent is enabled. If the event keyword is not specified, a log message is sent to the console of the device after the configuration is complete.

inventory

(Optional) Sends an inventory of the line cards and modules in the router to the CNS configuration engine as part of the HTTP request.


Defaults

The port number defaults to 80 with no encryption and 443 with encryption.
Default web page of the initial configuration is /cns/config.asp.

Command Modes

EXEC

Command History

Release
Modification

12.2(2)T

This command was introduced.

12.0(18)ST

This command was integrated into Cisco IOS Release 12.0(18)ST.

12.0(22)S

This command was integrated into Cisco IOS Release 12.0(22)S.

12.3(1)

The inventory keyword was added.


Usage Guidelines

Use this command to request the configuration of a device from a configuration server. Use the cns trusted-server command to specify which configuration server can be used (trusted).

When the configuration has been received by the router, each line of the configuration will be applied in the same order as it was received. If the IOS parser has an error with one of the lines of the configuration, then all the configuration up to this point will be applied to the router, but none of the configuration beyond the error will be applied. If an error occurs, the command will not retry.

A single message will be published on the event bus after the partial configuration is complete. The event bus will display one of the following status messages:

cisco.mgmt.cns.config.complete—CNS configuration agent successfully applied the configuration.

cisco.mgmt.cns.config.warning—CNS configuration agent fully applied the configuration, but encountered possible semantic errors.

cisco.mgmt.cns.config.failure—CNS configuration agent encountered an error and was not able to apply the configuration.

The cns config retrieve command can be used with Command Scheduler commands (for example, kron policy-list and cli commands) in environments where it is not practical to use the CNS event agent and the cns config partial command. Configured within the cli command, the cns config retrieve command can be used to poll the configuration server to detect configuration changes.

Examples

The following example shows how to request a configuration from a trusted server at 10.1.1.1:

Router(config)# cns trusted-server all 10.1.1.1
Router(config)# cns config retrieve 10.1.1.1

Related Commands

Command
Description

cli

Specifies EXEC CLI commands within a Command Scheduler policy list.

cns config initial

Starts the CNS configuration agent and initiates an initial configuration.

cns trusted-server

Specifies a trusted server for CNS agents.

kron policy-list

Specifies a name for a Command Scheduler policy and enters kron-policy configuration mode.

show cns config status

Displays information about the status of the CNS configuration agent.


cns connect

To enter Cisco Networking Services (CNS) connect configuration mode and define the parameters of a CNS connect profile for connecting to the CNS configuration engine, use the cns connect command in global configuration mode. To disable the CNS connect profile, use the no form of this command.

cns connect name [ping-interval interval-seconds] [retries number-retries] [timeout timeout-seconds] [sleep sleep-seconds]

no cns connect name [ping-interval interval-seconds] [retries number-retries] [timeout timeout-seconds] [sleep sleep-seconds]

Syntax Description

name

The name of the CNS connect profile to be configured.

ping-interval interval-seconds

(Optional) Sets the interval (in seconds) between each successive attempt to ping the CNS configuration engine. The default value is 10 seconds.

retries number-retries

(Optional) Sets the number of times the CNS connect function will try to ping the CNS configuration engine. The default value is 3.

timeout timeout-seconds

(Optional) Sets the amount of time (in seconds) after which an interface is no longer used for ping attempts. The default value is 120 seconds.

sleep sleep-seconds

(Optional) Sets the amount of time (in seconds) before which the first ping is attempted for each interface. This option provides time for the far end of a link to stabilize. The default value is 0 seconds.


Defaults

No CNS connect profiles are defined.

Command Modes

Global configuration

Command History

Release
Modification

12.3(2)XF

This command was introduced.

12.3(8)T

This command was integrated into Cisco IOS Release 12.3(8)T.

12.3(9)

This command was integrated into Cisco IOS Release 12.3(9).


Usage Guidelines

Use the cns connect command to enter CNS connect configuration mode and define the parameters of a CNS connect profile for connecting to the CNS configuration engine. Then use the following CNS connect commands to create a CNS connect profile:

discover

template

A CNS connect profile specifies the discover commands and associated template commands that are to be applied to a router's configuration. When multiple discover and template commands are configured in a CNS connect profile, they are processed in the order in which they are entered.


Note Effective with Cisco IOS Releases 12.3(8)T and 12.3(9), the cns config connect-intf command is replaced by the cns connect and cns template connect commands.


Examples

The following example shows how to create a CNS connect profile named profile-1:

Router (config)# cns connect profile-1
Router (config-cns-conn)# discover interface Serial
Router (config-cns-conn)# template template-1
Router (config-cns-conn)# exit
Router (config)#

In this example, the following sequence of events occurs for each serial interface when the cns connect profile-1 command is processed:

1. Enter interface configuration mode and apply all commands in the template-1 template to the router's configuration.

2. Try to ping the CNS configuration engine.

3. If the ping is successful, then download pertinent configuration information from the CNS configuration engine and exit. The cns connect profile-1 command has completed its process.

4. If the ping is unsuccessful, enter interface configuration mode and remove all commands in the template-1 template from the router's configuration. The cns connect profile-1 command has failed to retrieve any configuration information from the CNS configuration engine.

Related Commands

Command
Description

cli (cns)

Specifies the command lines of a CNS connect template.

cns template connect

Enters CNS template connect configuration mode and defines the name of a CNS connect template.

discover (cns)

Defines the interface parameters within a CNS connect profile for connecting to the CNS configuration engine.

template (cns)

Specifies a list of CNS connect templates within a CNS connect profile to be applied to a router's configuration.


cns event

To configure the Cisco Networking Services (CNS) event gateway, which provides CNS event services to Cisco IOS clients, use the cns event command in global configuration mode. To remove the specified event gateway from the gateway list, use the no form of this command.

cns event {host-name | ip-address} [port-number] [encrypt] [backup] [failover-time seconds] [keepalive seconds retry-count] [source ip-address] [clock-timeout time] [reconnect time]

no cns event {host-name | ip-address} [port-number] [encrypt] [backup] [failover-time seconds] [keepalive seconds retry-count] [source ip-address] [clock-timeout time] [reconnect time]

Syntax Description

host-name

Hostname of the event gateway.

ip-address

IP address of the event gateway.

port-number

(Optional) Port number for the event gateway. The default is 11011 with no encryption or 11012 with encryption.

encrypt

(Optional) Uses a Secure Sockets Layer (SSL) encrypted link to the event gateway.

backup

(Optional) Indicates a backup gateway. If omitted, indicates the primary gateway. A primary gateway must be configured before you can configure a backup gateway. Optional keywords, if omitted, are set as for the primary gateway.

failover-time seconds

(Optional) Specifies a time interval, in seconds, to wait for the primary gateway route after the route to the backup gateway is established. The default is 3.

keepalive seconds retry-count

(Optional) Specifies a keepalive timeout, in seconds, and retry count.

source ip-address

(Optional) Indicates the IP address of the source for CNS communications.

clock-timeout time

(Optional) Specifies the maximum time, in minutes, that the CNS event agent will wait for the clock to be set for transports (such as SSL) that require an accurate clock. The default is 10 minutes.

reconnect time

(Optional) Specifies the configurable upper limit of the maximum retry timeout. The valid range is 1 through 65535. The default is 3600.


Command Default

The event gateway default port number is 11011 with no encryption or 11012 with encryption.
The default number of seconds to wait for a primary gateway route is 3.
The clock timeout default is 10 minutes.
The reconnection time default is 3600 seconds.

Command Modes

Global configuration

Command History

Release
Modification

12.2(2)T

This command was introduced.

12.0(18)ST

This command was integrated into the Cisco IOS Release 12.0(18)ST.

12.0(22)S

This command was integrated into Cisco IOS Release 12.0(22)S.

12.2(2)XB

This command was implemented on Cisco IAD2420 series Integrated Access Devices (IADs).

12.2(8)T

The encrypt, init-retry, source, and force-fmt1 keywords were added.

12.3

The reconnect-time keyword was added.

12.3(1)

The init-retry keyword was replaced with the failover-time keyword. The force-fmt1 keyword was removed. The clock-timeout keyword was added.


Usage Guidelines

The CNS event agent must be enabled before any of the other CNS agents are configured because the CNS event agent provides a transport connection to the CNS Event Bus for all other CNS agents. The other CNS agents use the connection to the CNS Event Bus to send and receive messages. The CNS event agent does not read or modify the messages.

The failover-time keyword is useful if you have a backup CNS event gateway configured. If the CNS event agent is trying to connect to the gateway and it discovers that the route to the backup is available before the route to the primary gateway, the seconds argument specifies how long the CNS event agent will continue to search for a route to the primary gateway before attempting to link to the backup gateway.

Unless you are using a bandwidth-constrained link, you should set a keepalive timeout and retry count. Doing so allows the management network to recover gracefully should a Cisco IE2100 configuration engine fail. Without the keepalive data, such a failure requires manual intervention on every device. The seconds multiplied by the retry-count determines the length of idle time before the CNS event agent will disconnect and attempt to reconnect to the gateway. Cisco recommends a minimum retry-count of 2.

If the optional source keyword is used, the source IP address might be a secondary IP address of a specific interface to allow a management network to run on top of a production network.

If network connectivity between the Cisco IOS router running the CNS Event Agent and the gateway is absent, the Event Agent goes into an exponential backoff retry mode and gets stuck at the maximum limit (which may be hours). The reconnect-time keyword allows a configurable upper limit of the maximum retry timeout.

Examples

The following example shows how to set the address of the primary CNS event gateway to the configuration engine software running on IP address 10.1.2.3, port 11011, with a keepalive of 60 seconds and a retry count of 5:

Router(config)# cns event 10.1.2.3 11011 keepalive 60 5 

Related Commands

Command
Description

cns id

Sets the unique event ID or config ID router identifier.

show cns event status

Displays status information about the CNS event agent.


cns exec

To enable and configure the CNS exec agent, which provides CNS exec services to Cisco IOS clients, use the cns exec command in global configuration mode. To disable the use of CNS exec agent services, use the no form of this command.

cns exec [host-name | ip-address] [port-number] [encrypt [enc-port-number]] [source ip-address]

no cns exec {host-name | ip-address} [port-number] [encrypt [enc-port-number]] [source ip-address]

Syntax Description

host-name

(Optional) Host name of the exec server.

ip-address

(Optional) IP address of the exec server.

port-number

(Optional) Port number for the exec server. The default is 80.

encrypt

(Optional) Uses a Secure Socket Layer (SSL) encrypted link to the exec agent server.

enc-port-number

(Optional) Port number for the encrypted exec server. The default is 443.

source

(Optional) Specifies the use of an IP address defined by the ip-address argument as the source for CNS exec agent communications.

ip-address

(Optional) IP address.


Defaults

The default exec server port number is 80.
The default encrypted exec server port number is 443.

Command Modes

Global configuration

Command History

Release
Modification

12.3(1)

This command was introduced.


Usage Guidelines

The CNS exec agent allows a remote application to execute an EXEC mode command-line interface (CLI) command on a Cisco IOS device by sending an event message containing the command. A restricted set of EXEC CLI commands—show commands—are supported.

In previous Cisco IOS Releases the CNS exec agent was enabled when the CNS configuration agent was enabled through the cns config partial command.

Examples

The following example shows how to enable the CNS exec agent with an IP address of 10.1.2.3 for the exec agent server, a port number of 93, and a source IP address of 172.17.2.2:

Router(config)# cns exec 10.1.2.3 93 source 172.17.2.2

Related Commands

Command
Description

cns event

Enables and configures CNS event agent services.

show cns event subject

Displays a list of CNS event agent subjects that are subscribed to by applications.


cns id

To set the unique event ID, config ID, or image ID Cisco IOS device identifier used by CNS services, use the cns id command in global configuration mode. To set the identifier to the host name of the Cisco IOS device, use the no form of this command.

If ID Choice Is IP Address or MAC Address

cns id type number {dns-reverse | ipaddress | mac-address} [event] [image]

no cns id type number {dns-reverse | ipaddress | mac-address} [event] [image]

If ID Choice Is Anything Else

cns id {hardware-serial | hostname | string string} [event] [image]

no cns id {hardware-serial | hostname | string string} [event] [image]

Syntax Description

type number

Type of interface (for example, ethernet, group-async, loopback, or virtual-template) and the interface number. Indicates from which interface the IP or MAC address should be retrieved in order to define the unique ID.

dns-reverse

Uses DNS reverse lookup to retrieve the host name of the Cisco IOS device and assign it as the unique ID.

ipaddress

Uses the IP address specified in the type number arguments as the unique ID.

mac-address

Uses the MAC address specified in the type number arguments as the unique ID.

event

(Optional) Sets this ID to be the event ID value, which is used to identify the Cisco IOS device for CNS event services. If both optional keywords are omitted, the event ID is set to the host name of the Cisco IOS device.

image

(Optional) Sets this ID to be the image ID value, which is used to identify the Cisco IOS device for CNS image agent services. If both optional keywords are omitted, the image ID is set to the host name of the Cisco IOS device.

hardware-serial

Uses the hardware serial number as the unique ID.

hostname

Uses the host name as the unique ID. This is the system default.

string string

Uses an arbitrary text string—typically the host name—as the unique ID.


Defaults

The system defaults to the host name of the Cisco IOS device as the unique ID.

Command Modes

Global configuration

Command History

Release
Modification

12.2(2)XB

This command was introduced on Cisco IAD2420 series IADs.

12.2(8)T

This command was integrated into Cisco IOS Release 12.2(8)T.

12.3(1)

The optional image keyword was added to set an image ID.


Usage Guidelines

Use this command to set the unique ID to the CNS configuration agent, which then pulls the initial configuration template to the Cisco IOS device during bootup.

You can set one or all three IDs: the config ID value for CNS configuration services, the event ID value for CNS event services, and the image ID value for CNS image agent services. To set all values, use the command three times.

To set the CNS event ID to the host name of the Cisco IOS device, use the no form of this command with the event keyword. To set the CNS config ID to the host name of the Cisco IOS device, use the no form of this command without the event keyword. To set the CNS image ID to the host name of the Cisco IOS device, use the no form of this command with the image keyword.

Examples

The following example shows how to pass the host name of the Cisco IOS device as the config ID value:

Router(config)# cns id hostname

The following example shows how to pass the hardware serial number of the Cisco IOS device as the event ID value:

Router(config)# cns id hardware-serial event

The following example shows how to pass the IP address of Ethernet interface 0/1 as the image ID value:

Router(config)# cns id ethernet 0/1 image

Related Commands

Command
Description

cns event

Enables the CNS event gateway, which provides CNS event services to Cisco IOS clients.


cns image

Enables the CNS image agent services to Cisco IOS clients.


cns image

To configure the CNS image agent services, use the cns image command in global configuration mode. To disable the use of CNS image agent services, use the no form of this command.

cns image [server server-url [status status-url]]

no cns image [server server-url [status status-url]]

Syntax Description

server

(Optional) Specifies an image distribution server to contact for information about an updated image to be downloaded.

server-url

(Optional) The URL used to contact an image distribution server. An IP address or domain name can be used.

status

(Optional) Specifies that any status messages generated by CNS image agent operations will be sent to the URL specified by the status-url argument.

status-url

(Optional) The URL of a web server to which status messages are written.


Defaults

When configured, the CNS image agent always listens for image events on the CNS Event Bus server.

Command Modes

Global configuration

Command History

Release
Modification

12.3(1)

This command was introduced.


Usage Guidelines

Use the cns image command to start the CNS image agent process and to listen for image-related events on the CNS Event Bus.

If the optional server details are specified, the CNS image agent uses the server URL to contact the image management server. If no server details are specified, the URL for the image server must be supplied using one of the following three methods. The first method is to specify the image server using the server options on the cns image retrieve command. The second method is to use the server configured by the CNS event agent and stored as an image server event that can be received from the CNS Event Bus. The third method does not require a server URL because it uses CNS Event Bus mode.

If the optional status details are not specified, the status messages are sent as events on the CNS Event Bus.

Examples

The following example shows how to enable the CNS image agent services and configure a path to the image distribution server and a status messages server:

Router(config)# cns image server https://10.20.2.3:8080/cns/imageserver/ status 
https://10.20.2.3:8080/cns/imageserver/messages/

Related Commands

Command
Description

show cns image status

Displays information about the CNS image agent status.


cns image password

To configure a password to use with the CNS image agent services, use the cns image password command in global configuration mode. To disable the use of a password, use the no form of this command.

cns image password image-password

no cns image password image-password

Syntax Description

image-password

Password to be used for CNS image agent services.


Defaults

No password is used with the CNS image agent services.

Command Modes

Global configuration

Command History

Release
Modification

12.3(1)

This command was introduced.


Usage Guidelines

Use this command to create a password that is sent along with the image ID in all CNS image agent messages. The receiver of these messages can use this information to authenticate the sending device. This password may be different from the username and password used for HTTP basic authentication configured with other CNS image agent commands.

Examples

The following example shows how to configure a password to be used for the CNS image agent services:

Router(config)# cns image password textabc

Related Commands

Command
Description

cns id

Specifies the unique event ID, config ID, or image ID used by CNS services.


cns image retrieve

To contact a CNS image distribution server and download a new image if a new image exists, use the cns image retrieve command in privileged EXEC mode.

cns image retrieve [server server-url [status status-url]]

Syntax Description

server

(Optional) Specifies an image distribution server to contact for information about an updated image to be downloaded. If the server keyword is not specified, the server path configured in the cns image command is used. If no server path has been configured, an error is displayed.

server-url

(Optional) The URL used to contact an image distribution server. If the server-url argument is not specified, the URL path configured in the cns image command is used. If no URL has been configured, an error is displayed.

status

(Optional) Specifies that any status messages generated by this command will be sent to the URL specified by the status-url argument.

status-url

(Optional) The URL of a web server to which status messages are written.


Defaults

If the server keyword and server-url argument are not specified, the server path configured in the cns image command is used. If no server path has been configured, an error is displayed.

Command Modes

Privileged EXEC

Command History

Release
Modification

12.3(1)

This command was introduced.


Usage Guidelines

You must enable the CNS image agent services using the cns image command before configuring this command.

Use this command to poll an image distribution server and download a new image to the Cisco IOS device if a new image exists.

Examples

The following example shows how to configure the CNS image agent to access the image distribution server at 10.19.2.3 and download a new image if a new image exists:

Router# cns image retrieve server https://10.20.2.3:8080/cns/imageserver/ status 
https://10.20.2.3:8080/cns/imageserver/messages/

Related Commands

Command
Description

cns image

Enables CNS image agent services.

cns trusted-server

Specifies a trusted server for CNS agents.

show cns image status

Displays information about the CNS image agent status.


cns image retry

To set the CNS image upgrade retry interval, use the cns image retry command in global configuration mode. To restore the default value, use the no form of this command.

cns image retry seconds

no cns image retry seconds

Syntax Description

seconds

(Optional) Interval in seconds from 0 to 65535. The default is 60 seconds.


Defaults

Retry interval is 60 seconds.

Command Modes

Global configuration

Command History

Release
Modification

12.3(1)

This command was introduced.


Usage Guidelines

Use this command to set an interval after which the CNS image agent will retry an image upgrade operation if the original upgrade attempt failed.

Examples

The following example shows how to set the CNS image upgrade interval to 240 seconds:

Router(config)# cns image retry 240

Related Commands

Command
Description

cns image

Enables CNS image agent services.


cns inventory

To enable the CNS inventory agent—that is, to send an inventory of the router's line cards and modules to the CNS configuration engine—and enter CNS inventory mode, use the cns inventory command in global configuration mode. To disable the CNS inventory agent, use the no form of this command.

cns inventory

no cns inventory

Syntax Description

This command has no arguments or keywords.

Defaults

Disabled

Command Modes

Global configuration

Command History

Release
Modification

12.2(8)T

This command was introduced.

12.3(1)

The config, event, and notify oir keywords were removed.


Usage Guidelines

Use this command with the announce config and transport event CNS inventory configuration mode commands to specify when to notify the CNS configuration engine of changes to the router's port-adaptor and interface inventory. A transport must be specified in CNS inventory configuration mode before any of the CNS inventory commands are executed.

Examples

The following example shows how to enable the CNS inventory agent and enter CNS inventory configuration mode:

Router(config)# cns inventory
Router(cns_inv)#

Related Commands

Command
Description

announce config

Species that an unsolicited configuration inventory is sent out by the CNS inventory agent at bootup.

cns config initial

Starts the CNS configuration agent and initiates an initial configuration.

transport events

Species that inventory events are sent out by the CNS inventory agent.


cns mib-access encapsulation

To specify whether Cisco Networking Services (CNS) should use nongranular (SNMP) or granular (XML) encapsulation to access MIBs, use the cns mib-access encapsulation command in global configuration mode. To disable the currently specified encapsulation, use the no form of this command.

cns mib-access encapsulation {snmp | xml [size bytes]}

no cns mib-access encapsulation {snmp | xml}

Syntax Description

snmp

Enables nongranular (SNMP) encapsulation for MIB access.

xml

Enables granular (XML) encapsulation for MIB access.

size bytes

(Optional) Maximum size in bytes for response events. The default is 3072.


Defaults

For XML encapsulation, a maximum size of 3072 bytes.

Command Modes

Global configuration

Command History

Release
Modification

12.2(8)T

This command was introduced on Cisco 2600 series and Cisco 3600 series routers.


Examples

The following example specifies that XML be used to access MIBs:

Router(config)# cns mib-access encapsulation xml 

Related Commands

Command
Description

cns notifications encapsulation

Specifies whether CNS notifications should be sent using nongranular (SNMP) or granular (XML) encapsulation.


cns notifications encapsulation

To specify whether Cisco Networking Services (CNS) notifications should be sent using nongranular (SNMP) or granular (XML) encapsulation, use the cns notifications encapsulation command in global configuration mode. To disable the currently specified encapsulation, use the no form of this command.

cns notifications encapsulation {snmp | xml}

no cns notifications encapsulation {snmp | xml}

Syntax Description

snmp

Uses nongranular (SNMP) encapsulation to send notifications.

xml

Uses granular (XML) encapsulation to send notifications.


Defaults

This command is disabled.

Command Modes

Global configuration

Command History

Release
Modification

12.2(8)T

This command was introduced on Cisco 2600 series and Cisco 3600 series routers.


Examples

The following example shows how to specify that granular notifications should be sent:

Router(config)# cns notifications encapsulation xml 

Related Commands

Command
Description

cns mib-access encapsulation

Specifies whether CNS should use granular (XML) or nongranular (SNMP) encapsulation to access MIBs.


cns template connect

To enter Cisco Networking Services (CNS) template connect configuration mode and define the name of a CNS connect template, use the cns template connect command in global configuration mode. To disable the CNS connect template, use the no form of this command.

cns template connect name

no cns template connect name

Syntax Description

name

The name of the CNS connect template to be configured.


Defaults

No CNS connect templates are defined.

Command Modes

Global configuration

Command History

Release
Modification

12.3(2)XF

This command was introduced.

12.3(8)T

This command was integrated into Cisco IOS Release 12.3(8)T.

12.3(9)

This command was integrated into Cisco IOS Release 12.3(9).


Usage Guidelines

Use the cns template connect command to enter CNS template connect configuration mode and define the name of the CNS connect template to be configured. Then use the cli command to specify the command lines of the CNS connect template.


Note When creating a CNS connect template, you must enter the exit command to complete the configuration of the template and exit from CNS template connect configuration mode. This requirement was implemented to prevent accidentally entering a command without the cli command.



Note Effective with Cisco IOS Releases 12.3(8)T and 12.3(9), the cns config connect-intf command is replaced by the cns connect and cns template connect commands.


Examples

The following example shows how to configure a CNS connect template named template1:

Router (config)# cns template connect template-1
Router (config-templ-conn)# cli command-1
Router (config-templ-conn)# cli command-2
Router (config-templ-conn)# cli no command-3
Router (config-templ-conn)# exit
Router (config)#

When the template1 template is applied, the following commands are sent to the router's parser:

command-1
command-2
no command-3

When the template1 template is removed from the router's configuration after an unsuccessful ping attempt to the CNS configuration engine, the following commands are sent to the router's parser:

no command-1
no command-2
command-3

Related Commands

Command
Description

cli (cns)

Specifies the command lines of a CNS connect template.

cns connect

Enters CNS connect configuration mode and defines the parameters of a CNS connect profile for connecting to the CNS configuration engine.

discover (cns)

Defines the interface parameters within a CNS connect profile for connecting to the CNS configuration engine.

template (cns)

Specifies a list of CNS connect templates within a CNS connect profile to be applied to a router's configuration.


cns trusted-server

To specify a trusted server for CNS agents, use the cns trusted-server command in global configuration mode. To disable the use of a trusted server for a CNS agent, use the no form of this command.

cns trusted-server {all-agents | config | event | exec | image} hostname | ip-address

no cns trusted-server {all-agents | config | event | exec | image}

Syntax Description

all-agents

Specifies a trusted server for all CNS agents.

config

Specifies a trusted server for CNS config agent.

event

Specifies a trusted server for CNS event agent.

exec

Specifies a trusted server for CNS exec agent.

image

Specifies a trusted server for CNS image agent.

hostname

Host name of the trusted server.

ip-address

IP address of the trusted server.


Defaults

all-agents

Command Modes

Global configuration

Command History

Release
Modification

12.3(1)

This command was introduced.


Usage Guidelines

Use the cns trusted-server command to specify a trusted server for an individual CNS agent or all the CNS agents. In previous Cisco IOS Releases CNS agents could connect to any server and this could expose the system to security violations. An attempt to connect to a server not on the list will result in an error message being displayed. For backwards compatibility the configuration of a server address using the configuration command-line interface (CLI) for a CNS agent will result in an implicit trust of the server. The implicit trusted server commands apply only to commands in configuration mode, not EXEC mode commands.

Use this command when a CNS agent will redirect its response to a server address that is not explicitly configured on the command line for the specific CNS agent. For example, the CNS exec agent may have one server configured but receive a message from the CNS Event Bus that overrides the configured server. The new server address has not been explicitly configured so the new server address is not a trusted server. An error will be generated when the CNS exec agent tries to respond to this new server address unless the cns trusted-server command has been configured for the new server address.

Examples

The following example shows how to configure server 10.19.2.5 as a trusted server for the CNS event agent:

Router# cns trusted-server event 10.19.2.5

The following example shows how to configure server 10.2.2.8 as an implicit trusted server for the CNS image agent:

Router# cns image server 10.2.2.8 status 10.2.2.8

Related Commands

Command
Description

cns config

Configures CNS configuration agent services.

cns event

Enables and configures CNS event agent services.

cns image

Configures CNS image agent services.


config-cli


Note Effective with Cisco IOS Releases 12.3(8)T and 12.3(9), the config-cli command is replaced by the cli (cns) command. See the cli (cns) command for more information.


To connect to the Cisco Networking Services (CNS) configuration engine using a specific type of interface, use the config-cli command in CNS Connect-interface configuration mode.

config-cli type [number]

Syntax Description

type number

Type of interface. Indicates from which interface the IP or MAC address should be retrieved in order to define the unique ID.

number

(Optional) Interface number. Indicates from which interface the IP or MAC address should be retrieved in order to define the unique ID.


Defaults

No command lines are specified to configure the interface.

Command Modes

CNS Connect-interface configuration

Command History

Release
Modification

12.2(8)T

This command was introduced on Cisco 2600 series and Cisco 3600 series routers.

12.3(8)T

This command was replaced by the cli (cns) command.

12.3(9)

This command was replaced by the cli (cns) command.


Usage Guidelines

Begin by using the cns config connect-intf command to enter CNS Connect-interface configuration (config-cns-conn-if) mode. Then use either this or its companion CNS bootstrap-configuration command to connect to the CNS configuration engine for initial configuration:

config-cli connects to the registrar using a specific type of interface. You must specify the interface type but need not specify the interface number; the router's bootstrap configuration finds the connecting interface, regardless of the slot in which the card resides, by trying different candidate interfaces until it can ping the configuration engine.

line-cli connects to the registrar using modem dialup lines.

Immediately after either of the commands, enter additional configuration commands as appropriate.

Examples

The following example enters CNS Connect-interface configuration mode, connects to a configuration engine using an asynchronous interface, and issues a number of commands:

Router(config)# cns config connect-intf Async
Router(config-cns-conn-if)# config-cli encapsulation ppp
Router(config-cns-conn-if)# config-cli ip unnumbered FastEthernet0/0
Router(config-cns-conn-if)# config-cli dialer rotary-group 0
Router(config-cns-conn-if)# line-cli modem InOut
Router(config-cns-conn-if)# line-cli
.
.
.
Router(config-cns-conn-if)# exit

These commands apply the following configuration:

line 65
modem InOut
.
.
.
interface Async65
encapsulation ppp
dialer in-band
dialer rotary-group 0

Related Commands

Command
Description

cns config connect-intf

Specifies the interface for connecting to the CNS configuration engine.

line-cli

Connects to the CNS configuration engine using a modem dialup line.


config-register

To change the configuration register settings, use the config-register command in global configuration mode.

config-register value

Syntax Description

value

Hexadecimal or decimal value that represents the 16-bit configuration register value that you want to use the next time the router is restarted. The value range is from 0x0 to 0xFFFF (0 to 65535 in decimal).


Defaults

Refer to the documentation for your platform for the default configuration register value. For many newer platforms, the default is 0x2102, which causes the router to boot from Flash memory and the Break key to be ignored.

Command Modes

Global configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

This command applies only to platforms that use a software configuration register.

The lowest four bits of the configuration register (bits 3, 2, 1, and 0) form the boot field. The boot field determines if the router boots manually, from ROM, or from Flash or the network.

To change the boot field value and leave all other bits set to their default values, follow these guidelines:

If you set the configuration register boot field value to 0x0, you must boot the operating system manually with the boot command.

If you set the configuration register boot field value to 0x1, the router boots using the default ROM software.

If you set the configuration register boot field to any value from 0x2 to 0xF, the router uses the boot field value to form a default boot filename for booting from a network server.

For more information about the configuration register bit settings and default filenames, refer to the appropriate router hardware installation guide.

Examples

In the following example, the configuration register is set to boot the system image from Flash memory:

config-register 0x2102

Related Commands

Command
Description

boot system

Specifies the system image that the router loads at startup.

confreg

Changes the configuration register settings while in ROM monitor mode.

o

Lists the value of the boot field (bits 0 to 3) in the configuration register.

show version

Displays the configuration of the system hardware, the software version, the names and sources of configuration files, and the boot images.


configure memory

To configure the system from the system memory, use the configure memory command in privileged EXEC mode.

configure memory

Syntax Description

This command has no arguments or keywords.

Command Modes

Privileged EXEC

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

On all platforms except Class A Flash file system platforms, this command executes the commands located in the configuration file in NVRAM (the "startup configuration file").

On Class A Flash file system platforms, if you specify the configure memory command, the router executes the commands pointed to by the CONFIG_FILE environment variable. The CONFIG_FILE environment variable specifies the location of the configuration file that the router uses to configure itself during initialization. The file can be located in NVRAM or any of the Flash file systems supported by the platform.

When the CONFIG_FILE environment variable specifies NVRAM, the router executes the NVRAM configuration only if it is an entire configuration, not a distilled version. A distilled configuration is one that does not contain access lists.

To view the contents of the CONFIG_FILE environment variable, use the show bootvar EXEC command. To modify the CONFIG_FILE environment variable, use the boot config command and then save your changes by issuing the copy system:running-config nvram:startup-config command.

Examples

In the following example, a router is configured from the configuration file in the memory location pointed to by the CONFIG_FILE environment variable:

Router# configure memory

Related Commands

Command
Description

boot config

Specifies the device and filename of the configuration file from which the router configures itself during initialization (startup).

copy system:running-config nvram:startup-config

Saves the running configuration as the startup configuration file.

show bootvar

Displays the contents of the BOOT environment variable, the name of the configuration file pointed to by the CONFIG_FILE environment variable, the contents of the BOOTLDR environment variable, and the configuration register setting.


configure network

The configure network command was replaced by the copy {rcp | tftp} running-config command in Cisco IOS Release 11.0. To maintain backward compatibility, the configure network command continues to function in Cisco IOS Release 12.2(11)T for most systems, but support for this command may be removed in a future release.

The copy {rcp | tftp} running-config command was replaced by the copy {ftp: | rcp: | tftp:}[filenamesystem:running-config command in Cisco IOS Release 12.1.

The copy {ftp: | rcp: | tftp:}[filename] system:running-config command specifies that a configuration file should be copied from a FTP, rcp, or TFTP source to the running configuration. See the description of the copy command in this chapter for more information.

configure overwrite-network

The configure overwrite-network has been replaced by the copy {ftp-url | rcp-url | tftp-url} nvram:startup-config command. See the description of the copy command in the "Cisco IOS File System Commands" chapter for more information.

configure terminal

To enter global configuration mode, use the configure terminal command in privileged EXEC mode.

configure terminal

Syntax Description

This command has no arguments or keywords.

Command Modes

Privileged EXEC

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Use this command to enter global configuration mode. Note that commands in this mode are written to the running configuration file as soon as you enter them (using the Enter key/Carriage Return).

After you enter the configure command, the system prompt changes from <router-name># to <router-name>(config)#, indicating that the router is in global configuration mode. To leave global configuration mode and return to privileged EXEC mode, type end or press Ctrl-Z.

To view the changes to the configuration you have made, use the more system:running-config command or show running-config command in EXEC mode.

Examples

In the following example, the user enters global configuration mode:

Router# configure terminal
Enter configuration commands, one per line. End with CNTL/Z.
Router(config)#


Related Commands

Command
Description

boot config

Specifies the device and filename of the configuration file from which the router configures itself during initialization (startup).

copy running-config startup-config

OR

copy system:running-config nvram:startup-config

Saves the running configuration as the startup configuration file.

show running-config

OR

more system:running-config

Displays the currently running configuration.


confreg

To change the configuration register settings while in ROM monitor mode, use the confreg command in ROM monitor mode.

confreg [value]

Syntax Description

value

(Optional) Hexadecimal value that represents the 16-bit configuration register value that you want to use the next time the router is restarted. The value range is from 0x0 to 0xFFFF.


Defaults

Refer to your platform documentation for the default configuration register value.

Command Modes

ROM monitor

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Not all versions in the ROM monitor support this command. Refer to your platform documentation for more information on ROM monitor mode.

If you use this command without specifying the configuration register value, the router prompts for each bit of the configuration register.

The lowest four bits of the configuration register (bits 3, 2, 1, and 0) form the boot field. The boot field determines if the router boots manually, from ROM, or from Flash or the network.

To change the boot field value and leave all other bits set to their default values, follow these guidelines:

If you set the configuration register boot field value to 0x0, you must boot the operating system manually with the boot command.

If you set the configuration register boot field value to 0x1, the router boots using the default ROM software.

If you set the configuration register boot field to any value from 0x2 to 0xF, the router uses the boot field value to form a default boot filename for booting from a network server.

For more information about the configuration register bit settings and default filenames, refer to the appropriate router hardware installation guide.

Examples

In the following example, the configuration register is set to boot the system image from Flash memory:

confreg 0x210F

In the following example, no configuration value is entered, so the system prompts for each bit in the register:

rommon 7 > confreg
     Configuration Summary
enabled are:
console baud: 9600
boot: the ROM Monitor
do you wish to change the configuration? y/n  [n]:  y
enable  "diagnostic mode"? y/n  [n]:  y
enable  "use net in IP bcast address"? y/n  [n]:  

enable  "load rom after netboot fails"? y/n  [n]:  
enable  "use all zero broadcast"? y/n  [n]:  
enable  "break/abort has effect"? y/n  [n]:  
enable  "ignore system config info"? y/n  [n]:  
change console baud rate? y/n  [n]:  y
enter rate: 0 = 9600, 1 = 4800, 2 = 1200, 3 = 2400  [0]:  0
change the boot characteristics? y/n  [n]:  y
enter to boot:
 0 = ROM Monitor
 1 = the boot helper image
 2-15 = boot system
    [0]:  0
     Configuration Summary
enabled are:
diagnostic mode
console baud: 9600
boot: the ROM Monitor
do you wish to change the configuration? y/n  [n]:  

You must reset or power cycle for new config to take effect.
rommon 8>

continue

To return to EXEC mode from ROM monitor mode, use the continue command in ROM monitor mode.

continue

Syntax Description

This command has no arguments or keywords.

Defaults

No default behavior or values.

Command Modes

ROM monitor

Command History

Release
Modification

11.0

This command was introduced.


Usage Guidelines

Use this command to return to EXEC mode from ROM monitor mode, to use the system image instead of reloading. On older platforms, the angle bracket (< >) indicates that the router is in ROM monitor mode. On newer platforms, rommon number> is the default ROM monitor prompt. Typically, the router is in ROM monitor mode when you manually load a system image or perform diagnostic tests. Otherwise, the router will most likely never be in this mode.


Caution While in ROM monitor mode, the Cisco IOS system software is suspended until you issue either a reset or the continue command.

Examples

In the following example, the continue command switches the router from ROM monitor to EXEC mode:

> continue
Router#

Related Commands

Command
Description

boot

Boots the router manually.


copy

To copy any file from a source to a destination, use the copy command in EXEC mode.

copy [/erase] source-url destination-url

Syntax Description

/erase

(Optional) Erases the destination file system before copying.

source-url

The location URL or alias of the source file or directory to be copied.

destination-url

The destination URL or alias of the copied file or directory.


The exact format of the source and destination URLs varies according to the file or directory location. You may enter either an alias keyword for a particular file or an alias keyword for a file system type (not a file within a type).


Timesaver Aliases are used to cut down on the amount of typing you need to perform. For example, it is easier to type copy run start (the abbreviated form of the copy running-config startup-config command) than it is to type copy system:r nvram:s (the abbreviated form of the copy system:running-config nvram:startup-config command). These aliases also allow you to continue using some of the common commands used in previous versions of Cisco IOS software.


Table 15 shows two keyword shortcuts to URLs.

Table 15 Common Keyword Aliases to URLs

Keyword
Source or Destination

running-config

(Optional) Keyword alias for the system:running-config URL.
The system:running-config keyword represents the current running configuration file. This keyword does not work in more and show file EXEC command syntaxes.

startup-config

(Optional) Keyword alias for the nvram:startup-config URL.
The nvram:startup-config keyword represents the configuration file used during initialization (startup). This file is contained in NVRAM for all platforms except the Cisco 7000 family, which uses the CONFIG_FILE environment variable to specify the startup configuration. The Cisco 4500 series cannot use the copy running-config startup-config command. This keyword does not work in more and show file EXEC command syntaxes.


The following tables list aliases by file system type. If you do not specify an alias, the router looks for a file in the current directory.

Table 16 lists URL aliases for Special (opaque) file systems. Table 17 lists them for network file systems, and Table 18 lists them for local writable storage.

Table 16 URL Prefix Aliases for Special File Systems 

Alias
Source or Destination

flh:

Source URL for flash load helper log files.

modem:

Destination URL for loading modem firmware on Cisco 5200 and 5300 Series routers.

nvram:

Router NVRAM. You can copy the startup configuration into or from NVRAM. You can also display the size of a private configuration file.

null:

Null destination for copies or files. You can copy a remote file to null to determine its size.

system:

Source or destination URL for system memory, which includes the running configuration.

xmodem:

Source destination for the file from a network machine that uses the Xmodem protocol.

ymodem:

Source destination for the file from a network machine that uses the Xmodem protocol.


Table 17 URL Prefix Aliases for Network File Systems

Alias
Source or Destination

ftp:

Source or destination URL for an File Transfer Protocol (FTP) network server. The syntax for this alias is as follows:
ftp:[[[//username [:password]@]location]/directory]/filename.

rcp:

Source or destination URL for a Remote Copy Protocol (rcp) network server. The syntax for this alias is as follows: rcp:[[[//username@]location]/directory]/filename.

tftp:

Source or destination URL for a TFTP network server. The syntax for this alias is tftp:[[//location]/directory]/filename.


Table 18 URL Prefix Aliases for Local Writable Storage File Systems 

Alias
Source or Destination

bootflash:

Source or destination URL for boot flash memory.

disk0: and disk1:

Source or destination URL of rotating media.

flash:

Source or destination URL for Flash memory. This alias is available on all platforms. For platforms that lack a flash: device, note that flash: is aliased to slot0:, allowing you to refer to the main Flash memory storage area on all platforms.

slavebootflash:

Source or destination URL for internal Flash memory on the slave RSP card of a router configured for HSA.

slaveram:

NVRAM on a slave RSP card of a router configured for HSA.

slaveslot0:

Source or destination URL of the first PCMCIA card on a slave RSP card of a router configured for HSA.

slaveslot1:

Source or destination URL of the second PCMCIA slot on a slave RSP card of a router configured for HSA.

slot0:

Source or destination URL of the first PCMCIA Flash memory card.

slot1:

Source or destination URL of the second PCMCIA Flash memory card.


Command Modes

EXEC

Command History

Release
Modification

11.3 T

This command was introduced.


Usage Guidelines

You can enter on the command line all necessary source- and destination-URL information and the username and password to use, or you can enter the copy command and have the router prompt you for any missing information.

If you enter information, choose one of the following three options: running-config, startup-config, or a file system alias (see previous tables). The location of a file system dictates the format of the source or destination URL.

The colon is required after the alias. However, earlier commands not requiring a colon remain supported, but are unavailable in context-sensitive help.

The entire copying process may take several minutes and differs from protocol to protocol and from network to network.

In the alias syntax for ftp:, rcp:, and tftp:, the location is either an IP address or a host name. The filename is specified relative to the directory used for file transfers.

This section contains usage guidelines for the following topics:

Understanding Invalid Combinations of Source and Destination

Understanding Character Descriptions

Understanding Partitions

Using rcp

Using FTP

Storing Images on Servers

Copying from a Server to Flash Memory

Verifying Images

Copying a Configuration File from a Server to the Running Configuration

Copying a Configuration File from a Server to the Startup Configuration

Storing the Running or Startup Configuration on a Server

Saving the Running Configuration to the Startup Configuration

Using CONFIG_FILE, BOOT, and BOOTLDR Environment Variables

Using the Copy Command with the Dual RSP Feature

Understanding Invalid Combinations of Source and Destination

Some invalid combinations of source and destination exist. Specifically, you cannot copy the following:

From a running configuration to a running configuration

From a startup configuration to a startup configuration

From a device to the same device (for example, the copy flash: flash: command is invalid)

Understanding Character Descriptions

Table 19 describes the characters that you may see during processing of the copy command.

Table 19 copy Character Descriptions

Character
Description

!

For network transfers, an exclamation point indicates that the copy process is taking place. Each exclamation point indicates the successful transfer of ten packets (512 bytes each).

.

For network transfers, a period indicates that the copy process timed out. Many periods in a row typically mean that the copy process may fail.

O

For network transfers, an uppercase O indicates that a packet was received out of order and the copy process may fail.

e

For Flash erasures, a lowercase e indicates that a device is being erased.

E

An uppercase E indicates an error. The copy process may fail.

V

A series of uppercase Vs indicates the progress during the verification of the image checksum.


Understanding Partitions

You cannot copy an image or configuration file to a Flash partition from which you are currently running. For example, if partition 1 is running the current system image, copy the configuration file or image to partition 2. Otherwise, the copy operation will fail.

You can identify the available Flash partitions by entering the show file system EXEC command.

Using rcp

The rcp requires a client to send a remote username upon each rcp request to a server. When you copy a configuration file or image between the router and a server using rcp, the Cisco IOS software sends the first valid username it encounters in the following sequence:

1. The remote username specified in the copy command, if a username is specified.

2. The username set by the ip rcmd remote-username global configuration command, if the command is configured.

3. The remote username associated with the current tty (terminal) process. For example, if the user is connected to the router through Telnet and was authenticated through the username command, the router software sends the Telnet username as the remote username.

4. The router host name.

For the rcp copy request to process, an account must be defined on the network server for the remote username. If the network administrator of the destination server did not establish an account for the remote username, this command will not run. If the server has a directory structure, the configuration file or image is written to or copied from the directory associated with the remote username on the server. For example, if the system image resides in the home directory of a user on the server, specify that user name as the remote username.

If you are writing to the server, the rcp server must be properly configured to accept the rcp write request from the user on the router. For UNIX systems, add an entry to the .rhosts file for the remote user on the rcp server. Suppose the router contains the following configuration lines:

hostname Rtr1
ip rcmd remote-username User0

If the router IP address translates to Router1.company.com, then the .rhosts file for User0 on the rcp server should contain the following line:

Router1.company.com Rtr1

Refer to the documentation for your rcp server for more details.

If you are using a personal computer as a file server, the computer must support the remote shell protocol (rsh).

Using FTP

The FTP protocol requires a client to send a username and password with each FTP request to a remotre FTP server. Use the ip ftp username and ip ftp password global configuration commands to specify a default username and password for all copy operations to or from an FTP server. Include the username in the copy command syntax if you want to specify a username for that copy operation only.

When you copy a configuration file from the router to a server using FTP, the Cisco IOS software sends the first valid username that it encounters in the following sequence:

1. The username specified in the copy command, if a username is specified.

2. The username set by the ip ftp username command, if the command is configured.

3. Anonymous.

The router sends the first valid password in the following list:

1. The password specified in the copy command, if a password is specified.

2. The password set by the ip ftp password command, if the command is configured.

3. The router forms a password username@routername.domain. The variable username is the username associated with the current session, routername is the configured host name, and domain is the domain of the router.

The username and password must be associated with an account on the FTP server. If you are writing to the server, the FTP server must be properly configured to accept the FTP write request from the user on the router.

If the server has a directory structure, the configuration file or image is written to or copied from the directory associated with the username on the server. For example, if the system image resides in the home directory of a user on the server, specify that user name as the remote username.

Refer to the documentation for your FTP server for more details.

Storing Images on Servers

Use the copy flash: destination-url command (for example, copy flash: tftp:) to copy a system image or boot image from Flash memory to a network server. You can use the copy of the image as a backup copy. Also, you can also use the image backup file to verify that the image in Flash memory is the same as that in the original file.

Copying from a Server to Flash Memory

Use the copy destination-url flash: command (for example, copy tftp: flash:) to copy an image from a server to Flash memory.

On Class B file system platforms, the system provides an option to erase existing Flash memory before writing onto it.


Note Verify the image in Flash memory before booting the image.


Verifying Images

When copying a new image to your router, you should confirm that the image was not corrupted during the copy process. Depending on the destination filesystem type, a checksum for the image file may be displayed when the copy command completes. You can verify this checksum by comparing it to the checksum value provided for your image file on Cisco.com.


Caution If the checksum values do not match, do not reboot the router. Instead, reissue the copy command and compare the checksums again. If the checksum is repeatedly wrong, copy the original image back into Flash memory before you reboot the router from Flash memory. If you have a corrupted image in Flash memory and try to boot from Flash memory, the router will start the system image contained in ROM (assuming booting from a network server is not configured). If ROM does not contain a fully functional system image, the router might not function and will need to be reconfigured through a direct console port connection.

An alternate method for file verification is to use the UNIX 'diff' command. This method can also be applied to file types other than Cisco IOS images. If you suspect that a file is corrupted, copy the suspect file and the original file to a Unix server. (The file names may need to be modified if you try to save the files in the same directory.) Then run the UNIX 'diff' command on the two files. If there is no difference, then the file has not been corrupted.

Copying a Configuration File from a Server to the Running Configuration

Use the copy {ftp: | rcp: | tftp:} running-config command to load a configuration file from a network server to the running configuration of the router (note that running-config is the alias for the system:running-config keyword). The configuration will be added to the running configuration as if the commands were typed in the command-line interface (CLI). Thus, the resulting configuration file will be a combination of the previous running configuration and the loaded configuration file, with the loaded configuration file having precedence.

You can copy either a host configuration file or a network configuration file. Accept the default value of host to copy and load a host configuration file containing commands that apply to one network server in particular. Enter network to copy and load a network configuration file containing commands that apply to all network servers on a network.

Copying a Configuration File from a Server to the Startup Configuration

Use the copy {ftp: | rcp: | tftp:} nvram:startup-config command to copy a configuration file from a network server to the router startup configuration. These commands replace the startup configuration file with the copied configuration file.

Storing the Running or Startup Configuration on a Server

Use the copy system:running-config {ftp: | rcp: | tftp:} command to copy the current configuration file to a network server using FTP, rcp, or TFTP. Use the copy nvram:startup-config {ftp: | rcp: | tftp:} command to copy the startup configuration file to a network server.

The configuration file copy can serve as a backup copy.

Saving the Running Configuration to the Startup Configuration

Use the copy system:running-config nvram:startup-config command to copy the running configuration to the startup configuration.


Note Some specific commands might not get saved to NVRAM. You will need to enter these commands again if you reboot the machine. These commands are noted in the documentation. We recommend that you keep a listing of these settings so you can quickly reconfigure your router after rebooting.


If you issue the copy system:running-config nvram:startup-config command from a bootstrap system image, a warning will instruct you to indicate whether you want your previous NVRAM configuration to be overwritten and configuration commands to be lost. This warning does not appear if NVRAM contains an invalid configuration or if the previous configuration in NVRAM was generated by a bootstrap system image.

On all platforms except Class A file system platforms, the copy system:running-config nvram:startup-config command copies the currently running configuration to NVRAM.

On the Class A Flash file system platforms, the copy system:running-config nvram:startup-config command copies the currently running configuration to the location specified by the CONFIG_FILE environment variable. This variable specifies the device and configuration file used for initialization. When the CONFIG_FILE environment variable points to NVRAM or when this variable does not exist (such as at first-time startup), the software writes the current configuration to NVRAM. If the current configuration is too large for NVRAM, the software displays a message and stops executing the command.

When the CONFIG_FILE environment variable specifies a valid device other than nvram: (that is, flash:, bootflash:, slot0:, or slot1:), the software writes the current configuration to the specified device and filename, and stores a distilled version of the configuration in NVRAM. A distilled version is one that does not contain access list information. If NVRAM already contains a copy of a complete configuration, the router prompts you to confirm the copy.

Using CONFIG_FILE, BOOT, and BOOTLDR Environment Variables

For the Class A Flash file system platforms, specifications are as follows:

The CONFIG_FILE environment variable specifies the configuration file used during router initialization.

The BOOT environment variable specifies a list of bootable images on various devices.

The BOOT environment variable specifies a list of bootable images on various devices.

The BOOTLDR environment variable specifies the Flash device and filename containing the rxboot image that ROM uses for booting.

Cisco 3600 routers do not use a dedicated boot helper image (rxboot), which many other routers use to help with the boot process. Instead, the BOOTLDR ROM monitor environment variable identifies the Flash memory device and filename that are used as the boot helper; the default is the first system image in Flash memory.

To view the contents of environment variables, use the show bootvar EXEC command. To modify the CONFIG_FILE environment variable, use the boot config global configuration command. To modify the BOOTLDR environment variable, use the boot bootldr global configuration command. To modify the BOOT environment variable, use the boot system global configuration command. To save your modifications, use the copy system:running-config nvram:startup-config command.

When the destination of a copy command is specified by the CONFIG_FILE or BOOTLDR environment variable, the router prompts you for confirmation before proceeding with the copy. When the destination is the only valid image in the BOOT environment variable, the router also prompts you for confirmation before proceeding with the copy.

Using the Copy Command with the Dual RSP Feature

The Dual RSP feature allows you to install two Route Switch Processor (RSP) cards in a single router on the Cisco 7507 and Cisco 7513 platforms.

On a Cisco 7507 or Cisco 7513 router configured for Dual RSPs, if you copy a file to nvram:startup-configuration with automatic synchronization disabled, the system asks if you also want to copy the file to the slave startup configuration. The default answer is yes. If automatic synchronization is enabled, the system automatically copies the file to the slave startup configuration each time you use a copy command with nvram:startup-configuration as the destination.

Examples

The following examples illustrate uses of the copy command.

Copying an Image from a Server to Flash Memory Examples

Saving a Copy of an Image on a Server Examples

Copying a Configuration File from a Server to the Running Configuration Example

Copying a Configuration File from a Server to the Startup Configuration Example

Copying the Running Configuration to a Server Example

Copying the Startup Configuration to a Server Example

Saving the Current Running Configuration Example

Moving Configuration Files to Other Locations Examples

Copying an Image from the Master RSP Card to the Slave RSP Card Example

Copying an Image from a Server to Flash Memory Examples

The following three examples use a copy rcp:, copy tftp:, or copy ftp: command to copy an image file from a server to Flash memory:

Copying an Image from a Server to Flash Memory Example

Copying an Image from a Server to a Flash Memory Using Flash Load Helper Example

Copying an Image from a Server to a Flash Memory Card Partition Example

Copying an Image from a Server to Flash Memory Example

This example copies a system image named file1 from the remote rcp server with an IP address of 172.16.101.101 to Flash memory. On Class B file system platforms, the Cisco IOS software allows you to first erase the contents of Flash memory to ensure that enough Flash memory is available to accommodate the system image.

Router# copy rcp://netadmin@172.16.101.101/file1 flash:file1 

Destination file name [file1]?
Accessing file 'file1' on 172.16.101.101...
Loading file1 from 172.16.101.101 (via Ethernet0): ! [OK]

Erase flash device before writing? [confirm]
Flash contains files. Are you sure you want to erase? [confirm]

Copy 'file1' from server
  as 'file1' into Flash WITH erase? [yes/no] yes
Erasing device... eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee...erased
Loading file1 from 172.16.101.101 (via Ethernet0): !
[OK - 984/8388608 bytes]

Verifying checksum... OK (0x14B3)
Flash copy took 0:00:01 [hh:mm:ss]

Copying an Image from a Server to a Flash Memory Using Flash Load Helper Example

The following example copies a system image into a partition of Flash memory. The system will prompt for a partition number only if there are two or more read/write partitions or one read-only and one read/write partition and dual Flash bank support in boot ROMs. If the partition entered is not valid, the process terminates. You can enter a partition number, a question mark (?) for a directory display of all partitions, or a question mark and a number (?number) for directory display of a particular partition. The default is the first read/write partition. In this case, the partition is read-only and has dual Flash bank support in boot ROM, so the system uses Flash Load Helper.

Router# copy tftp: flash: 

System flash partition information:
Partition   Size     Used    Free    Bank-Size   State       Copy-Mode
    1       4096K    2048K   2048K   2048K       Read Only   RXBOOT-FLH
    2       4096K    2048K   2048K   2048K       Read/Write  Direct

[Type ?<no> for partition directory; ? for full directory; q to abort]
Which partition? [default = 2]

                               **** NOTICE ****
Flash load helper v1.0
This process will accept the copy options and then terminate
the current system image to use the ROM based image for the copy.
Routing functionality will not be available during that time.
If you are logged in via telnet, this connection will terminate.
Users with console access can see the results of the copy operation.
                               ---- ******** ----
Proceed? [confirm]
System flash directory, partition 1:
File  Length   Name/status
  1   3459720  master/igs-bfpx.100-4.3
[3459784 bytes used, 734520 available, 4194304 total]
Address or name of remote host [255.255.255.255]? 172.16.1.1 
Source file name? master/igs-bfpx-100.4.3 
Destination file name [default = source name]?

Loading master/igs-bfpx.100-4.3 from 172.16.1.111: !
Erase flash device before writing? [confirm]
Flash contains files. Are you sure? [confirm]
Copy 'master/igs-bfpx.100-4.3' from TFTP server
as 'master/igs-bfpx.100-4.3' into Flash WITH erase? [yes/no] yes 

Copying an Image from a Server to a Flash Memory Card Partition Example

The following example copies the file c3600-i-mz from the rcp server at IP address 172.23.1.129 to the Flash memory card in slot 0 of a Cisco 3600 series router, which has only one partition. As the operation progresses, the Cisco IOS software asks you to erase the files on the Flash memory PC card to accommodate the incoming file. This entire operation takes 18 seconds to perform, as indicated at the end of the example.

Router# copy rcp: slot0:

PCMCIA Slot0 flash

Partition   Size    Used      Free      Bank-Size  State          Copy Mode
  1         4096K   3068K     1027K     4096K      Read/Write     Direct
  2         4096K   1671K     2424K     4096K      Read/Write     Direct
  3         4096K      0K     4095K     4096K      Read/Write     Direct
  4         4096K   3825K      270K     4096K      Read/Write     Direct

[Type ?<no> for partition directory; ? for full directory; q to abort]
Which partition? [default = 1] 

PCMCIA Slot0 flash directory, partition 1:
File  Length   Name/status
  1   3142288  c3600-j-mz.test  
[3142352 bytes used, 1051952 available, 4194304 total]
Address or name of remote host [172.23.1.129]? 
Source file name? /tftpboot/images/c3600-i-mz 
Destination file name [/tftpboot/images/c3600-i-mz]? 
Accessing file '/tftpboot/images/c3600-i-mz' on 172.23.1.129...
Connected to 172.23.1.129
Loading 1711088 byte file c3600-i-mz: ! [OK]

Erase flash device before writing? [confirm]
Flash contains files. Are you sure you want to erase? [confirm]

Copy '/tftpboot/images/c3600-i-mz' from server
  as '/tftpboot/images/c3600-i-mz' into Flash WITH erase? [yes/no] yes 
Erasing device... eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee ...erased
Connected to 172.23.1.129
Loading 1711088 byte file c3600-i-mz: 
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Verifying checksum...  OK (0xF89A)
Flash device copy took 00:00:18 [hh:mm:ss]

Saving a Copy of an Image on a Server Examples

The following four examples use copy commands to copy image files to a server for storage:

Copy an Image from Flash Memory to an rcp Server Example

Copy an Image from a Partition of Flash Memory to a Server Example

Copying an Image from a Flash Memory File System to an FTP Server Example

Copying an Image from Boot Flash Memory to a TFTP Server Example

Copy an Image from Flash Memory to an rcp Server Example

The following example copies a system image from Flash Memory to an rcp server using the default remote username. Because the rcp server address and filename are not included in the command, the router prompts for it.

Router# copy flash: rcp:

IP address of remote host [255.255.255.255]? 172.16.13.110
Name of file to copy? gsxx
writing gsxx - copy complete

Copy an Image from a Partition of Flash Memory to a Server Example

The following example copies an image from a particular partition of Flash memory to an rcp server using a remote username of netadmin1.

The system will prompt if there are two or more partitions. If the partition entered is not valid, the process terminates. You have the option to enter a partition number, a question mark (?) for a directory display of all partitions, or a question mark and a number (?number) for a directory display of a particular partition. The default is the first partition.

Router# configure terminal
Router# ip rcmd remote-username netadmin1
Router# end
Router# copy flash: rcp:
System flash partition information:
Partition   Size     Used    Free    Bank-Size   State       Copy-Mode
    1       4096K    2048K   2048K   2048K       Read Only   RXBOOT-FLH
    2       4096K    2048K   2048K   2048K       Read/Write  Direct
[Type ?<number> for partition directory; ? for full directory; q to abort]
Which partition? [1] 2

System flash directory, partition 2:
File  Length   Name/status
  1   3459720  master/igs-bfpx.100-4.3
[3459784 bytes used, 734520 available, 4194304 total]
Address or name of remote host [ABC.CISCO.COM]?
Source file name? master/igs-bfpx.100-4.3
Destination file name [master/igs-bfpx.100-4.3]?
Verifying checksum for 'master/igs-bfpx.100-4.3' (file # 1)... OK
Copy 'master/igs-bfpx.100-4.3' from Flash to server
as 'master/igs-bfpx.100-4.3'? [yes/no] yes
!!!!...
Upload to server done
Flash copy took 0:00:00 [hh:mm:ss]

Copying an Image from a Flash Memory File System to an FTP Server Example

The following example copies the file c3600-i-mz from partition 1 of the Flash memory card in slot 0 to an FTP server at IP address 172.23.1.129.

Router# show slot0: partition 1

PCMCIA Slot0 flash directory, partition 1:
File  Length   Name/status
  1   1711088 c3600-i-mz 
[1711152 bytes used, 2483152 available, 4194304 total]

Router# copy slot0:1:c3600-i-mz ftp://myuser:mypass@172.23.1.129/c3600-i-mz
Verifying checksum for '/tftpboot/cisco_rules/c3600-i-mz' (file # 1)...  OK
Copy '/tftpboot/cisco_rules/c3600-i-mz' from Flash to server
  as 'c3700-i-mz'? [yes/no] yes
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Upload to server done
Flash device copy took 00:00:23 [hh:mm:ss]

Copying an Image from Boot Flash Memory to a TFTP Server Example

The following example copies an image from boot Flash memory to a TFTP server:

Router# copy bootflash:file1 tftp://192.168.117.23/file1

Verifying checksum for 'file1' (file # 1)... OK
Copy 'file1' from Flash to server
  as 'file1'? [yes/no]y
!!!!...
Upload to server done
Flash copy took 0:00:00 [hh:mm:ss]

Copying a Configuration File from a Server to the Running Configuration Example

The following example copies and runs a configuration filename host1-confg from the netadmin1 directory on the remote server with an IP address of 172.16.101.101:

Router# copy rcp://netadmin1@172.16.101.101/host1-confg system:running-config

Configure using host1-confg from 172.16.101.101? [confirm]
Connected to 172.16.101.101
Loading 1112 byte file host1-confg:![OK]
Router#
%SYS-5-CONFIG: Configured from host1-config by rcp from 172.16.101.101

Copying a Configuration File from a Server to the Startup Configuration Example

The following example copies a configuration file host2-confg from a remote FTP server to the startup configuration. The IP address is172.16.101.101, the remote username is netadmin1, and the remote password is ftppass.

Router# copy ftp://netadmin1:ftppass@172.16.101.101/host2-confg nvram:startup-config 
Configure using rtr2-confg from 172.16.101.101?[confirm]
Connected to 172.16.101.101
Loading 1112 byte file rtr2-confg:![OK]
[OK]
Router#
%SYS-5-CONFIG_NV:Non-volatile store configured from rtr2-config by  
FTP from 172.16.101.101

Copying the Running Configuration to a Server Example

The following example specifies a remote username of netadmin1. Then it copies the running configuration file named rtr2-confg to the netadmin1 directory on the remote host with an IP address of 172.16.101.101.

Router# configure terminal 
Router(config)# ip rcmd remote-username netadmin1 
Router(config)# end 
Router# copy system:running-config rcp: 
Remote host[]? 172.16.101.101 

Name of configuration file to write [Rtr2-confg]?
Write file rtr2-confg on host 172.16.101.101?[confirm]
Building configuration...[OK]
Connected to 172.16.101.101

Copying the Startup Configuration to a Server Example

The following example copies the startup configuration to a TFTP server:

Router# copy nvram:startup-config tftp:

Remote host[]? 172.16.101.101 

Name of configuration file to write [rtr2-confg]? <cr>
Write file rtr2-confg on host 172.16.101.101?[confirm] <cr>
![OK]

Saving the Current Running Configuration Example

The following example copies the running configuration to the startup configuration. On a Class A Flash file system platform, this command copies the running configuration to the startup configuration specified by the CONFIG_FILE variable.

copy system:running-config nvram:startup-config

The following example shows the warning that the system provides if you try to save configuration information from bootstrap into the system:

Router(boot)# copy system:running-config nvram:startup-config 

Warning: Attempting to overwrite an NVRAM configuration written
by a full system image. This bootstrap software does not support
the full configuration command set. If you perform this command now,
some configuration commands may be lost.
Overwrite the previous NVRAM configuration?[confirm]

Enter no to escape writing the configuration information to memory.

Moving Configuration Files to Other Locations Examples

On some routers, you can store copies of configuration files on a Flash memory device. Five examples follow.

Copying the Startup Configuration to a Flash Memory Device Example

The following example copies the startup configuration file (specified by the CONFIG_FILE environment variable) to a Flash memory card inserted in slot 0:

copy nvram:startup-config slot0:router-confg

Copying the Running Configuration to a Flash Memory Device Example

The following example copies the running configuration from the router to the Flash memory PC card in slot 0:

Router# copy system:running-config slot0:berlin-cfg 

Building configuration...
5267 bytes copied in 0.720 secs

Copying to the Running Configuration from a Flash Memory Device Example

The following example copies the file named ios-upgrade-1 from the Flash memory card in slot 0 to the running configuration:

Router# copy slot0:4:ios-upgrade-1 system:running-config

Copy 'ios-upgrade-1' from flash device
  as 'running-config' ? [yes/no] yes 

Copying to the Startup Configuration from a Flash Memory Device Example

The following example copies the router-image file from the Flash memory to the startup configuration:

copy flash:router-image nvram:startup-config

Copying a Configuration File from one Flash Device to Another Example

The following example copies the file running-config from the first partition in internal Flash memory to the Flash memory PC card in slot 1. The checksum of the file is verified, and its copying time of 30 seconds is displayed.

Router# copy flash: slot1:

System flash

Partition   Size    Used      Free      Bank-Size  State          Copy Mode
  1         4096K   3070K     1025K     4096K      Read/Write     Direct
  2        16384K   1671K    14712K     8192K      Read/Write     Direct

[Type ?<no> for partition directory; ? for full directory; q to abort]
Which partition? [default = 1] 

System flash directory, partition 1: 
File  Length   Name/status
  1   3142748  dirt/images/mars-test/c3600-j-mz.latest 
  2   850      running-config 
[3143728 bytes used, 1050576 available, 4194304 total]

PCMCIA Slot1 flash directory:
File  Length   Name/status
  1   1711088  dirt/images/c3600-i-mz 
  2   850      running-config 
[1712068 bytes used, 2482236 available, 4194304 total]
Source file name? running-config 
Destination file name [running-config]? 
Verifying checksum for 'running-config' (file # 2)...  OK
Erase flash device before writing? [confirm] 
Flash contains files. Are you sure you want to erase? [confirm] 

Copy 'running-config' from flash: device
  as 'running-config' into slot1: device WITH erase? [yes/no] yes 
Erasing device... eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee ...erased
!
 [OK - 850/4194304 bytes]

Flash device copy took 00:00:30 [hh:mm:ss]
Verifying checksum...  OK (0x16)

Copying an Image from the Master RSP Card to the Slave RSP Card Example

The following example copies the router-image file from the Flash memory card inserted in slot 1 of the master RSP card to slot 0 of the slave RSP card in the same router:

copy slot1:router-image slaveslot0:

Related Commands

Command
Description

boot config

Specifies the device and filename of the configuration file from which the router configures itself during initialization (startup).

boot system

Specifies the system image that the router loads at startup.

cd

Changes the default directory or file system.

copy xmodem: flash:

Copies any file from a source to a destination.

copy ymodem: flash:

Copies any file from a source to a destination.

delete

Deletes a file on a Flash memory device.

dir

Displays a list of files on a file system.

erase

Erases a file system.

ip rcmd remote-username

Configures the remote username to be used when requesting a remote copy using rcp.

reload

Reloads the operating system.

show (Flash file system)

Displays the layout and contents of a Flash memory file system.

show bootvar

Displays the contents of the BOOT environment variable, the name of the configuration file pointed to by the CONFIG_FILE environment variable, the contents of the BOOTLDR environment variable, and the configuration register setting.

slave auto-sync config

Turns on automatic synchronization of configuration files for a Cisco 7507 or Cisco 7513 router that is configured for Dual RSP Backup.

verify bootflash:

Either of the identical verify bootflash: or verify bootflash commands replaces the copy verify bootflash command. Refer to the verify command for more information.


copy erase flash

The copy erase flash command has been replaced by the erase flash:command. See the description of the erase command for more information.

copy verify bootflash

The copy verify bootflash command has been replaced by the verify bootflash: command. See the description of the verify command for more information.

copy verify flash

The copy verify flash command has been replaced the verify flash: command. See the description of the verify command for more information.

copy verify

The copy verify command has been replaced by the verify command. See the description of the verify command for more information.

crypto mib topn

To configure TopN sampling parameters, use the crypto mib topn command in global configuration mode. To disable TopN sampling, use the no form of this command.

crypto mib topn [interval seconds] [stop seconds]

no crypto mib topn [interval seconds] [stop seconds]

Syntax Description

interval seconds

(Optional) Frequency of sampling interval, in seconds. In other words, how many minutes should pass between samples.

The allowable range is from 60 to 86400 seconds (60 seconds to 24 hours). The default is 300 seconds (5 minutes). TopnMinSampleInterval: how long (in seconds) between samples?

Defined in the MIB as TopnMinSampleInterval.

stop seconds

(Optional) Time before sampling stops, in seconds. In other words, how many minutes should pass from the time this command is executed before sampling will cease.

The allowable range is from 0 to 604800 seconds. A zero (0) indicates continuous sampling. For any value other than 0, the stop time value must be greater than or equal to the sampling interval value.

Defined in the MIB as TopnStopTime.


Defaults

interval: 300 seconds, stop: continuous sampling (0 seconds)

Command Modes

Global configuration

Command History

Release
Modification

12.1(6)E

This command was introduced.

12.2(9)YE

This command was integrated into Cisco IOS Release 12.2(9)YE.

12.2(9)YO1

This command was integrated into Cisco IOS Release 12.2(9)YO1.

12.2(13)T

This command was integrated into Cisco IOS Release 12.2(13)T.


Usage Guidelines

Use this command to rank objects according to your chosen criteria. You will not see the stop parameter setting after enabling the show running configuration command if the stop parameter is set at a value greater than zero. Otherwise, the current sampling parameters are recorded in the active configuration (if sampling is enabled), and sampling occurs continuously (at the specified intervals) until, and after, the device is rebooted. This command should be disabled if your criteria queries performed by XSM clients (such as VPN Device Manager [VDM]) are not to be processed.

"Crypto MIB" commands apply to characteristics of the IP Security (IPSec) MIBs. TopN (topn) is a special subset of the IPSec MIB Export (IPSMX) interface that provides a set of queries that allows ranked reports of active Internet Key Exchange (Ike) or IPSec tunnels to be obtained depending on certain criteria. While the VPN Device Manager (VDM) application retrieves and presents the data elements defined in the Ike and IPSec MIBs, the application does not use the SNMP interface.

Examples

The following example shows the crypto mib topn command being enabled with an interval frequency of 240 seconds and a designated stop time of 1200 seconds (20 minutes). At that time, the assigned sampling ceases.

crypto mib topn interval 240 stop 1200

Related Commands

Command
Description

xsm

Enables XSM client access to the router.


databits

To set the number of data bits per character that are interpreted and generated by the router hardware, use the databits command in line configuration mode. To restore the default value, use the no form of the command.

databits {5 | 6 | 7 | 8}

no databits

Syntax Description

5

Five data bits per character.

6

Six data bits per character.

7

Seven data bits per character.

8

Eight data bits per character. This is the default.


Defaults

Eight data bits per character

Command Modes

Line configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

The databits line configuration command can be used to mask the high bit on input from devices that generate 7 data bits with parity. If parity is being generated, specify 7 data bits per character. If no parity generation is in effect, specify 8 data bits per character. The other keywords are supplied for compatibility with older devices and generally are not used.

Examples

The following example sets the number of data bits per character to seven on line 4:

Router(config)# line 4
Router(config-line)# databits 7

Related Commands

Command
Description

data-character-bits

Sets the number of data bits per character that are interpreted and generated by the Cisco IOS software.

terminal databits

Changes the number of data bits per character for the current terminal line for this session.

terminal data-character-bits

Sets the number of data bits per character that are interpreted and generated by the Cisco IOS software for the current line and session.


data-character-bits

To set the number of data bits per character that are interpreted and generated by the Cisco IOS software, use the data-character-bits command in line configuration mode. To restore the default value, use the no form of this command.

data-character-bits {7 | 8}

no data-character-bits

Syntax Description

7

Seven data bits per character.

8

Eight data bits per character. This is the default.


Defaults

Eight data bits per character

Command Modes

Line configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

The data-character-bits line configuration command is used primarily to strip parity from X.25 connections on routers with the protocol translation software option. The data-character-bits line configuration command does not work on hard-wired lines.

Examples

The following example sets the number of data bits per character to seven on virtual terminal line (vty) 1:

Router(config)# line vty 1
Router(config-line)# data-character-bits 7

Related Commands

Command
Description

terminal data-character-bits

Sets the number of data bits per character that are interpreted and generated by the Cisco IOS software for the current line and session.


data-pattern

To specify the data pattern in an Service Assurance Agent (SAA) udpEcho operation to test for data corruption, use the data pattern command in SAA RTR configuration mode. To remove the data pattern specification, use the no form of this command.

data-pattern hex-pattern

no data-pattern hex-pattern

Syntax Description

hex-pattern

Hexadecimal sting to use for monitoring the specified operation.


Defaults

The default hex-pattern is ABCD.

Command Modes

SAA RTR configuration

Command History

Release
Modification

12.1(1)T

This command was introduced.


Usage Guidelines

The data-pattern command allows users to specify a alphanumeric character string to verify that operation payload does not get corrupted in either direction (source-to-destination [SD] or destination-to-source [DS]).

For Cisco IOS Release 12.2(11)T, the data-pattern command is applicable to the udpEcho operation only. This command also applies to the Frame Relay operation in 12.2(1)T and later releases.

Examples

The following example specifies 1234ABCD5678 as the data pattern:

Router(config)# rtr 1
Router(config-rtr)# type udpEcho dest-ipaddr 10.0.54.205 dest-port 101
Router(config-rtr)# data-pattern 1234ABCD5678

Related Commands

Command
Description

show rtr collection-statistics

Displays statistical errors for all SAA operations or the specified operation.

show rtr configuration

Displays configuration values including all defaults for all SAA operations or the specified operation.


default-value exec-character-bits

To define the EXEC character width for either 7 bits or 8 bits, use the default-value exec-character-bits command in global configuration mode. To restore the default value, use the no form of this command.

default-value exec-character-bits {7 | 8}

no default-value exec-character-bits

Syntax Description

7

Selects the 7-bit ASCII character set. This is the default.

8

Selects the full 8-bit ASCII character set.


Defaults

7-bit ASCII character set

Command Modes

Global configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Configuring the EXEC character width to 8 bits allows you to add graphical and international characters in banners, prompts, and so on. However, setting the EXEC character width to 8 bits can also cause failures. If a user on a terminal that is sending parity enters the help command, an "unrecognized command" message appears because the system is reading all 8 bits, although the eighth bit is not needed for the help command.

Examples

The following example selects the full 8-bit ASCII character set for EXEC banners and prompts:

Router(config)# default-value exec-character-bits 8

Related Commands

Command
Description

default-value special-character-bits

Configures the flow control default value from a 7-bit width to an 8-bit width.

exec-character-bits

Configures the character widths of EXEC and configuration command characters.

length

Sets the terminal screen length.

terminal exec-character-bits

Locally changes the ASCII character set used in EXEC and configuration command characters for the current session.

terminal special-character-bits

Changes the ASCII character widths to accept special characters for the current terminal line and session.


default-value special-character-bits

To configure the flow control default value from a 7-bit width to an 8-bit width, use the default-value special-character-bits command in global configuration mode. To restore the default value, use the no form of this command.

default-value special-character-bits {7 | 8}

no default-value special-character-bits

Syntax Description

7

Selects the 7-bit character set. This is the default.

8

Selects the full 8-bit character set.


Defaults

7-bit character set

Command Modes

Global configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Configuring the special character width to 8 bits allows you to add graphical and international characters in banners, prompts, and so on.

Examples

The following example selects the full 8-bit special character set:

Router(config)# default-value special-character-bits 8

Related Commands

Command
Description

default-value exec-character-bits

Defines the EXEC character width for either 7 bits or 8 bits.

exec-character-bits

Configures the character widths of EXEC and configuration command characters.

length

Sets the terminal screen length.

terminal exec-character-bits

Locally changes the ASCII character set used in EXEC and configuration command characters for the current session.

terminal special-character-bits

Changes the ASCII character widths to accept special characters for the current terminal line and session.


delete

To delete a file on a Flash memory device or NVRAM, use the delete command in EXEC mode.

delete url [/force | /recursive]

Syntax Description

url

IFS URL of the file to be deleted. Include the filesystem prefix, followed by a colon, and, optionally, the name of a file or directory.

/force

(Optional) Deletes the specified file or directory with prompting you for verification.

Note Use this keyword with caution: the system will not ask you to confirm the file deletion.

/recursive

(Optional) Deletes all files in the specified directory, as well as the directory itself.


Command Modes

EXEC

Command History

Release
Modification

11.0

This command was introduced.


Usage Guidelines

If you attempt to delete the configuration file or image specified by the CONFIG_FILE or BOOTLDR environment variable, the system prompts you to confirm the deletion. Also, if you attempt to delete the last valid system image specified in the BOOT environment variable, the system prompts you to confirm the deletion.

When you delete a file in Flash memory, the software simply marks the file as deleted, but it does not erase the file. To later recover a "deleted" file in Flash memory, use the undelete EXEC command. You can delete and undelete a file up to 15 times.

To permanently delete all files marked "deleted" on a linear Flash memory device, use the squeeze EXEC command.

Examples

The following example deletes the file named test from the Flash card inserted in slot 0:

Router# delete slot0:test 
Delete slot0:test? [confirm]

Related Commands

Command
Description

cd

Changes the default directory or file system.

dir

Displays a list of files on a file system.

show bootvar

Displays the contents of the BOOT environment variable, the name of the configuration file pointed to by the CONFIG_FILE environment variable, the contents of the BOOTLDR environment variable, and the configuration register setting.

squeeze

Permanently deletes Flash files by squeezing a Class A Flash file system.

undelete

Recovers a file marked "deleted" on a Class A or Class B Flash file system.


diag

To perform field diagnostics on a line card, on the Gigabit Route Processor (GRP), on the Switch Fabric Cards (SFCs), and on the Clock Scheduler Card (CSC) in Cisco 12000 series Gigabit Switch Routers (GSRs), use the diag command in privileged EXEC mode. To disable field diagnostics on a line card, use the no form of this command.

diag slot-number [halt | previous | post | verbose [wait] | wait]

no diag slot-number

Syntax Description

slot-number

Slot number of the line card you want to test. Slot numbers range from 0 to 11 for the Cisco 12012 and 0 to 7 for the Cisco 12008 router. Slot numbers for the CSC are 16 and 17, and for the FSC are 18, 19, and 20.

halt

(Optional) Stops the field diagnostic testing on the line card.

previous

(Optional) Displays previous test results (if any) for the line card.

post

(Optional) Initiates an EPROM-based extended power-on self-test (EPOST) only. The EPOST test suite is not as comprehensive as the field diagnostics, and a pass/fail message is the only message displayed on the console.

verbose [wait]

(Optional) Enables the maximum status messages to be displayed on the console. By default, only the minimum status messages are displayed on the console. If you specify the optional wait keyword, the Cisco IOS software is not automatically reloaded on the line card after the test completes.

wait

(Optional) Stops the automatic reloading of the Cisco IOS software on the line card after the completion of the field diagnostic testing. If you use this keyword, you must use the microcode reload slot global configuration command, or manually remove and insert the line card (to power it up) in the slot so that the GRP will recognize the line card and download the Cisco IOS software image to the line card.


Defaults

No field diagnostics tests are performed on the line card.

Command Modes

Privileged EXEC

Command History

Release
Modification

11.2 GS

This command was introduced to support the Cisco 12000 series GSR.


Usage Guidelines

The diag command must be executed from the GRP main console port.

Perform diagnostics on the CSC only if a redundant CSC is in the router.

Diagnostics will stop and ask you for confirmation before altering the router's configuration. For example, running diagnostics on a SFC or CSC will cause the fabric to go from full bandwidth to one-fourth bandwidth. Bandwidth is not affected by GRP or line card diagnostics.

The field diagnostic software image is bundled with the Cisco IOS software and is downloaded automatically from the GRP to the target line card prior to testing.


Caution Performing field diagnostics on a line card stops all activity on the line card. Before the diag EXEC command begins running diagnostics, you are prompted to confirm the request to perform field diagnostics on the line card.

In normal mode, if a test fails, the title of the failed test is displayed on the console. However, not all tests that are performed are displayed. To view all the tests that are performed, use the verbose keyword.

After all diagnostic tests are completed on the line card, a PASSED or TEST FAILURE message is displayed. If the line card sends a PASSED message, the Cisco IOS software image on the line card is automatically reloaded unless the wait keyword is specified. If the line card sends a TEST FAILURE message, the Cisco IOS software image on the line card is not automatically reloaded.

If you want to reload the line card after it fails diagnostic testing, use the microcode reload slot global configuration command.


Note When you stop the field diagnostic test, the line card remains down (that is, in an unbooted state). In most cases, you stopped the testing because you need to remove the line card or replace the line card. If that is not the case, and you want to bring the line card back up (that is, online), you must use the microcode reload global configuration command or power cycle the line card.


If the line card fails the test, the line card is defective and should be replaced. In future releases this might not be the case because DRAM and SDRAM SIMM modules might be field replaceable units. For example, if the DRAM test failed you might only need to replace the DRAM on the line card.

For more information, refer to the Cisco 12000 series installation and configuration guides.

Examples

In the following example, a user is shown the output when field diagnostics are performed on the line card in slot 3. After the line card passes all field diagnostic tests, the Cisco IOS software is automatically reloaded on the card. Before starting the diagnostic tests, you must confirm the request to perform these tests on the line card because all activity on the line card is halted. The total/indiv. timeout set to 600/220 sec. message indicates that 600 seconds are allowed to perform all field diagnostics tests, and that no single test should exceed 220 seconds to complete.


Router# diag 3 

Running Diags will halt ALL activity on the requested slot. [confirm]
Router#
Launching a Field Diagnostic for slot 3
Running DIAG config check
RUNNING DIAG download to slot 3 (timeout set to 400 sec.)
sending cmd FDIAG-DO ALL to fdiag in slot 3
(total/indiv. timeout set to 600/220 sec.)
Field Diagnostic ****PASSED**** for slot 3
Field Diag eeprom values: run 159 fial mode 0 (PASS) slot 3
   last test failed was 0, error code 0
sending SHUTDOWN FDIAG_QUIT to fdiag in slot 3

Board will reload
.
.
.
Router#

In the following example, a user is shown the output when field diagnostics are performed on the line card in slot 3 in verbose mode:

Router# diag 3 verbose 

Running Diags will halt ALL activity on the requested slot. [confirm]
Router#
Launching a Field Diagnostic for slot 3
Running DIAG config check
RUNNING DIAG download to slot 3 (timeout set to 400 sec.)
sending cmd FDIAG-DO ALL to fdiag in slot 3
(total/indiv. timeout set to 600/220 sec.)
FDIAG_STAT_IN_PROGRESS: test #1 R5K Internal Cache
FDIAG_STAT_PASS test_num 1
FDIAG_STAT_IN_PROGRESS: test #2 Sunblock Ordering
FDIAG_STAT_PASS test_num 2
FDIAG_STAT_IN_PROGRESS: test #3 Dram Datapins
FDIAG_STAT_PASS test_num 3
.
.
.
Field Diags: FDIAG_STAT_DONE
Field Diagnostic ****PASSED**** for slot 3
Field Diag eeprom values: run 159 fial mode 0 (PASS) slot 3
   last test failed was 0, error code 0
sending SHUTDOWN FDIAG_QUIT to fdiag in slot 3

Board will reload
.
.
.
Router#

Related Commands

Command
Description

microcode reload

Reloads the Cisco IOS image on a line card on the Cisco 7000 series with RSP7000, Cisco 7500 series, or Cisco 12000 series routers after all microcode configuration commands have been entered.


dir

To display a list of files on a file system, use the dir command in EXEC mode.

dir [/all] [filesystem: ][file-url]

Syntax Description

/all

(Optional) Lists deleted files, undeleted files, and files with errors.

filesystem:

(Optional) File system or directory containing the files to list, followed by a colon.

file-url

(Optional) The name of the files to display on a specified device. The files can be of any type. You can use wildcards in the filename. A wildcard character (*) matches all patterns. Strings after a wildcard are ignored.


Defaults

The default file system is specified by the cd command. When you omit the /all keyword, the Cisco IOS software displays only undeleted files.

Command Modes

EXEC

Command History

Release
Modification

11.0

This command was introduced.

12.3

A timestamp that shows the offset from Coordinated Universal Time (UTC) was added to the dir command display.


Usage Guidelines

Use the show (Flash file system) command to display more detail about the files in a particular file system.

Examples

The following is sample output from the dir command:

Router# dir slot0:

Directory of slot0:/

  1  -rw-     4720148   Dec 29 2003 17:49:36  -08:00 hampton/nitro/c7200-j-mz
  2  -rw-     4767328   Jan 02 2004 18:42:53  -08:00 c7200-js-mz
  5  -rw-         639   Jan 03 2004 12:09:32  -08:00 rally
  7  -rw-         639   Jan 03 2004 12:37:13  -08:00 the_time

20578304 bytes total (3104544 bytes free)

Router# dir /all slot0:

Directory of slot0:/

  1  -rw-     4720148   Dec 15 2003 17:49:36  -08:00 hampton/nitro/c7200-j-mz
  2  -rw-     4767328   Jan 02 2004 18:42:53  -08:00 c7200-js-mz
  3  -rw-     7982828   Jan 02 2004 18:48:14  -08:00 [rsp-jsv-mz]
  4  -rw-         639   Jan 03 2004 12:09:17  -08:00 the_time]
  5  -rw-         639   Jan 03 1994 12:09:32  -08:00 rally
  6  -rw-         639   Jan 03 1994 12:37:01  -08:00 [the_time]
  7  -rw-         639   Jan 03 1994 12:37:13  -08:00 the_time

Table 20 describes the significant fields shown in the output.

Table 20 dir Field Descriptions 

Field
Description

1

Index number of the file.

-rw-

Permissions. The file can be any or all of the following:

d—directory

r—readable

w—writable

x—executable

4720148

Size of the file.

Aug 29 1997 17:49:36

Last modification date.

-08:00

Conversion to local time in hours from Coordinated Universal Time (UTC). In the example, -08:00 indicates that the given time is 8 hours behind UTC or Pacific Standard Time (PST).

hampton/nitro/c7200-j-mz

Filename. Deleted files are indicated by square brackets around the filename.


Related Commands

Command
Description

cd

Changes the default directory or file system.

delete

Deletes a file on a Flash memory device.

undelete

Recovers a file marked "deleted" on a Class A or Class B Flash file system.


disable

To exit privileged EXEC mode and return to user EXEC mode, or to exit to a lower privilege level, enter the disable command in EXEC mode.

disable [privilege-level]

Syntax Description

privilege-level

(Optional) Specific privilege level (other than user EXEC mode).


Command Modes

EXEC

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Up to 16 security levels can be configured using Cisco IOS software. If such levels are configured on a system, using this command with the privilege-level option allows you to exit to a lower security level. If a level is not specified, the user will exit to the user EXEC mode, which is the default.


Note Five EXEC commands are associated with privilege level 0: disable, enable, exit, help, and logout. If you configure a privilege level greater than 0, these five commands will not be included in the command set for that privilege level.


Examples

In the following example, the user enters privileged EXEC mode using the enable command, then exits back to user EXEC mode using the disable command. Note that the prompt for user EXEC mode is >, and the prompt for privileged EXEC mode is #.

Router> enable
Password: <letmein>
Router# disable
Router>

Related Commands

Command
Description

enable

Enables higher privilege level access, such as privileged EXEC mode.


disconnect-character

To define a character to disconnect a session, use the disconnect-character command in line configuration mode. To remove the disconnect character, use the no form of this command.

disconnect-character ascii-number

no disconnect-character

Syntax Description

ascii-number

Decimal representation of the session disconnect character.


Defaults

No disconnect character is defined.

Command Modes

Line configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

See the"ASCII Character Set and Hex Values" appendix for a list of ASCII characters.

The Break character is represented by zero; NULL cannot be represented.

To use the session-disconnect character in normal communications, precede it with the escape character.

Examples

The following example defines the disconnect character for virtual terminal line 4 as Escape, which is decimal character 27:

Router(config)# line vty 4
Router(config-line)# disconnect-character 27

discover (cns)

To define the interface parameters within a Cisco Networking Services (CNS) connect profile for connecting to the CNS configuration engine, use the discover command in CNS connect configuration mode. To disable this functionality, use the no form of this command.

discover {line line-type | controller controller-type | interface [interface-type] | dlci [subinterface subinterface-number]}

no discover {line line-type | controller controller-type | interface [interface-type] | dlci [subinterface subinterface-number]}

Syntax Description

line line-type

Line type to be used for connecting to the CNS configuration engine.

When the line line-type keyword and argument are specified, all the lines that create an interface that match the specified line-type argument are discovered.

The CNS connect templates associated with the discover line line-type command are applied in line configuration mode.

controller controller-type

Controller type to be used for connecting to the CNS configuration engine.

When the controller controller-type keyword and argument are specified, all the controllers that create an interface that match the specified controller-type argument are discovered.

The CNS connect templates associated with the discover controller controller-type command are applied in controller configuration mode.

interface [interface-type]

Interface type to be used for connecting to the CNS configuration engine.

If the discover interface interface-type command is the first discover command configured in a CNS connect profile, then the interfaces that match the specified interface-type argument are discovered.

If the discover interface interface-type command is configured after the discover line line-type or discover controller controller-type commands in a CNS connect profile, then the specified interface-type argument is ignored. Instead, the CNS connect templates associated with the discover interface command are applied to all the interfaces associated with the preceding discover line line-type or discover controller controller-type commands.

The CNS connect templates associated with the discover interface interface-type command are applied in interface configuration mode.

dlci

Active DLCIs to be used for connecting to the CNS configuration engine.

When this keyword is defined, all the active DLCIs are discovered on the interface specified by the preceding discover interface interface-type command. A Frame Relay LMI message will return a list of active DLCIs.

Active DLCIs can only be discovered on interfaces configured with Frame Relay. Therefore, the location of the discover dlci command in a CNS connect profile is important. It must be entered after the interfaces have been configured with Frame Relay.

The CNS connect templates associated with the discover dlci command are applied in subinterface (point-to-point) configuration mode.

Defines the CNS connect variable ${dlci} and ${next-hop}.

Note Any Cisco IOS command that requires knowledge of the active DLCIs must be configured after the discover dlci command.

subinterface subinterface-number

(Optional) Point-to-point subinterface number used to perform a search for active DLCIs. If the number is not specified, the default value is 9999.


Defaults

No interface parameters within a CNS connect profile are defined.

Command Modes

CNS connect configuration

Command History

Release
Modification

12.3(2)XF

This command was introduced.

12.3(8)T

This command was integrated into Cisco IOS Release 12.3(8)T.

12.3(9)

This command was integrated into Cisco IOS Release 12.3(9). The dlci subinterface subinterface-number keywords and argument, and the CNS connect variable ${dlci} are not supported in this release.


Usage Guidelines

First use the cns connect command to enter CNS connect configuration mode and define the parameters of a CNS connect profile for connecting to the CNS configuration engine. Then use the following CNS connect commands to create a CNS connect profile:

discover

template

A CNS connect profile specifies the discover commands and associated template commands that are to be applied to a router's configuration. The first discover command in a CNS connect profile defines the scope of the interfaces for which to search and use to perform the ping iterations for connecting to the CNS configuration engine. Subsequent discover commands limit this scope. The search is based on discovering all the interfaces that match the specified line, controller, or interface type. The search is case-insensitive and allows for abbreviations. For example, the discover interface Serial, discover interface Ser, discover interface serial, and discover interface ser commands all match the serial interface.

Each discover command must have at least one unique CNS connect template associated with it. Specifically, the template command must be configured after configuring the discover command. The discover command specifies the configuration mode in which the CNS connect templates (specified by the template command that is associated with the discover command) are to be applied. When multiple discover and template commands are configured in a CNS connect profile, they are processed in the order in which they are entered.

Table 21 provides a summary of the interface parameters that can be defined using the discover command.

Table 21 Summary of the discover Commands

discover Command
Description
Associated CNS Connect Variable
Configuration Mode in Which CNS Connect Templates Are Applied
Prerequisite discover Command
Required Subsequent discover Command

discover line line-type

Discovers all the lines that create an interface that match the specified line-type argument.

${line}

Line

discover interface interface-type

discover controller controller-type

Discovers all the controllers that create an interface that match the specified controller-type argument.

${controller}

Controller

discover interface interface-type

discover interface [interface-type]

If this is the first discover command configured, then all the interfaces that match the specified interface-type argument are discovered.

If configured after the discover line line-type or discover controller controller-type commands, then the specified interface-type argument is ignored.

${interface}

${next-hop}

Interface

discover dlci [subinterface subinterface-number]

Discovers all active DLCIs on the interface specified by the preceding discover interface command.

${dlci}

${next-hop}

Subinterface (point-to-point)

discover interface interface-type


CNS connect variables can be used as placeholders within a CNS connect template configuration. Each variable is defined by an associated discover command (see Table 21 and Table 22). Before a CNS connect template that contains these variables is applied to a router's configuration, the variables are replaced by the values defined by their associated discover command. For example, if the discover interface serial command was configured, and you were able to connect to the CNS configuration engine using Serial0/0, then the cli ip route 0.0.0.0 0.0.0.0 ${interface} command would generate the cli ip route 0.0.0.0 0.0.0.0 serial0/0 command.

Table 22 Summary of the CNS Connect Variables

Variable
Description

${line}

The line type defined by the associated discover line line-type command.

${controller}

The controller type defined by the associated discover controller controller-type command.

${interface}

The interface type defined by the associated discover interface command.

${dlci}

The active DLCI defined by the associated discover dlci command.

${next-hop}

The next hop interface. This variable is identical to the ${interface} variable unless the discover dlci command has been configured. In this case, the ${next-hop} variable is identical to the ${interface}.{subinterface} variable, where the {subinterface} variable is specified by the discover dlci command.

The ${next-hop} variable should only be used in the CNS connect templates after the last discover command has been entered.

A typical use of this variable is to allow the default IP route to be configured to send traffic towards the CNS configuration engine. Note that the CNS configuration engine may not be on the same LAN as the router. Therefore, configuring a route to the CNS configuration engine may require deployment-specific knowledge. Common practice is to define a default route to the interface using the ip route command (for example, cli ip route 0.0.0.0 0.0.0.0 ${next-hop}).

$$

A literal substitution of the $ symbol.



Note Effective with Cisco IOS Releases 12.3(8)T and 12.3(9), the & variable is replaced by the ${interface} variable.


Examples

The following example shows how to create a CNS connect profile named EG:

Router (config)# cns connect EG
Router (config-cns-conn)# discover controller T1
Router (config-cns-conn)# template timeslot-1
Router (config-cns-conn)# discover interface
Router (config-cns-conn)# template frame
Router (config-cns-conn)# exit
Router (config)#

In this example, the following sequence of events occur for each T1 controller when the cns connect EG command is processed:

1. Enter controller configuration mode and apply all commands in the timeslot-1 template to the router's configuration.

2. For each interface associated with each T1 controller:

a. Enter interface configuration mode and apply all commands in the frame template to the router's configuration.

b. Try to ping the CNS configuration engine.

c. If the ping is successful, then download pertinent configuration information from the CNS configuration engine and exit. The cns connect EG command has completed its process.

d. If the ping is unsuccessful, enter interface configuration mode and remove all commands in the frame template from the router's configuration.

3. Enter controller configuration mode and remove all commands in the timeslot-1 template from the router's configuration. The cns connect EG command has failed to retrieve any configuration information from the CNS configuration engine.

Related Commands

Command
Description

cli (cns)

Specifies the command lines of a CNS connect template.

cns connect

Enters CNS connect configuration mode and defines the parameters of a CNS connect profile for connecting to the CNS configuration engine.

cns template connect

Enters CNS template connect configuration mode and defines the name of a CNS connect template.

template (cns)

Specifies a list of CNS connect templates within a CNS connect profile to be applied to a router's configuration.


dispatch-character

To define a character that causes a packet to be sent, use the dispatch-character command in line configuration mode. To remove the definition of the specified dispatch character, use the no form of this command.

dispatch-character ascii-number1 [ascii-number2 . . . ascii-number]

no dispatch-character ascii-number1 [ascii-number2 . . . ascii-number]

Syntax Description

ascii-number1

Decimal representation of the desired dispatch character.

ascii-number2 . . . ascii-number

(Optional) Additional decimal representations of characters. This syntax indicates that you can define any number of characters as dispatch characters.


Defaults

No dispatch character is defined.

Command Modes

Line configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

See the "ASCII Character Set and Hex Values" appendix for a list of ASCII characters.

The dispatch-character command defines one or more dispatch characters that cause a packet to be sent even if the dispatch timer has not expired. Use of a dispatch character causes the Cisco IOS software to attempt to buffer characters into larger-sized packets for transmission to the remote host.

Enable the dispatch-character command from the session that initiates the connection, not from the incoming side of a streaming Telnet session.

This command can take multiple arguments, so you can define any number of characters as dispatch characters.

Examples

The following example defines the Return character (decimal 13) as the dispatch character for virtual terminal line (vty) line 4:

Router(config)# line vty 4
Router(config-line)# dispatch-character 13

Related Commands

Command
Description

dispatch-machine

Specifies an identifier for a TCP packet dispatch state machine on a particular line.

dispatch-timeout

Sets the character dispatch timer.

state-machine

Specifies the transition criteria for the state of a particular state machine.

terminal dispatch-character

Defines a character that causes a packet to be sent for the current session.


dispatch-machine

To specify an identifier for a TCP packet dispatch state machine on a particular line, use the dispatch-machine command in line configuration mode. To disable a state machine on a particular line, use the no form of this command.

dispatch-machine name

no dispatch-machine

Syntax Description

name

Name of the state machine that determines when to send packets on the asynchronous line.


Defaults

No dispatch state machine identifier is defined.

Command Modes

Line configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

When the dispatch-timeout command is specified, a packet being built will be sent when the timer expires, and the state will be reset to zero.

Any dispatch characters specified using the dispatch-character command are ignored when a state machine is also specified.

If a packet becomes full, it will be sent regardless of the current state, but the state will not be reset. The packet size depends on the traffic level on the asynchronous line and the dispatch-timeout value. There is always room for 60 data bytes. If the dispatch-timeout value is greater than or equal to 100 milliseconds, a packet size of 536 (data bytes) is allocated.

Examples

The following example specifies the name linefeed for the state machine:

Router(config)# state-machine linefeed 0 0 9 0
Router(config)# state-machine linefeed 0 11 255 0
Router(config)# state-machine linefeed 0 10 10 transmit
Router(config)# line 1
Router(config-line)# dispatch-machine linefeed

Related Commands

Command
Description

dispatch-character

Defines a character that causes a packet to be sent.

dispatch-timeout

Sets the character dispatch timer.

state-machine

Specifies the transition criteria for the state of a particular state machine.


dispatch-timeout

To set the character dispatch timer, use the dispatch-timeout command in line configuration mode. To remove the timeout definition, use the no form of this command.

dispatch-timeout milliseconds

no dispatch-timeout

Syntax Description

milliseconds

Integer that specifies the number of milliseconds (ms) that the Cisco IOS software waits after putting the first character into a packet buffer before sending the packet. During this interval, more characters can be added to the packet, which increases the processing efficiency of the remote host.


Defaults

No dispatch timeout is defined.

Command Modes

Line configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Use this command to increase the processing efficiency for the remote host.

The dispatch-timeout line configuration command causes the software to buffer characters into packets for transmission to the remote host. The Cisco IOS software sends a packet a specified amount of time after the first character is put into the buffer. You can use the dispatch-timeout and dispatch-character line configuration commands together. In this case, the software dispatches a packet each time the dispatch character is entered, or after the specified dispatch timeout interval, depending on which condition is met first.


Note The system response time might appear intermittent if the timeout interval is greater than 100 milliseconds and remote echoing is used. For lines with a reverse-Telnet connection, use a dispatch-timeout value less than 10 milliseconds.


Examples

The following example sets the dispatch timer to 80 milliseconds for virtual terminal line (vty) lines 0 through 4:

Router(config)# line vty 0 4
Router(config-line)# dispatch-timeout 80

Related Commands

Command
Description

dispatch-character

Defines a character that causes a packet to be sent.

dispatch-machine

Specifies an identifier for a TCP packet dispatch state machine on a particular line.

state-machine

Specifies the transition criteria for the state of a particular state machine.

terminal dispatch-timeout

Sets the character dispatch timer for the current session.


distributions-of-statistics-kept

To set the number of statistic distributions kept per hop during a SSA operation, use the distributions-of-statistics-kept command in SAA RTR configuration mode. To return to the default value, use the no form of this command.

distributions-of-statistics-kept size

no distributions-of-statistics-kept

Syntax Description

size

Number of statistic distributions kept per hop. The default is 1 distribution.


Defaults

1 distribution

Command Modes

SAA RTR configuration

Command History

Release
Modification

11.2

This command was introduced.


Usage Guidelines

In most situations, you do not need to change the statistic distribution size for the SAA. Only change the size when distributions are needed (for example, when performing statistical modeling of your network).


Note Increasing the distributions also increases the RAM usage. The total number of statistics distributions captured will be: the value of distributions-of-statistics-kept times the value of hops-of-statistics-kept times the value of paths-of-statistics-kept times the value of hours-of-statistics-kept.


When the number of distributions reaches the size specified, no further distribution information is stored.

Examples

The following example sets the distribution to 5 and the distribution interval to 10 ms. This setting means that the first distribution will contain statistics from 0 to 9 ms, the second distribution will contain statistics from 10 to 19 ms, the third distribution will contain statistics from 20 to 29 ms, the fourth distribution will contain statistics from 30 to 39 ms, and the fifth distribution will contain statistics from 40 ms to infinity.

Router(config)# rtr 1
Router(config-rtr)# type echo protocol ipIcmpEcho 172.16.161.21
Router(config-rtr)# distributions-of-statistics-kept 5
Router(config-rtr)# statistics-distribution-interval 10

Related Commands

Command
Description

hops-of-statistics-kept

Sets the number of hops for which statistics are maintained per path for the SAA operation.

hours-of-statistics-kept

Sets the number of hours for which statistics are maintained for the SAA operation.

paths-of-statistics-kept

Sets the number of paths for which statistics are maintained per hour for the SAA operation.

rtr

Specifies an SAA operation and enters SAA RTR configuration mode.

statistics-distribution-interval

Sets the time interval for each statistics distribution kept for SAA.


do

To execute an EXEC-level command from global configuration mode or any configuration submode, use the do command in any configuration mode.

do command

Syntax Description

command

The EXEC command to be executed.


Defaults

No default behavior or values.

Command Modes

All configuration modes

Command History

Release
Modification

12.2(8)T

This command was introduced.


Usage Guidelines

Use this command to execute EXEC commands (such as show, clear, and debug commands) while configuring your routing device. After the EXEC command is executed, the system will return to the configuration mode you were using.


Tip This command can be useful for saving your configuration to the startup-config file without having to return to the EXEC mode (do copy running-config startup-config), or for checking the status of a feature (using a do show command) while configuring the feature.


Examples

In the following example, the show interfaces EXEC command is issued from within global configuration mode:

Router(config)# do show interfaces serial 3/0

Serial3/0 is up, line protocol is up
  Hardware is M8T-RS232
  MTU 1500 bytes, BW 1544 Kbit, DLY 20000 usec, rely 255/255, load 1/255
  Encapsulation HDLC, loopback not set, keepalive set (10 sec)
  Last input never, output 1d17h, output hang never
  Last clearing of "show interface" counters never
.
.
.
Router(config)#

In the following example, the clear vpdn tunnel EXEC command is issued from within VPDN configuration mode:

Router(config-vpdn)# do clear vpdn tunnel
Router(config-vpdn)# 

downward-compatible-config

To generate a configuration that is compatible with an earlier Cisco IOS release, use the downward-compatible-config command in global configuration mode. To disable this function, use the no form of this command.

downward-compatible-config version

no downward-compatible-config

Syntax Description

version

Cisco IOS release number, not earlier than Release 10.2.


Defaults

Disabled

Command Modes

Global configuration

Command History

Release
Modification

11.1

This command was introduced.


Usage Guidelines

In Cisco IOS Release 10.3, IP access lists changed format. Use the downward-compatible-config command to regenerate a configuration in a format prior to Release 10.3 if you are going to downgrade from your software version to version 10.2 or 10.3. The earliest version value this command accepts is 10.2.

When this command is configured, the router attempts to generate a configuration that is compatible with the specified version. Note that this command affects only IP access lists.

Under some circumstances, the software might not be able to generate a fully backward-compatible configuration. In such a case, the software issues a warning message.

Examples

The following example generates a configuration file compatible with Cisco IOS Release 10.2 access lists:

Router(config)# downward-compatible-config 10.2

Related Commands

Command
Description

access-list (extended)

Provides extended access lists that allow more detailed access lists.

access-list (standard)

Defines a standard XNS access list.


editing

To reenable Cisco IOS enhanced editing features for a particular line after they have been disabled, use the editing command in line configuration mode. To disable these features, use the no form of this command.

editing

no editing

Syntax Description

This command has no arguments or keywords.

Defaults

Enabled

Command Modes

Line configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Enhanced editing features are enabled by default. However, there may be situations in which you need to disable these features. The no form of this command disables these enhanced editing features, and the plain form of the command can be used to reenable these features.

Table 23 provides a description of the keys used to enter and edit commands when the editing features are enabled. Ctrl indicates the Control key, which must be pressed simultaneously with its associated letter key. Esc indicates the Escape key, which must be pressed first, followed by its associated letter key. A comma is used in the following table to indicate a key sequence (the comma key should not be pressed). Keys are not case sensitive. Many letters used for CLI navigation and editing were chosen to provide an easy way of remembering their functions. In the following table (Table 23), characters are bolded in the "Function Summary" column to indicate the relation between the letter used and the function.

Table 23 Command Editing Keys and Functions 

Keys
Function Summary
Function Details

Tab

Complete command

Completes a partial command name entry. When you enter a unique set of characters and press the Tab key, the system completes the command name. If you enter a set of characters that could indicate more than one command, the system beeps to indicate an error.
To view the commands which match the set of characters you have entered, enter a question mark (?) immediately following the partial command (no space). The CLI will then list the commands that begin with that string.

Return
(at the command line)

Execute

Executes the command.

Return
(at the --More-- prompt)

Continue

Displays the next line of output.

Space Bar
(at the --More-- prompt)

Continue

Displays the next screen of output. The amount of output you see will depend on the screen depth setting of your terminal.

Delete or Backspace

Backspace

Erases the character to the left of the cursor.

Left Arrow1 or Ctrl-B

Back character

Moves the cursor one character to the left.
When you enter a command that extends beyond a single line, you can press the Left Arrow or Ctrl-B keys repeatedly to scroll back toward the system prompt and verify the beginning of the command entry.

Right Arrow1 or Ctrl-F

Forward character

Moves the cursor one character to the right.

Esc, B

Back word

Moves the cursor back one word.

Esc, F

Forward word

Moves the cursor forward one word.

Ctrl-A

Beginning of line

Moves the cursor to the beginning of the line.

Ctrl-E

End of line

Moves the cursor to the end of the command line.

Ctrl-D

Delete character

Deletes the character at the cursor.

Esc, D

Delete next word

Deletes from the cursor to the end of the word.

Ctrl-W

Delete previous word

Deletes the word to the left of the cursor.

Ctrl-K

Delete line forward

Deletes all characters from the cursor to the end of the command line.

Ctrl-U or Ctrl-X

Delete line backward

Deletes all characters from the cursor back to the beginning of the command line.

Ctrl-T

Transpose characters

Transposes the character to the left of the cursor with the character located at the cursor.

Ctrl-R or Ctrl-L

Redisplay line

Redisplays the system prompt and command line.

Ctrl-V or Esc, Q

Ignore editing

Inserts a code to indicate to the system that the keystroke immediately following should be treated as a command entry, not as an editing key.

Up Arrow1 or Ctrl-P

Previous command

Recalls commands in the history buffer, beginning with the most recent command. Repeat the key sequence to recall successively older commands.

Down Arrow1 or Ctrl-N (next)

Next command

Returns to more recent commands in the history buffer (after recalling commands with the Up Arrow or Ctrl-P). Repeat the key sequence to recall successively more recent commands.

Ctrl-Y

Recall last deleted command

Recalls the most recent entry in the delete buffer. The delete buffer contains the last ten items you have deleted or cut. Ctrl-Y can be used in conjunction with Esc Y.

Esc, Y

Recall next deleted command

Recalls the next entry in the delete buffer. The delete buffer contains the last ten items you have deleted. Press Ctrl-Y first to recall the most recent entry. Then press Esc Y up to nine times to recall the remaining entries in the buffer. If you bypass an entry, continue to press Esc Y to cycle back to it.

Esc, C

Capitalize word

Capitalizes the word from the cursor to the end of the word.

Esc, U

Make word uppercase

Changes all letters from the cursor to the next space on the line appear in uppercase letters.

Esc, L

Make word lowercase

Changes the word to lowercase from the cursor to the end of the word.

1 The arrow keys function only with ANSI-compatible terminals.


Examples

In the following example, enhanced editing mode is disabled on line 3:

Router(config)# line 3
Router(config-line)# no editing

Related Commands

Command
Description

terminal editing

Controls CLI enhanced editing feature for the current terminal session.


enable

To enter privileged EXEC mode, or any other security level set by a system administrator, use the enable command in EXEC mode.

enable [privilege-level]

Syntax Description

privilege-level

(Optional) Privilege level at which to log in.


Defaults

Privilege-level 15 (privileged EXEC)

Command Modes

EXEC

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

Entering privileged EXEC mode enables the use of privileged commands. Because many of the privileged commands set operating parameters, privileged access should be password-protected to prevent unauthorized use. If the system administrator has set a password with the enable password global configuration command, you are prompted to enter it before being allowed access to privileged EXEC mode. The password is case sensitive.

If an enable password has not been set, enable mode only can be accessed through the console connection.

Security levels can be set by an administrator using the enable password and privilege level commands. Up to 16 privilege levels can be specified, using the numbers 0 through 15. Using these privilege levels, the administrator can allow or deny access to specific commands. Privilege level 0 is associated with user EXEC mode, and privilege level 15 is associated with privileged EXEC mode.

For more information on defined privilege levels, see the Cisco IOS Security Configuration Guide and the Cisco IOS Security Command Reference publications.

If a level is not specified when entering the enable command, the user will enter the default mode of privileged EXEC (level 15).

Examples

In the following example, the user enters privileged EXEC mode using the enable command. The system prompts the user for a password before allowing access to the privileged EXEC mode. The password is not printed to the screen. The user then exits back to user EXEC mode using the disable command. Note that the prompt for user EXEC mode is >, and the prompt for privileged EXEC mode is #.

Router> enable
Password: <letmein>
Router# disable
Router>

Related Commands

Command
Description

disable

Exits from privileged EXEC mode to user EXEC mode, or, if privilege levels are set, to the specified privilege level.

enable password

Sets a local password to control access to various privilege levels.

privilege level (global)

Sets a privilege level for a command.

privilege level (line)

Sets a privilege level for a command for a specific line.


end

To end the current configuration session and return to privileged EXEC mode, use the end command in global configuration mode.

end

Syntax Description

This command has no arguments or keywords.

Defaults

No default behavior or values.

Command Modes

Global configuration

Command History

Release
Modification

10.0

This command was introduced.


Usage Guidelines

This command will bring you back to privileged EXEC mode regardless of what configuration mode or configuration submode you are in.


Note This global configuration command can be used in any configuration mode.


Use this command when you are done configuring the system and you want to return to EXEC mode to perform verification steps.

Examples

In the following example, the end command is used to exit from ALPS ASCU configuration mode and return to privileged EXEC mode. A show command is used in privileged EXEC mode to verify the configuration.

Router# configure terminal
Router(config)# interface serial 1:1 
Router(config-if)# alps ascu 4B 
Router(config-alps-ascu)# end
Router# show interface serial 1:1

Related Commands

Command
Description

exit (global)

Exits from the current configuration mode.


enhanced-history

To enable enhanced history gathering for an Service Assurance Agent (SAA) operation, use the enhanced-history command in one of the SAA RTR configuration modes.

enhanced-history interval seconds buckets number-of-buckets

Syntax Description

interval seconds

The number of seconds enhanced history should be gathered in each bucket. When this time expires, enhanced history statistics are gathered in a new bucket. The default is 900 seconds (15 minutes).

buckets number-of-buckets

The number of history buckets that should be retained in system memory. When this number is reached, statistic gathering for the operation ends. The default is 100 buckets.


Defaults

For SLM operations, 900 seconds and 100 buckets

Command Modes

SAA Echo operation configuration (config-rtr-echo)

SAA UDP Echo operation configuration (config-rtr-udp)

SAA TCP operation configuration (config-rtr-tcp)

SAA Jitter operation configuration (config-rtr-jitter)

SAA SLM Controller/Interface configuration (config-rtr-slm-if)

SAA SLM ATM Interface configuration (config-rtr-slm-atm-if)

SAA SLM Frame Relay Interface configuration (config-rtr-slm-fr-if)

SAA SLM ATM Circuit configuration (config-rtr-slm-atm-dlci)

SAA SLM Frame Relay Circuit configuration (config-rtr-slm-fr-dlci)

Command History

Release
Modification

12.2(11)T

This command was introduced.

12.3(1)

This command was made available for SAA SLM Frame Relay configuration modes.


Usage Guidelines

Performance statistics are stored in "buckets" which keep the accumulated data separate from each other. Each bucket consists of data accumulated over the specified interval. For Frame Relay SLM and ATM SLM operations, each bucket consists of 15 minutes (900 seconds) worth of statistics. The following line will be written to the configuration:

enhanced-history interval 900 buckets 100

Regardless of the values entered for seconds and number-of-buckets, the default of value of a 900-second interval and 100 history buckets will be used. Your input is overridden in the Frame Relay operations so that complete SLM statistics can be provided.

Examples

In the following example SAA operation 3 is configured with the standard enhanced history characteristics:

Router(config)# rtr slm frame-relay statistics 
Router(config)# rtr 3
Router(config-rtr)# type slm frame-relay pvc interface Serial0:0 111 
Router(config-rtr-slm-fr-dlci)# enhanced-history interval 900 buckets 100 
Router(config-rtr-slm-fr-dlci)# exit 
Router(config)# rtr schedule 3 start-time now life forever 
Router(config)# end 
Router#

Related Commands

Command
Description

type slm controller

Specifies that the SAA operation is an SLM controller operation, and specifies the controller that the operation should be run on.

type slm frame-relay interface

Specifies that the SAA operation is an SLM FR interface operation, and specifies the interface that the operation should be run on.

type slm frame-relay pvc interface

Specifies that the SAA operation is an SLM FR circuit operation, and specifies the interface and DLCI number that the operation should be run on.

type slm interface

Specifies that the SAA operation is an SLM interface operation, and specifies the interface that the operation should be run on.


erase

To erase a file system, use the erase command in EXEC mode.

erase [/no-squeeze] filesystem:

Syntax Description

/no-squeeze

Disables the squeeze operation to conserve memory and makes the erase option compatible with older filesystems.

filesystem:

File system name, followed by a colon. For example, flash: or nvram:


Command Modes

EXEC

Command History

Release
Modification

11.0

This command was introduced.

12.2(11)T

The /no-squeeze option was added for the Cisco 1700 series.


Usage Guidelines

The erase nvram: command replaces the write erase command and the erase startup-config command.

When a file system is erased, none of the files in the file system can be recovered.

The erase command can be used on both Class B and Class C Flash file systems only. To reclaim space on Flash file systems after deleting files using the delete command, you must use the erase command. This command erases all of the files in the Flash file system.

If the flash memory is partitioned, all partitions must be removed before using the erase command.

Class A Flash file systems cannot be erased. You can delete individual files using the delete EXEC command and then reclaim the space using the squeeze EXEC command. You can use the format EXEC command to format the Flash file system.

On Class C Flash file systems, space is dynamically reclaimed when you use the delete command. You can also use either the format or erase command to reinstalled a Class C Flash file system.

The erase nvram: command erases NVRAM. On Class A file system platforms, if the CONFIG_FILE variable specifies a file in Flash memory, the specified file will be marked "deleted."

The /no-squeeze option is available on systems with small amounts of Flash memory in order to conserve memory. When a squeeze operation is performed, the last two erase sectors are permanently reservered for the squeeze logs and squeeze buffer. Disabling the squeeze operation keeps these memory sectors free. If any sectors using squeeze data are detected, they will be erased when this option is used.

Examples

The following example erases the NVRAM, including the startup configuration located there:

erase nvram:

The following example erases all of partition 2 in internal Flash memory:

Router# erase flash:2   

System flash directory, partition 2:
File  Length   Name/status
  1   1711088  dirt/images/c3600-i-mz  
[1711152 bytes used, 15066064 available, 16777216 total]

Erase flash device, partition 2? [confirm]
Are you sure? [yes/no]: yes
Erasing device... eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee ...erased

The following example erases Flash memory when Flash is partitioned, but no partition is specified in the command:

Router# erase flash:

System flash partition information:
Partition   Size     Used    Free    Bank-Size   State       Copy-Mode
    1       4096K    2048K   2048K   2048K       Read Only   RXBOOT-FLH
    2       4096K    2048K   2048K   2048K       Read/Write  Direct

[Type ?<no> for partition directory; ? for full directory; q to abort]
Which partition? [default = 2]

The system will prompt only if there are two or more read/write partitions. If the partition entered is not valid or is the read-only partition, the process terminates. You can enter a partition number, a question mark (?) for a directory display of all partitions, or a question mark and a number (?number) for directory display of a particular partition. The default is the first read/write partition.

System flash directory, partition 2:
File  Length   Name/status
  1   3459720  master/igs-bfpx.100-4.3
[3459784 bytes used, 734520 available, 4194304 total]

Erase flash device, partition 2? [confirm] <Return>

Related Commands

Command
Description

boot config

Specifies the device and filename of the configuration file from which the router configures itself during initialization (startup).

delete

Deletes a file on a Flash memory device.

more nvram:startup-config

Displays the startup configuration file contained in NVRAM or specified by the CONFIG_FILE environment variable.

show bootvar

Displays the contents of the BOOT environment variable, the name of the configuration file pointed to by the CONFIG_FILE environment variable, the contents of the BOOTLDR environment variable, and the configuration register setting.

undelete

Recovers a file marked "deleted" on a Class A or Class B Flash file system.


erase bootflash

The erase bootflash: and erase bootflash commands have identical functions. See the description of the erase command in this chapter for more information.

escape-character

To define a system escape character, use the escape-character command in line configuration mode. To set the escape character to Break, use the no or default form of this command.

escape-character {break | char | default | none | soft}

no escape-character [soft]

default escape-character [soft]

Syntax Description

break

Sets the escape character to Break. Note that the Break key should not be used as an escape character on a console terminal.

char

Character (for example, !) or its ASCII decimal representation (integer in the range of 0 to 255) to be used as the escape character.

default

Sets the escape key sequence to the default of Ctrl-^, X.

none

Disables escape entirely.

soft

Sets an escape character that will wait until pending input is processed before it executes.


Defaults

The default escape key sequence is Ctrl-Shift-6 (Ctrl-^) or Ctrl-Shift-6, X (^^X). The X is generally only required for modem connections.

The default escape-character command sets the escape character to Break (the default setting for Break is Ctrl-C).

Command Modes

Line configuration

Command History

Release
Modification

10.0

This command was introduced.

11.3

The soft keyword was added.


Usage Guidelines

See the "ASCII Character Set and Hexidecimal Values" appendix for a list of ASCII characters.

The escape character (or key sequence) suspends any actively running processes and returns you to privileged EXEC mode or, if a menu is being used, to the system menu interface. The escape character is used for interrupting or aborting a process started by previously executed command. Examples of processes from which you can escape include Domain-Name lookup, ping, trace, and Telnet sessions initiated from the device to which you are connected.

To view the current setting of the escape sequence for a line, use the show line command followed by the specific line identifier (for example, show line 0, or show line console). The default escape sequence for a line is often displayed as ^^X . The first caret symbol represents the Control (Ctrl) key, the second caret symbol is literal (Shift-6), and the X is literal (for most systems, the X is not required).

To set the escape key for the active terminal line session, use the terminal escape-character command.

The Break key cannot be used as an escape character on a console terminal because the Cisco IOS software interprets Break as an instruction to halt the system. Depending upon the configuration register setting, break commands issued from the console line either will be ignored or cause the server to shut down.

To send an escape sequence over a Telnet connection, press Ctrl-Shift-6 twice.

The escape-character soft form of this command defines a character or character sequence that will cause the system to wait until pending input is processed before suspending the current session. This option allows you to program a key sequence to perform multiple actions, such as using the F1 key to execute a command, then execute the escape function after the first command is executed.

The following restrictions apply when using the soft keyword:

The length of the logout sequence must be 14 characters or fewer.

The soft escape character cannot be the same as the generic Cisco escape character, Break, or the characters b, d, n, or s.

The soft escape character should be an ASCII value from 1 to 127. Do not use the number 30.

Examples

The following example sets the escape character for the console line to the keyboard entry Ctrl-P, which is represented by the ASCII decimal value of 16:

Router(config)# line console
Router(config-line)# escape-character 16

The following example sets the escape character for line 1 to !, which is represented in the configuration file as the ASCII number 33:

Router(config)# line 1
Router(config-line)# escape-character !
Router(config-line)# end
Router# show running-config
Building configuration...
.
.
.
line 1
 autoselect during-login
 autoselect ppp
 modem InOut
 transport preferred none
 transport output telnet
 escape-character 33
.
.
.

Related Commands

Command
Description

show line

Displays information about the specified line connection, or all the lines.

terminal escape-character

Sets the escape character for the current terminal line for the current session.