Finding Feature Information

Your software release may not support all the features documented in this module. For the latest feature information and caveats, see 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 document.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Prerequisites for Cisco IOS XE Scripting with Tcl

Tcl commands can be executed from the Tcl configuration mode using the Cisco IOS XE CLI. Tcl configuration mode, like global configuration mode, is accessed from privileged EXEC mode. Access to privileged EXEC mode should be managed by restricting access using the enable command password.

Restrictions for Cisco IOS XE Scripting with Tcl

If Cisco IOS XE configuration commands are used within the Tcl scripts, submode commands must be entered as quoted arguments on the same line as the configuration command.

Error messages are provided, but you must check that the Tcl script will run successfully because errors may cause the Tcl shell to run in an infinite loop.

Caution

The use of Tcl server sockets to listen to telnet and FTP ports (23 and 21 respectively) will preempt the normal handling of these ports in Cisco IOS XE software.

The table below lists Tcl commands and library calls that do not behave within Cisco IOS XE software as documented in standard Tcl documents.

When the CLI tclsh command is used, there is no event loop implemented unless Embedded Syslog Manager (ESM) is active on the same router. Commands entered using the after Tcl command will not run unless forced using the update command. Sleep mode (the after command) works only with the ms keyword.

file

-time

atime

No

The optional -time keyword to set the file access time is not supported in Cisco IOS XE software.

file

-time

mtime

No

The optional -time keyword to set the file modification time is not supported in Cisco IOS XE software.

fileevent

Partially

When the CLI tclsh command is used, there is no event loop implemented unless Embedded Syslog Manager (ESM) is active on the same router. Commands entered using the fileevent Tcl command will not run unless forced using the update command.

history

!n

Partially

The !n shortcut does not work in Cisco IOS XE software. Use the history Tcl command with the redon keyword.

load

No

When the CLI load command is used, an error message stating “dynamic loading not available on this system” is displayed.

Information About Cisco IOS XE Scripting with Tcl

Tcl Shell for Cisco IOS XE Software

The Cisco IOS XE Tcl shell was designed to allow customers to run Tcl commands directly from the Cisco IOS XE CLI prompt. Cisco IOS XE software does contain some subsystems such as Embedded Syslog Manager (ESM) and Interactive Voice Response (IVR) that use Tcl interpreters as part of their implementation. These subsystems have their own proprietary commands and keyword options that are not available in the Tcl shell.

Several methods have been developed for creating and running Tcl scripts within Cisco IOS XE software. A Tcl shell can be enabled, and Tcl commands can be entered line by line. After Tcl commands are entered, they are sent to a Tcl interpreter. If the commands are recognized as valid Tcl commands, the commands are executed and the results are sent to the tty. If a command is not a recognized Tcl command, it is sent to the Cisco IOS XE CLI parser. If the command is not a Tcl or Cisco IOS XE command, two error messages are displayed. A predefined Tcl script can be created outside of Cisco IOS XE software, transferred to flash or disk memory, and run within Cisco IOS XE software. It is also possible to create a Tcl script and precompile the code before running it under Cisco IOS XE software.

Multiple users on the same router can be in Tcl configuration mode at the same time without interference because each Tcl shell session launches a separate interpreter and Tcl server process. The tty interface number served by each Tcl process is represented in the server process name and can be displayed using the showprocess CLI command.

The Tcl shell can be used to run Cisco IOS XE CLI EXEC commands within a Tcl script. Using the Tcl shell to run CLI commands allows customers to build menus to guide novice users through tasks, to automate repetitive tasks, and to create custom output for show commands.

Tcl Precompiler

The Cisco IOS XE Tcl implementation offers support for loading scripts that have been precompiled by the TclPro precompiler. Precompiled scripts allow a measure of security and consistency because they are obfuscated.

SNMP MIB Object Access

Designed to make access to Simple Network Management Protocol (SNMP) MIB objects easier, a set of UNIX-like SNMP commands has been created. The Tcl shell is enabled either manually or by using a Tcl script, and the new commands can be entered to allow you to perform specified get and set actions on MIB objects. To increase usability, the new commands have names similar to those used for UNIX SNMP access. To access the SNMP commands go to, Using the Tcl Shell to Access SNMP MIB Objects.

Custom Extensions in the Tcl Shell

The Cisco IOS XE implementation of the Tcl shell contains some custom command extensions. These extensions operate only under Tcl configuration mode. The table below displays these command extensions.

Use the community-string argument to specify the SNMP community from which the objects will be retrieved.

Use the non-repeaters argument to specify the number of objects that can be retrieved with a get-next operation.

Use the max-repetitions argument to specify the maximum number of get-next operations to attempt while trying to retrieve the remaining objects.

Use the oid argument to specify the object ID(s) to retrieve.

snmp_getid

Retrieves the following variables from the SNMP entity on the router:

sysDescr.0

sysObjectID.0

sysUpTime.0

sysContact.0

sysName.0

sysLocation.0

This command is similar to the SNMP getid command. The syntax is in the following format:

snmp_getidcommunity-string

snmp_getnext

Retrieves a set of individual variables from the SNMP entity on the router. This command is similar to the SNMP getnextcommand. The syntax is in the following format:

snmp_getnextcommunity-stringoid [oid2oid3...]

snmp_getone

Retrieves a set of individual variables from the SNMP entity on the router. This command is similar to the SNMP getone command. The syntax is in the following format:

snmp_getonecommunity-stringoid [oid2oid3...]

snmp_setany

Retrieves the current values of the specified variables and then performs a set request on the variables. This command is similar to the SNMP setany command. The syntax is in the following format:

snmp_setanycommunity-stringoidtypeval [oid2type2val2...]

Use the type argument to specify the type of object to retrieve. The type can be one of the following:

-i--Integer. A 32-bit number used to specify a numbered type within the context of a managed object. For example, to set the operational status of a router interface, 1 represents up and 2 represents down.

-u--Unsigned32. A 32-bit number used to represent decimal values in the range from 0 to 2 32 - 1 inclusive.

-c--Counter32. A 32-bit number with a minimum value of 0 and a maximum value of 2 32 - 1. When the maximum value is reached, the counter resets to 0 and starts again.

-g--Gauge. A 32-bit number with a minimum value of 0 and a maximum value of 2 32 - 1. The number can increase or decrease at will. For example, the interface speed on a router is measured using a gauge object type.

How to Configure Cisco IOS XE Scripting with Tcl

Enabling the Tcl Shell and Using the CLI to Enter Commands

Perform this task to enable the interactive Tcl shell and to enter Tcl commands line by line through the Cisco IOS XE CLI prompt. Optional steps include specifying a default location for encoding files and specifying an initialization script.

SUMMARY STEPS

1.enable

2.configureterminal

3.scriptingtclencdirlocation-url

4.scriptingtclinitinit-url

5.scriptingtcllow-memorybytes

6.exit

7.tclsh

8. Enter the required Tcl command language syntax.

9.ios_config“cmd”“cmd-option”

10.exec“exec-cmd”

11.exit

DETAILED STEPS

Command or Action

Purpose

Step 1

enable

Example:

Router> enable

Enables privileged EXEC mode.

Enter your password if prompted.

Step 2

configureterminal

Example:

Router# configure terminal

(Optional) Enters global configuration mode.

Perform Step 2 through Step 6 if you are using encoding files, an initialization script, or both.

Step 3

scriptingtclencdirlocation-url

Example:

Router(config)# scripting tcl encdir tftp://10.18.117.23/enctcl/

(Optional) Specifies the default location of external encoding files used by the Tcl encoding command.

Commands entered in Tcl configuration mode are sent first to the interactive Tcl interpreter. If the command is not a valid Tcl command, it is then sent to the CLI parser.

Step 9

ios_config“cmd”“cmd-option”

Example:

Router(tcl)# ios_config “interface Ethernet 2/0” “no keepalive”

(Optional) Modifies the router configuration using a Tcl script by specifying the Tcl command ios_configwith CLI commands and options. All arguments and submode commands must be entered on the same line as the CLI configuration command.

In this example, the first argument in quotes configures an Ethernet interface and enters interface configuration mode. The second argument in quotes sets the keepalive option. If these two CLI statements were entered on separate Tcl command lines, the configuration would not work.

Troubleshooting Tips

Use the Tcl puts command in a Tcl script to trace command execution.

Running Predefined Tcl Scripts

Perform this optional task to run a predefined Tcl script in Cisco IOS XE software.

Before You Begin

Before performing this task, you must create a Tcl script that can run on Cisco IOS XE software. The Tcl script may be transferred to internal flash memory using any file system that the Cisco IOS XE file system (IFS) supports, including TFTP, FTP, and rcp. The Tcl script may also be sourced from a remote location.

SUMMARY STEPS

1.enable

2.tclsh

3. Enter the Tcl source command with the filename and path.

4.exit

DETAILED STEPS

Command or Action

Purpose

Step 1

enable

Example:

Router> enable

Enables privileged EXEC mode.

Enter your password if prompted.

Step 2

tclsh

Example:

Router# tclsh

Enables the interactive Tcl shell and enters Tcl configuration mode.

Step 3

Enter the Tcl source command with the filename and path.

Example:

Router(tcl)# source slot0:test.tcl

Commands entered in Tcl configuration mode are sent first to the interactive Tcl interpreter. If the command is not a valid Tcl command, it is then sent to the CLI parser.

Step 4

exit

Example:

Router(tcl)# exit

Exits Tcl configuration mode and returns to privileged EXEC mode.

Configuration Examples for Cisco IOS XE Scripting with Tcl

Tcl Script Using the show interfaces Command Example

Using the Tcl regular expression engine, scripts can filter specific information from show commands and present it in a custom format. The following is an example of filtering the showinterfaces command output and creating a comma-separated list of BRI interfaces on the router:

Tcl Script for SNMP MIB Access Examples

Using the Tcl shell, Tcl commands can perform actions on MIBs. The following example shows how to set up the community access strings to permit access to SNMP. Public access is read-only, but private access is read-write. The following example shows how to retrieve a large section of a table at once using the snmp_getbulk Tcl command extension.

Two arguments, non-repeatersand max-repetitions, must be set when an snmp_getbulk command is issued. The non-repeaters argument specifies that the first N objects are to be retrieved with a simple snmp_getnext operation. The max-repetitions argument specifies that up to M snmp_getnext operations are to be attempted to retrieve the remaining objects.

In this example, three bindings--sysUpTime (1.3.6.1.2.1.1.2.0), ifDescr (1.3.6.1.2.1.2.2.1.2), and ifType (1.3.6.1.2.1.2.2.1.3)--are used. The total number of variable bindings requested is given by the formula N + (M * R), where N is the number of non-repeaters (in this example 1), M is the max-repetitions (in this example 5), and R is the number of request objects (in this case 2, ifDescr and ifType). Using the formula, 1 + (5 * 2) equals 11; and this is the total number of variable bindings that can be retrieved by this snmp_getbulk request command.

Sample results for the individual variables include a retrieved value of sysUpTime.0 being 1336090, where the unit is in milliseconds. The retrieved value of ifDescr.1 (the first interface description) is FastEthernet0/0, and the retrieved value of ifType.1 (the first interface type) is 6, which corresponds to the ethernetCsmacd type.

The following example shows how to retrieve the sysDescr.0, sysObjectID.0, sysUpTime.0, sysContact.0, sysName.0, and sysLocation.0 variables--in this example shown as system.1.0, system.2.0, system.3.0, system.4.0, system.5.0, and system.6.0--from the SNMP entity on the router using the snmp_getid Tcl command extension.

The following example shows how to change something in the configuration of the router using the snmp_setany Tcl command extension. In this example, the hostname of the router is changed to TCLSNMP-HOST.

RFCs

No new or modified RFCs are supported by this feature, and support for existing RFCs has not been modified by this feature.

--

Technical Assistance

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.

Feature Information for Cisco IOS XE Scripting with Tcl

The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.