The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table at the end of this module.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn. An account on Cisco.com is not required.
Information About Configuring the Configuration Engine
The Cisco Configuration Engine is network management utility software that acts as a configuration service for automating the deployment and management of network devices and services. Each Cisco Configuration Engine manages a group of Cisco devices (switches and routers) and the services that they deliver, storing their configurations and delivering them as needed. The Cisco Configuration Engine automates initial configurations and configuration updates by generating device-specific configuration changes, sending them to the device, executing the configuration change, and logging the results.
The Cisco Configuration Engine supports standalone and server modes and has these Cisco Networking Services (CNS) components:
In standalone mode, the Cisco Configuration Engine supports an embedded directory service. In this mode, no external directory or other data store is required. In server mode, the Cisco Configuration Engine supports the use of a user-defined external directory.
The Configuration Service is the core component of the Cisco Configuration Engine. It consists of a Configuration Server that works with Cisco IOS CNS agents on the switch. The Configuration Service delivers device and service configurations to the switch for initial configuration and mass reconfiguration by logical groups. Switches receive their initial configuration from the Configuration Service when they start up on the network for the first time.
The Configuration Service uses the CNS Event Service to send and receive configuration change events and to send success and failure notifications.
The Configuration Server is a web server that uses configuration templates and the device-specific configuration information stored in the embedded (standalone mode) or remote (server mode) directory.
Configuration templates are text files containing static configuration information in the form of CLI commands. In the templates, variables are specified by using Lightweight Directory Access Protocol (LDAP) URLs that reference the device-specific configuration information stored in a directory.
The Cisco IOS agent can perform a syntax check on received configuration files and publish events to show the success or failure of the syntax check. The configuration agent can either apply configurations immediately or delay the application until receipt of a synchronization event from the configuration server.
The Cisco Configuration Engine uses the Event Service for receipt and generation of configuration events. The Event Service consists of an event agent and an event gateway. The event agent is on the switch and facilitates the communication between the switch and the event gateway on the Cisco Configuration Engine.
The Event Service is a highly capable publish-and-subscribe communication method. The Event Service uses subject-based addressing to send messages to their destinations. Subject-based addressing conventions define a simple, uniform namespace for messages and their destinations.
The Cisco Configuration Engine includes the NameSpace Mapper (NSM) that provides a lookup service for managing logical groups of devices based on application, device or group ID, and event.
Cisco IOS devices recognize only event subject-names that match those configured in Cisco IOS software; for example, cisco.cns.config.load. You can use the namespace mapping service to designate events by using any desired naming convention. When you have populated your data store with your subject names, NSM changes your event subject-name strings to those known by Cisco IOS.
For a subscriber, when given a unique device ID and event, the namespace mapping service returns a set of events to which to subscribe. Similarly, for a publisher, when given a unique group ID, device ID, and event, the mapping service returns a set of events on which to publish.
The Cisco Configuration Engine assumes that a unique identifier is associated with each configured switch. This unique identifier can take on multiple synonyms, where each synonym is unique within a particular namespace. The event service uses namespace content for subject-based addressing of messages.
The Cisco Configuration Engine intersects two namespaces, one for the event bus and the other for the configuration server. Within the scope of the configuration server namespace, the term ConfigID is the unique identifier for a device. Within the scope of the event bus namespace, the term DeviceID is the CNS unique identifier for a device.
Each configured switch has a unique ConfigID, which serves as the key into the Cisco Configuration Engine directory for the corresponding set of switch CLI attributes. The ConfigID defined on the switch must match the ConfigID for the corresponding switch definition on the Cisco Configuration Engine.
The ConfigID is fixed at startup time and cannot be changed until the device restarts, even if the switch hostname is reconfigured.
Each configured switch participating on the event bus has a unique DeviceID, which is analogous to the switch source address so that the switch can be targeted as a specific destination on the bus.
The origin of the DeviceID is defined by the Cisco IOS hostname of the switch. However, the DeviceID variable and its usage reside within the event gateway adjacent to the switch.
The logical Cisco IOS termination point on the event bus is embedded in the event gateway, which in turn functions as a proxy on behalf of the switch. The event gateway represents the switch and its corresponding DeviceID to the event bus.
The switch declares its hostname to the event gateway immediately after the successful connection to the event gateway. The event gateway couples the DeviceID value to the Cisco IOS hostname each time this connection is established. The event gateway retains this DeviceID value for the duration of its connection to the switch.
The DeviceID is fixed at the time of the connection to the event gateway and does not change even when the switch hostname is reconfigured.
When changing the switch hostname on the switch, the only way to refresh the DeviceID is to break the connection between the switch and the event gateway. For instructions on refreshing DeviceIDs, see "Related Topics."
When the connection is reestablished, the switch sends its modified hostname to the event gateway. The event gateway redefines the DeviceID to the new value.
![]() Caution | When using the Cisco Configuration Engine user interface, you must first set the DeviceID field to the hostname value that the switch acquires after, not before, and you must reinitialize the configuration for your Cisco IOS CNS agent. Otherwise, subsequent partial configuration command operations may malfunction. |
In standalone mode, when a hostname value is set for a switch, the configuration server uses the hostname as the DeviceID when an event is sent on hostname. If the hostname has not been set, the event is sent on the cn=<value> of the device.
In server mode, the hostname is not used. In this mode, the unique DeviceID attribute is always used for sending an event on the bus. If this attribute is not set, you cannot update the switch.
These and other associated attributes (tag value pairs) are set when you run Setup on the Cisco Configuration Engine.
The CNS event agent feature allows the switch to publish and subscribe to events on the event bus and works with the Cisco IOS CNS agent. These agents, embedded in the switch Cisco IOS software, allow the switch to be connected and automatically configured.
When the switch first comes up, it attempts to get an IP address by broadcasting a Dynamic Host Configuration Protocol (DHCP) request on the network. Assuming there is no DHCP server on the subnet, the distribution switch acts as a DHCP relay agent and forwards the request to the DHCP server. Upon receiving the request, the DHCP server assigns an IP address to the new switch and includes the Trivial File Transfer Protocol (TFTP) server Internet Protocol (IP) address, the path to the bootstrap configuration file, and the default gateway IP address in a unicast reply to the DHCP relay agent. The DHCP relay agent forwards the reply to the switch.
The switch automatically configures the assigned IP address on interface VLAN 1 (the default) and downloads the bootstrap configuration file from the TFTP server. Upon successful download of the bootstrap configuration file, the switch loads the file in its running configuration.
The Cisco IOS CNS agents initiate communication with the Configuration Engine by using the appropriate ConfigID and EventID. The Configuration Engine maps the Config ID to a template and downloads the full configuration file to the switch.
The following figure shows a sample network configuration for retrieving the initial bootstrap configuration file by using DHCP-based autoconfiguration.
After the network is running, new services can be added by using the Cisco IOS CNS agent. Incremental (partial) configurations can be sent to the switch. The actual configuration can be sent as an event payload by way of the event gateway (push operation) or as a signal event that triggers the switch to initiate a pull operation.
The switch can check the syntax of the configuration before applying it. If the syntax is correct, the switch applies the incremental configuration and publishes an event that signals success to the configuration server. If the switch does not apply the incremental configuration, it publishes an event showing an error status. When the switch has applied the incremental configuration, it can write it to nonvolatile random-access memory (NVRAM) or wait until signaled to do so.
When the switch receives a configuration, it can defer application of the configuration upon receipt of a write-signal event. The write-signal event tells the switch not to save the updated configuration into its NVRAM. The switch uses the updated configuration as its running configuration. This ensures that the switch configuration is synchronized with other network activities before saving the configuration in NVRAM for use at the next reboot.
To enable automated CNS configuration of the switch, you must first complete the prerequisites listed in this topic. When you complete them, power on the switch. At the setup prompt, do nothing; the switch begins the initial configuration. When the full configuration file is loaded on your switch, you do not need to do anything else.
For more information on what happens during initial configuration, see "Related Topics."
Device |
Required Configuration |
---|---|
Access switch |
Factory default (no configuration file) |
Distribution switch |
|
DHCP server |
|
TFTP server |
|
CNS Configuration Engine |
One or more templates for each type of device, with the ConfigID of the device mapped to the template. |
How to Configure the Configuration Engine
![]() Note | You must enable the CNS event agent on the switch before you enable the CNS configuration agent. |
Follow these steps to enable the CNS event agent on the switch.
1.
enable
3.
cns event {hostname |
ip-address} [port-number] [ [keepalive
seconds
retry-count] [failover-time
seconds
] [reconnect-time
time]
|
backup]
6.
copy running-config
startup-config
To verify information about the event agent, use the show cns event connections command in privileged EXEC mode.
To disable the CNS event agent, use the no cns event { ip-address | hostname } global configuration command.
Follow these steps to enable the Cisco IOS CNS agent on the switch.
You must enable the CNS event agent on the switch before you enable this agent.
1.
enable
3.
cns config initial
{hostname |
ip-address} [port-number]
4.
cns config partial
{hostname |
ip-address} [port-number]
7.
copy running-config
startup-config
8. Start the Cisco IOS CNS agent on the switch.
Command or Action | Purpose | |
---|---|---|
Step 1 |
enable
Example:
Switch> enable
|
Enables privileged EXEC mode. Enter your password if prompted. |
Step 2 | configure
terminal
Example: Switch# configure terminal | |
Step 3 | cns config initial
{hostname |
ip-address} [port-number]
Example:
Switch(config)# cns config initial 10.180.1.27 10
|
Enables the Cisco IOS CNS agent, and enters the configuration server parameters.
This command enables the Cisco IOS CNS agent and initiates an initial configuration on the switch. |
Step 4 | cns config partial
{hostname |
ip-address} [port-number]
Example:
Switch(config)# cns config partial 10.180.1.27 10
|
Enables the Cisco IOS CNS agent, and enters the configuration server parameters.
Enables the Cisco IOS CNS agent and initiates a partial configuration on the switch. |
Step 5 | end
Example: Switch(config)# end | |
Step 6 | show running-config
Example: Switch# show running-config | |
Step 7 | copy running-config
startup-config
Example:
Switch# copy running-config startup-config
|
(Optional) Saves your entries in the configuration file. |
Step 8 | Start the Cisco IOS CNS agent on the switch. |
You can now use the Cisco Configuration Engine to remotely send incremental configurations to the switch.
Follow these steps to enable the CNS configuration agent and initiate an initial configuration on the switch.
1.
enable
3.
cns template connect
name
4.
cli
config-text
5. Repeat Steps 3 to 4 to configure another CNS connect template.
6.
exit
7.
cns connect
name
[retries
number] [retry-interval
seconds] [sleep
seconds] [timeout
seconds]
8.
discover {controller
controller-type |
dlci
[subinterface
subinterface-number] |
interface [interface-type] |
line
line-type}
9.
template
name
[...
name]
10. Repeat Steps 8 to 9 to specify more interface parameters and CNS connect templates in the CNS connect profile.
11.
exit
12.
hostname
name
13.
ip route
network-number
14.
cns id
interface
num {dns-reverse |
ipaddress |
mac-address} [event] [image]
15.
cns id {hardware-serial |
hostname |
string
string |
udi}
[event] [image]
16.
cns config initial
{hostname |
ip-address} [port-number] [event] [no-persist] [page
page] [source
ip-address] [syntax-check]
19.
copy running-config
startup-config
Command or Action | Purpose | |||
---|---|---|---|---|
Step 1 |
enable
Example:
Switch> enable
|
Enables privileged EXEC mode. Enter your password if prompted. | ||
Step 2 | configure
terminal
Example: Switch# configure terminal | |||
Step 3 | cns template connect
name
Example:
Switch(config)# cns template connect template-dhcp
|
Enters CNS template connect configuration mode, and specifies the name of the CNS connect template. | ||
Step 4 | cli
config-text
Example:
Switch(config-tmpl-conn)# cli ip address dhcp
|
Enters a command line for the CNS connect template. Repeat this step for each command line in the template. | ||
Step 5 | Repeat Steps 3 to 4 to configure another CNS connect template. | |||
Step 6 | exit
Example:
Switch(config)# exit
|
Returns to global configuration mode. | ||
Step 7 | cns connect
name
[retries
number] [retry-interval
seconds] [sleep
seconds] [timeout
seconds]
Example:
Switch(config)# cns connect dhcp
|
Enters CNS connect configuration mode, specifies the name of the CNS connect profile, and defines the profile parameters. The switch uses the CNS connect profile to connect to the Configuration Engine.
| ||
Step 8 | discover {controller
controller-type |
dlci
[subinterface
subinterface-number] |
interface [interface-type] |
line
line-type}
Example:
Switch(config-cns-conn)# discover interface gigabitethernet
|
Specifies the interface parameters in the CNS connect profile.
| ||
Step 9 | template
name
[...
name]
Example:
Switch(config-cns-conn)# template template-dhcp
|
Specifies the list of CNS connect templates in the CNS connect profile to be applied to the switch configuration. You can specify more than one template. | ||
Step 10 | Repeat Steps 8 to 9 to specify more interface parameters and CNS connect templates in the CNS connect profile. | |||
Step 11 | exit
Example:
Switch(config-cns-conn)# exit
|
Returns to global configuration mode. | ||
Step 12 | hostname
name
Example:
Switch(config)# hostname device1
|
Enters the hostname for the switch. | ||
Step 13 | ip route
network-number
Example:
RemoteSwitch(config)# ip route 172.28.129.22 255.255.255.255 11.11.11.1
|
(Optional) Establishes a static route to the Configuration Engine whose IP address is network-number. | ||
Step 14 | cns id
interface
num {dns-reverse |
ipaddress |
mac-address} [event] [image]
Example:
RemoteSwitch(config)# cns id GigabitEthernet1/0/1 ipaddress
|
(Optional) Sets the unique EventID or ConfigID used by the Configuration Engine. If you enter this command, do not enter the cns id {hardware-serial | hostname | string string | udi} [event] [image] command.
| ||
Step 15 | cns id {hardware-serial |
hostname |
string
string |
udi}
[event] [image]
Example:
RemoteSwitch(config)# cns id hostname
| (Optional)
Sets the unique EventID or ConfigID used by the Configuration Engine. If you
enter this command, do not enter the
cns id
interface
num {dns-reverse |
ipaddress |
mac-address} [event] [image]
command.
| ||
Step 16 | cns config initial
{hostname |
ip-address} [port-number] [event] [no-persist] [page
page] [source
ip-address] [syntax-check]
Example:
RemoteSwitch(config)# cns config initial 10.1.1.1 no-persist
|
Enables the Cisco IOS agent, and initiates an initial configuration.
| ||
Step 17 | end
Example: Switch(config)# end | |||
Step 18 | show running-config
Example: Switch# show running-config | |||
Step 19 | copy running-config
startup-config
Example:
Switch# copy running-config startup-config
|
(Optional) Saves your entries in the configuration file. |
To verify information about the configuration agent, use the show cns config connections command in privileged EXEC mode.
To disable the CNS Cisco IOS agent, use the no cns config initial { ip-address | hostname } global configuration command.
Follow these steps to refresh a DeviceID when changing the hostname on the switch.
1.
enable
2.
show cns config connections
3. Make sure that the CNS event agent is properly connected to the event gateway.
4.
show cns event connections
5. Record from the output of Step 4 the information for the currently connected connection listed below. You will be using the IP address and port number in subsequent steps of these instructions.
7.
no cns event
ip-address
port-number
8.
cns event
ip-address
port-number
10. Make sure that you have reestablished the connection between the switch and the event connection by examining the output from show cns event connections.
12.
copy running-config
startup-config
Command or Action | Purpose | |
---|---|---|
Step 1 |
enable
Example:
Switch> enable
|
Enables privileged EXEC mode. Enter your password if prompted. |
Step 2 | show cns config connections
Example:
Switch# show cns config connections
|
Displays whether the CNS event agent is connecting to the gateway, connected, or active, and the gateway used by the event agent, its IP address and port number. |
Step 3 | Make sure that the CNS event agent is properly connected to the event gateway. |
Examine the output of show cns config connections for the following: |
Step 4 | show cns event connections
Example:
Switch# show cns event connections
|
Displays the event connection information for your switch. |
Step 5 | Record from the output of Step 4 the information for the currently connected connection listed below. You will be using the IP address and port number in subsequent steps of these instructions. | |
Step 6 | configure
terminal
Example:
Switch# configure terminal
|
Enters global configuration mode. |
Step 7 | no cns event
ip-address
port-number
Example: Switch(config)# no cns event 172.28.129.22 2012
|
Specifies the IP address and port number that you recorded in Step 5 in this command. This command breaks the connection between the switch and the event gateway. It is necessary to first break, then reestablish, this connection to refresh the DeviceID. |
Step 8 | cns event
ip-address
port-number
Example: Switch(config)# cns event 172.28.129.22 2012
|
Specifies the IP address and port number that you recorded in Step 5 in this command. This command reestablishes the connection between the switch and the event gateway. |
Step 9 | end
Example: Switch(config)# end | |
Step 10 | Make sure that you have reestablished the connection between the switch and the event connection by examining the output from show cns event connections. |
|
Step 11 | show running-config
Example: Switch# show running-config | |
Step 12 | copy running-config
startup-config
Example:
Switch# copy running-config startup-config
|
(Optional) Saves your entries in the configuration file. |
Follow these steps to enable the Cisco IOS CNS agent and to initiate a partial configuration on the switch.
1.
enable
3.
cns config partial
{ip-address |
hostname} [port-number] [source
ip-address]
6.
copy running-config
startup-config
Command or Action | Purpose | |||
---|---|---|---|---|
Step 1 |
enable
Example:
Switch> enable
|
Enables privileged EXEC mode. Enter your password if prompted. | ||
Step 2 | configure
terminal
Example: Switch# configure terminal | |||
Step 3 | cns config partial
{ip-address |
hostname} [port-number] [source
ip-address]
Example:
Switch(config)# cns config partial 172.28.129.22 2013
|
Enables the configuration agent, and initiates a partial configuration.
| ||
Step 4 | end
Example: Switch(config)# end | |||
Step 5 | show running-config
Example: Switch# show running-config | |||
Step 6 | copy running-config
startup-config
Example:
Switch# copy running-config startup-config
|
(Optional) Saves your entries in the configuration file. |
To verify information about the configuration agent, use either the show cns config stats or the show cns config outstanding command in privileged EXEC mode.
To disable the Cisco IOS agent, use the no cns config partial { ip-address | hostname } global configuration command. To cancel a partial configuration, use the cns config cancel global configuration command.
Command |
Purpose |
---|---|
show cns config connections
Switch# show cns config connections
|
Displays the status of the CNS Cisco IOS CNS agent connections. |
show cns config outstanding
Switch# show cns config outstanding
|
Displays information about incremental (partial) CNS configurations that have started but are not yet completed. |
show cns config stats
Switch# show cns config stats
|
Displays statistics about the Cisco IOS CNS agent. |
show cns event connections
Switch# show cns event connections
|
Displays the status of the CNS event agent connections. |
show cns event gateway
Switch# show cns event gateway
|
Displays the event gateway information for your switch. |
show cns event stats
Switch# show cns event stats
|
Displays statistics about the CNS event agent. |
show cns event subject
Switch# show cns event subject
|
Displays a list of event agent subjects that are subscribed to by applications. |
Related Topic | Document Title |
---|---|
Configuration Engine Setup |
Cisco Configuration Engine Installation and Setup Guide, 1.5 for Linux http://www.cisco.com/en/US/docs/net_mgmt/configuration_engine/1.5/installation_linux/guide/setup_1.html |
Description | Link |
---|---|
To help you research and resolve system error messages in this release, use the Error Message Decoder tool. |
https://www.cisco.com/cgi-bin/Support/Errordecoder/index.cgi |
Standard/RFC | Title |
---|---|
None |
- |
MIB | MIBs Link |
---|---|
All supported MIBs for this release. |
To locate and download MIBs for selected platforms, Cisco IOS releases, and feature sets, use Cisco MIB Locator found at the following URL: |
Description | Link |
---|---|
The Cisco Support website provides extensive online resources, including documentation and tools for troubleshooting and resolving technical issues with Cisco products and technologies. To receive security and technical information about your products, you can subscribe to various services, such as the Product Alert Tool (accessed from Field Notices), the Cisco Technical Services Newsletter, and Really Simple Syndication (RSS) Feeds. Access to most tools on the Cisco Support website requires a Cisco.com user ID and password. |
Release |
Modification |
---|---|
Cisco IOS 15.0(2)EX1 |
This feature was introduced. |