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