Cisco IOS Scripting with TCL Configuration Guide, Cisco IOS XE Release 3S

Cisco IOS XE Scripting with Tcl

The Cisco IOS XE Scripting with Tcl feature provides the ability to run Tool Command Language (Tcl) version 8.3.4 commands from the Cisco IOS XE command-line interface (CLI).

Finding Feature Information

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 for Cisco IOS XE Scripting with Tcl" section.

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

Contents

•Prerequisites for Cisco IOS XE Scripting with Tcl

•Restrictions for Cisco IOS XE Scripting with Tcl

•Information About Cisco IOS XE Scripting with Tcl

•How to Configure Cisco IOS XE Scripting with Tcl

•Configuration Examples for Cisco IOS XE Scripting with Tcl

•Additional References

•Feature Information for Cisco IOS XE Scripting with Tcl

•Glossary

Prerequisites for Cisco IOS XE Scripting with Tcl

•Familiarity with Tcl programming and Cisco IOS XE commands is assumed.

•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.

•Table 1 lists Tcl commands and library calls that do not behave within Cisco IOS XE software as documented in standard Tcl documents.

Information About Cisco IOS XE Scripting with Tcl

To create and use Tcl scripts within Cisco IOS XE software, you should understand the following concepts:

•Tcl Shell for Cisco IOS XE Software

•Tcl Precompiler

•SNMP MIB Object Access

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 show process 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" section.

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. Table 2 displays these command extensions.

SNMP MIB Custom Extensions in the Tcl Shell

The Cisco IOS XE implementation of the Tcl shell contains some custom command extensions for SNMP MIB object access. These extensions operate only under Tcl configuration mode. Table 3 displays these command extensions.

How to Configure Cisco IOS XE Scripting with Tcl

This section contains the following tasks:

•Enabling the Tcl Shell and Using the CLI to Enter Commands (required)

•Using the Tcl Shell to Access SNMP MIB Objects (optional)

•Running Predefined Tcl Scripts (optional)

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. configure terminal

3. scripting tcl encdir location-url

4. scripting tcl init init-url

5. scripting tcl low-memory bytes

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

Examples

The following sample partial output shows information about Ethernet interface 0 on the router. The show interfaces command has been executed from Tcl configuration mode.

Router# tclsh

Router(tcl)# exec "show interfaces"

Ethernet 0 is up, line protocol is up

  Hardware is MCI Ethernet, address is 0000.0c00.750c (bia 0000.0c00.750c)

  Internet address is 10.108.28.8, subnet mask is 255.255.255.0

  MTU 1500 bytes, BW 10000 Kbit, DLY 100000 usec, rely 255/255, load 1/255

  Encapsulation ARPA, loopback not set, keepalive set (10 sec)

  ARP type: ARPA, ARP Timeout 4:00:00

  Last input 0:00:00, output 0:00:00, output hang never

  Last clearing of "show interface" counters 0:00:00

  Output queue 0/40, 0 drops; input queue 0/75, 0 drops

  Five minute input rate 0 bits/sec, 0 packets/sec

  Five minute output rate 2000 bits/sec, 4 packets/sec

     1127576 packets input, 447251251 bytes, 0 no buffer

     Received 354125 broadcasts, 0 runts, 0 giants, 57186* throttles

     0 input errors, 0 CRC, 0 frame, 0 overrun, 0 ignored, 0 abort

     5332142 packets output, 496316039 bytes, 0 underruns

     0 output errors, 432 collisions, 0 interface resets, 0 restarts

.

.

.

Troubleshooting Tips

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

Using the Tcl Shell to Access SNMP MIB Objects

Perform this optional task to enable the interactive Tcl shell and enter Tcl commands to perform actions on MIB objects.

Prerequisites

The SNMP community configuration must exist in the running configuration of the router.

SUMMARY STEPS

1. enable

2. configure terminal

3. scripting tcl encdir location-url

4. scripting tcl init init-url

5. exit

6. tclsh

7. Enter any required Tcl command language syntax.

8. snmp_getbulk community-string non-repeaters max-repetitions oid [oid2 oid3...]

9. snmp_getid community-string

10. snmp_getnext community-string oid [oid2 oid3...]

11. snmp_getone community-string oid [oid2 oid3...]

12. snmp_setany community-string oid type val [oid2 type2 val2...]

13. exit

DETAILED STEPS

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.

Prerequisites

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

Configuration Examples for Cisco IOS XE Scripting with Tcl

This section provides the following configuration examples:

•Tcl Script Using the show interfaces Command: Example

•Tcl Script for SMTP Support: Example

•Tcl Script for SNMP MIB Access: Examples

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 show interfaces command output and creating a comma-separated list of BRI interfaces on the router:

tclsh

proc get_bri {} {

    set check ""

    set int_out [exec "show interfaces"]

    foreach int [regexp -all -line -inline "(^BRI\[0-9]/\[0-9])" $int_out] {

        if {![string equal $check $int]} {

            if {[info exists bri_out]} {

                append bri_out "," $int

             } else {

                 set bri_out $int

             }

             set check $int

        }

    }

    return $bri_out

}

Tcl Script for SMTP Support: Example

The following Tcl script is useful for sending e-mail messages from a router.

##

## Place required comments here!!!

##

package provide sendmail 2.0

# Sendmail procedure for Support

namespace eval ::sendmail {

    namespace export initialize configure sendmessage sendfile

    array set ::sendmail::sendmail {

        smtphost    mailhub

        from        ""

        friendly    ""

    }

    proc configure {} {}

    proc initialize {smtphost from friendly} {

        variable sendmail

        if {[string length $smtphost]} then {

            set sendmail(smtphost) $smtphost 

        }

        if {[string length $from]} then {

            set sendmail(from) $from

        }

        if {[string length $friendly]} then {

            set sendmail(friendly) $friendly

        }

    }

    proc sendmessage {toList subject body {tcl_trace 0}} {

        variable sendmail

        set smtphost $sendmail(smtphost)

        set from $sendmail(from)

        set friendly $sendmail(friendly)

        if {$trace} then {

            puts stdout "Connecting to $smtphost:25"

        }

        set sockid [socket $smtphost 25]

## DEBUG

set status [catch {

        puts $sockid "HELO $smtphost"

        flush $sockid

        set result [gets $sockid]

        if {$trace} then {

            puts stdout "HELO $smtphost\n\t$result"

        }

        puts $sockid "MAIL From:<$from>"

        flush $sockid

        set result [gets $sockid]

        if {$trace} then {

            puts stdout "MAIL From:<$from>\n\t$result"

        }

        foreach to $toList {

            puts $sockid "RCPT To:<$to>"

            flush $sockid

        }

        set result [gets $sockid]

        if {$trace} then {

            puts stdout "RCPT To:<$to>\n\t$result"

        }

        puts  $sockid "DATA "

        flush $sockid

        set result [gets  $sockid]

        if {$trace} then {

            puts stdout "DATA \n\t$result"

        }

        puts  $sockid "From: $friendly <$from>"

        foreach to $toList {

            puts $sockid "To:<$to>"

        }

        puts  $sockid "Subject: $subject"

        puts  $sockid "\n"

        foreach line [split $body "\n"] {

            puts  $sockid " $line"

        }

        puts  $sockid "."

        puts  $sockid "QUIT"

        flush $sockid

        set result [gets  $sockid]

        if {$trace} then {

            puts stdout "QUIT\n\t$result"

        }

} result]

        catch {close $sockid }

        if {$status} then {

	      return -code error $result

        }

        return

    }

    proc sendfile {toList filename subject {tcl_trace 0}} {

        set fd [open $filename r]

        sendmessage $toList $subject [read $fd] $trace

        return

    }

}

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-repeaters and 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.

snmp-server community public RO

snmp-server community private RW

tclsh

  snmp_getbulk public 1 5 1.3.6.1.2.1.1.2.0  1.3.6.1.2.1.2.2.1.2  1.3.6.1.2.1.2.2.1.3

  {<obj oid='sysUpTime.0' val='1336090'/>}

  {<obj oid='ifDescr.1' val='FastEthernet0/0'/>}

  {<obj oid='ifType.1' val='6'/>}

  {<obj oid='ifDescr.2' val='FastEthernet1/0'/>}

  {<obj oid='ifType.2' val='6'/>}

  {<obj oid='ifDescr.3' val='Ethernet2/0'/>}

  {<obj oid='ifType.3' val='6'/>}

  {<obj oid='ifDescr.4' val='Ethernet2/1'/>}

  {<obj oid='ifType.4' val='6'/>}

  {<obj oid='ifDescr.5' val='Ethernet2/2'/>}

  {<obj oid='ifType.5' val='6'/>}

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.

tclsh

 snmp_getid public

 {<obj oid='system.1.0' val='Cisco Internetwork Operating System Software 

 Cisco IOS XE(tm) 7200 Software (C7200-IK9S-M), Experimental Version 12.3(20030507:225511)

 [geotpi2itd1 124]

 Copyright (c) 1986-2003 by Cisco Systems, Inc.

 Compiled Wed 21-May-03 16:16 by engineer'/>} 

 {<obj oid='system.2.0' val='products.223'/>}

 {<obj oid='sysUpTime.0' val='6664317'/>} 

 {<obj oid='system.4.0' val='1-800-553-2447 - phone the TAC'/>}

 {<obj oid='system.5.0' val='c7200.myCompany.com'/>}

 {<obj oid='system.6.0' val='Bldg 24, San Jose, CA'/>}

The following example shows how to retrieve a set of individual variables from the SNMP entity on the router using the snmp_getnext Tcl command extension:

snmp_getnext public 1.3.6.1.2.1.1.1.0 1.3.6.1.2.1.1.2.0 

 {<obj oid='system.2.0' val='products.223'/>}

 {<obj oid='sysUpTime.0' val='6683320'/>}

The following example shows how to retrieve a set of individual variables from the SNMP entity on the router using the snmp_getone Tcl command extension:

snmp_getone public 1.3.6.1.2.1.1.1.0 1.3.6.1.2.1.1.2.0 

 {<obj oid='system.1.0' val='Cisco Internetwork Operating System Software 

 Cisco IOS XE(tm) 7200 Software (C7200-IK9S-M), Experimental Version 12.3(20030507:225511) 
 [geotpi2itd1 124]

 Copyright (c) 1986-2003 by Cisco Systems, Inc.

 Compiled Wed 21-May-03 16:16 by engineer'/>} 

 {<obj oid='system.2.0' val='products.223'/>}

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.

tclsh

 snmp_setany private 1.3.6.1.2.1.1.5.0 -d TCLSNMP-HOST

 {<obj oid='system.5.0' val='TCLSNMP-HOST'/>}

Additional References

The following sections provide references related to the Cisco IOS XE Scripting with Tcl feature.

Related Documents

Standards

MIBs

RFCs

Technical Assistance

Feature Information for Cisco IOS XE Scripting with Tcl

Table 4 lists the release history for this feature.

Not all commands may be available in your Cisco IOS XE software release. For release information about a specific command, see the command reference documentation.

Use Cisco Feature Navigator to find information about platform support and software image support. Cisco Feature Navigator enables you to determine which Cisco IOS XE software images support a specific software release, feature set, or platform. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn. An account on Cisco.com is not required.

Note Table 4 lists only the Cisco IOS XE software release that introduced support for a given feature in a given Cisco IOS XE software release train. Unless noted otherwise, subsequent releases of that Cisco IOS XE software release train also support that feature.

Glossary

ESM—Embedded Syslog Manager.

IVR—Interactive Voice Response.

MIB—Management Information Base.

SNMP—Simple Network Management Protocol.

Tcl—Tool Command Language.

Note See Internetworking Terms and Acronyms for terms not included in this glossary.

CCDE, CCENT, Cisco Eos, Cisco HealthPresence, the Cisco logo, Cisco Lumin, Cisco Nexus, Cisco StadiumVision, Cisco TelePresence, Cisco WebEx, DCE, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn and Cisco Store are service marks; and Access Registrar, Aironet, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, EtherFast, EtherSwitch, Event Center, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iPhone, iQuick Study, IronPort, the IronPort logo, LightStream, Linksys, MediaTone, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, Network Registrar, PCNow, PIX, PowerPanels, ProConnect, ScriptShare, SenderBase, SMARTnet, Spectrum Expert, StackWise, The Fastest Way to Increase Your Internet Quotient, TransPath, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries.

All other trademarks mentioned in this document or website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0812R)

Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.

© 2003-2009 Cisco Systems, Inc. All rights reserved.