Cisco CNS Configuration Engine Administrator Guide, 1.4

Overview
How to Add a New Device Module
How to Update an Existing Device Module
How to Delete a Device Module
Code Sample

How to Use the IMGW Device Module Development Toolkit

This appendix explains how to add, update, and delete device modules using the IMGW Device Module Development Toolkit.

Overview

The program can be a script or a binary program. It must take command line arguments with the following format:

•For config event:

•For exec event:

•For hoptest:

Input Parameters

The following is a list of arguments and their descriptions for the current supported device program. A plug-in program can interpret the meaning of passed arguments differently, and does not necessarily use all the arguments passed to it.

plug-in program - The plug-in program that executes in the child process forked by IMGW runtime. System administrator gives this information to IMGW runtime during registration.

temp_logfile_name - The full path to the device module temporary log file, which should be used by the device module to log the processing history of one instance of operation (configuration download, command execution or hop test). This file is by default located at /tmp directory on CNS 2100 Series system. After the plug-in program exits, IMGW runtime puts the content of this file into a centralized log file named after /opt/CSCOimgw/bin/IMGW-DEVMOD_LOG for debugging purpose and then unlink this file.

logging_level - The value could be verbose, error or silent. This flag can be set by running setup command on the CNS 2100 Series system. It is recommended that the device module log information into the file of <temp_logfile_name> based on the specified logging level.

device_id - The identification of the device that is processed by the device module. It is passed in by the cisco.mgmt.cns.config.load or cisco.mgmt.cns.exec.cmd event.

action_type - It could be config, exec, or hoptest. The action type config notifies the device module to update the device configuration; exec notifies the device module to execute a command on the device; hoptest notifies the device module to test if the device is reachable by means of the hop information provided in <hop_information_string>. The device module should do the proper operation in response to this flag.

warning_logfile_name - The full path to the file that is used by the device module to log all warning messages and its corresponding configuration command line numbers. This parameter is supplied by IMGW runtime only when the action type is config because the information in this file is only used to generate the response message to the cisco.mgmt.cns.config.load event if the configure succeeds with warnings. In order for the IMGW runtime to generate the proper response message, each warning message should begin a new line and be prefixed with the string of LINE <line number of the configuration command that causes the warning message>:. An example of the warning file is as follows:

LINE 3: The interface has already been removed

. 
. 
.

LINE 7: The interface already exists.

The location of this file is under /tmp on the CNS 2100 Series system. After the plug-in program exits, IMGW runtime will put the content of this file into the response event payload and then unlink this file immediately.

error_logfile_name - The full path to the file that is used by the device module to log the occurrences of the error messages and their corresponding configuration command line numbers. This parameter is supplied by IMGW runtime only when the action type is config because the information in this file is only used to generate the response message to the cisco.mgmt.cns.config.load event if the configure fails. In order for the IMGW runtime to generate the proper response message, each error message should begin a new line and be prefixed with the string of LINE <line number of the configuration command that causes the error message>:. An example of the error file is as follows:

LINE 3: % Invalid input detected at

LINE 7: % Incomplete command

. 
. 
.

LINE 12: % The interface already exists

exec_response_logfile_name - The full path to the file that is used to log the output of command execution on the device. It is supplied by IMGW runtime only when the action type is exec and its location is under /tmp on the CNS 2100 Series system. After the plug-in program exits, IMGW runtime will put the content of this file into the response event payload and then unlink this file immediately.

hop_information_string - The string used to store the access information of the device. It is the string concatenation of all individual hop information of the device in order. An example the hop information and its <hop_information_string> are as follows:


Hop type	IP address	Port	Username	Password
IOS_LOGIN	172.29.145.45		Admin	Cisco
IOS_EN			Lab	Lab

The corresponding <hop_information_string> should be as follows:

"IOS_LOGIN" "172.29.145.45" " " "Admin" "Cisco" "IOS_EN" " " " " "Lab" "Lab"

Note For those fields of hop information with null value, IMGW runtime automatically adds a space before passing it to the child process.

command_to_be_executed - The command to be executed on the device. It is supplied by IMGW runtime only when the action type is exec.

command_arguments - The arguments of the command to be executed on the device. It is supplied by IMGW runtime only when the action type is exec.

configuration_file_name - The full path to the configuration file which will be downloaded onto the device. It is supplied by IMGW runtime only when the action type is config and its location is under /tmp on the CNS 2100 Series system. After the plug-in program exits, IMGW runtime will unlink this file immediately.

persistence - y or n. The symbol y means the configuration needs to be written into non-volatile storage and so forth. It is supplied by IMGW runtime only when the action type is config. This option is dependent on the device type. It means the device module can ignore it if the device type does not support it.

operation_timeout_value - The maximum time period allowed to execute a command on the device. This parameter is now used by Expect scripts in IMGW legacy device module for IOS, CatOS, CatIOS, PIX, CSS and CE devices. User-defined device module can ignore this parameter if they do not use it.

prompt_timeout_value - The maximum time period allowed to wait for the next prompt during login session to the device. This parameter is now used by Expect scripts in IMGW legacy device module for IOS, CatOS, CatIOS, PIX, CSS and CE devices. User-defined device module can ignore this parameter if they do not use it.

Exit Code

When the forked process (in which the plug-in program is executed) exits, the following exit code is expected by IMGW runtime from the forked process:

For config event

0 - Download succeeds

1 - Download fails

2 - Download succeeds but with warning messages

For exec event

0 - Command execution succeeds

1 - Command execution fails

For hop test

0 - Hop test succeeds

1 - Hop test fails

Flow of Events for Plug-in Device Module

The following is a brief description of program flow for the three different commands: config, exec, and hoptest. The first two functionalists are in response to the cisco.mgmt.cns.config.load and cisco.mgmt.cns.exec.cmd events respectively, while the last one is an internal routine operation required by IMGW runtime, thus is transparent to network operators.

After IMGW runtime spawns a child process to execute the plug-in program, the corresponding device module should read the action type from the parameter list. If the action type is config, then the device module should do device configuration update; if it is exec, then the device module should do command execution; if it is hoptest the device module should do hop test.

Device Configuration Update

1. Access the device by means of the <hop_information_string>.

2. Download the configuration file named after <configuration_file_name> onto the device.

3. If above download operation succeeds, the <persistence> is set to y and the device supports this option, write the configuration to non-volatile storage.

4. Write all warning messages prompted by the device and their corresponding configuration command line numbers into the file named after <warning_logfile_name>. The content of this file will be part of the payload of the response event if the download succeeds but with warning messages.

5. Write all error messages prompted by the device and their corresponding configuration command line numbers into the file named after <error_logfile_name>. The first error message and its corresponding configuration command line number will be part of the payload of the response event if the download fails.

6. Based on the <logging_level>, selectively redirect the processing history into the file named after <temp_logfile_name> for debugging purpose during the whole procedure.

7. Exit with proper exit code to return control to IMGW runtime

Command Execution

1. Access the device by means of the <hop_information_string>.

2. Execute on the device the <command_to_be_executed> with the <command_arguments>.

3. Capture all output from the command execution into the file named after <exec_response_logfile_name>. The content of this file will be part of the payload of the response event.

4. Based on the <logging_level>, selectively redirect the processing history into the file named after <temp_logfile_name> for debugging purpose during the whole procedure.

5. Exit with proper exit code to return control to IMGW runtime.

Hop Test

1. Access the device by means of the <hop_information_string>.

2. Based on the <logging_level>, selectively redirect the processing history into the file named after <temp_logfile_name> for debugging purpose during the whole procedure.

3. Exit with proper exit code to return control to IMGW runtime.

A simple example is given in "Code Sample" section. The sample program is a script that connects to a UNIX/Linux workstation by means of rlogin and runs a command passed to it. It responds to exec events.

How to Add a New Device Module

Step 1 Create a device module plug-in program.

Step 2 Unit test the program created in Step 1.

Step 3 Copy the program to the CNS 2100 Series system under /opt/CSCOimgw/plugin-modules/<device_type>.

Make sure that it has execute permission.

Assume the device type is MYDEV, an example would be: /opt/CSCOimgw/plugin-modules/MYDEV/my-handler.exp

Step 4 To register the program with the CNS 2100 Series system, type the following command (assuming the CNS 2100 Series system gateway ID is imgw-test1):

% imgw-devmod-register -gateway imgw-test1 -devtype MYDEV -optype exec -cmd /opt/CSCOimgw/plugin-modules/MYDEV/my-handler.exp

Step 5 Add device type and hop type through DAT (see

a. From the Home page, click on the Tools tab.

b. Click on DAT and login.

c. From the DAT page, click on IMGW.

d. Click on Edit Hop/Device Type.

e. Type in device type from Step 3 into the New DeviceType box and click Add to list. (see Figure B-1)

f. Type a new hop type into the New HopType box and click Add to list.

g. Click Modify.

Figure B-1 Add Device Module

How to Update an Existing Device Module

Step 1 Get a new device module plug-in program.

Step 2 To deregister the old program as follows, type the following command:

% imgw-devmod-deregister -gateway imgw-test1 -devtype MYDEV -optype exec

Step 3 Copy the program created in Step 1 to the CNS 2100 Series system under /opt/CSCOimgw/plugin-modules/<device_type>.

For example, the new file is:

/optCSCOimgw/plugin-modules/MYDEV/new_handler.exp

Step 4 To register the new program with the CNS 2100 Series system as follows, type the following command:

% imgw-devmod-register -gateway imgw-test1 -devtype MYDEV -optype exec -cmd /optCSCOimgw/plugin-modules/MYDEV/new_handler.exp

How to Delete a Device Module

Step 1 Remove device type and hop type through DAT

a. From the Home page, click on the Tools tab.

b. Click on DAT and login.

c. From the DAT page, click on IMGW.

d. Click on Edit Hop/Device Type.

e. Select the device type removed, and click Remove (see Figure B-1).

f. Select hop type associated with the deleted device type and click Remove.

g. Click Modify.

Step 2 To deregister the program, type the following command:

% imgw-devmod-register -gateway imgw-test1 -devtype MYDEV -optype exec

Step 3 To remove plug-in program from /opt/CSCOimgw/plugin-modules, type the following command:

% rm -fr /opt/CSCOimgw/plugin-modules/MYDEV/

Code Sample

#!/usr/bin/expect

# exit status:

# 0: success

# 1: failure

#exp_internal 1

###################################################################

# Get necessary arguments

###################################################################

# arg 1 loglevel is not used in this script

# arg 2 deviceid is not used in this script

# the contents of log is written to /opt/CSCOimgw/bin/IMGW-DEVMOD-LOG

set log [lindex $argv 0]

set action [lindex $argv 3]

###################################################################

# Hopinfo contains information to access a device.

# Hopinfo format:

# <hoptype> <ip> <port> <username> <password>

# eg)

# "IOS_LOGIN" "10.1.2.3" "0" "admin" "cisco"

# "IOS_EN" "" "" "labuser" "labpasswd"

###################################################################

set hopinfo [lindex $argv 4]

# hostname is 1st arg in hopinfo, username is 3rd and password the 4th

set hostname [lindex $argv 5]

set username [lindex $argv 7]

set password [lindex $argv 8]

set f [open $log w]

puts $f "hostname= $hostname, user= $username, passwd=$password"

###################################################################

# Get command to be executed.

###################################################################

# for this test script, there is only one hop entry, so the next arg is at

# [hopindex + 5]. If more than one hop entry exists, the next arg will be

# at [hopindex + x*5] where x is the number of hop entries.

set cmd [lindex $argv 9]

set cmdargs [lindex $argv 10]

###################################################################

# the contents of response log is included in the response event,

# and is logged in /opt/CSCOimgw/bin/IMGW-LOG-<hostname>

###################################################################

set reslog [lindex $argv 11]

# the remaining args op_timeout and prompt_timeout are not used

puts $f "Executing rlogin.exp"

puts $f "action= $action, cmd= $cmd, cmdargs= $cmdargs, hopinfo= $hopinfo"

###################################################################

# Do some error checking for input arguments.

###################################################################

if { [string match $action "exec"] !=1 } {

   puts $f "Error: Unknown action type, exit program."

   close $f

   exit 1

###################################################################

# Actual work here

###################################################################

puts $f "Calling command rlogin $hostname -l $username"

eval spawn -noecho "rlogin $hostname -l $username"

log_file -noappend $reslog

expect {

    -nocase "Password:" { send "$password\r" }

expect {

    -re "\-\>" {

        send "$cmd $cmdargs\r"

    -re "\\$" {

        send "$cmd $cmdargs\r"

expect {

    -re "\-\>" {

        send "exit\n"

    -re "\\$" {

        send "exit\n"

log_file

puts $f "Done"

close $f

###################################################################

# Return success exit code here

###################################################################

exit 0

Bias-Free Language

Book Title

Cisco CNS Configuration Engine Administrator Guide, 1.4

Chapter Title

How to Use the IMGW Device Module Toolkit

Results

Chapter: How to Use the IMGW Device Module Toolkit

How to Use the IMGW Device Module Development Toolkit

Overview

Input Parameters

Exit Code

Flow of Events for Plug-in Device Module

Device Configuration Update

Command Execution

Hop Test

How to Add a New Device Module

How to Update an Existing Device Module

How to Delete a Device Module

Code Sample

Was this Document Helpful?

Contact Cisco