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.
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).
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.
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.
|
Command |
Keyword |
Argument |
Supported |
Comments |
|---|---|---|---|---|
|
after |
ms |
script |
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 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 redo n keyword. |
|
|
load |
No |
When the CLI load command is used, an error message stating “dynamic loading not available on this system” is displayed. |
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.
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.
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 the Using the Tcl Shell to Access SNMP MIB Objects.
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.
|
Command |
Description |
|---|---|
|
ios_config |
Runs a Cisco IOS XE CLI configuration command. |
|
log_user |
Toggles Tcl command output under Tcl configuration mode. |
|
typeahead |
Writes text to the router standard input (stdin) buffer file. |
|
tclquit |
Leave Tcl shell--synonym for exit . |
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. The table below displays these command extensions.
|
Command |
Description |
|---|---|
|
snmp_getbulk |
Retrieves a large section of a MIB table. This command is similar to the SNMP getbulk command. The syntax is in the following format: snmp_getbulk community-string non-repeaters max-repetitions oid [oid2 oid3 ...]
|
|
snmp_getid |
Retrieves the following variables from the SNMP entity on the router:
This command is similar to the SNMP getid command. The syntax is in the following format: snmp_getid community-string |
|
snmp_getnext |
Retrieves a set of individual variables from the SNMP entity on the router. This command is similar to the SNMP getnext command. The syntax is in the following format: snmp_getnext community-string oid [oid2 oid3 ...] |
|
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_getone community-string oid [oid2 oid3 ...] |
|
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_setany community-string oid type val [oid2 type2 val2 ...]
|
Perform this task to enable the interactive Tcl shell and to enter Tcl commands through the Cisco IOS CLI. The optional steps in this procedure include specifying a default location for encoding files and specifying an initialization script.
|
Step 1 |
enable Example:Enables the privileged EXEC mode. Enter your password, if prompted. If you're encoding your files, or if you're using an initialization script, or both, perform steps 2 through 6 in this procedure. Else, go to step 7. |
||
|
Step 2 |
configure terminal Example:Enters the global configuration mode. |
||
|
Step 3 |
scripting tcl encdir location-url Example:Specifies the default location of external encoding files used by the Tcl encoding command. |
||
|
Step 4 |
scripting tcl init init-url Example:Specifies an initialization script to run when you enable the Tcl shell. |
||
|
Step 5 |
scripting tcl low-memory bytes Example:Specifies a low memory mark for free memory for the Tcl-based applications. You can set the memory threshold anywhere 0–4294967295 bytes.
|
||
|
Step 6 |
exit Example:Exits the global configuration mode and returns to the privileged EXEC mode. |
||
|
Step 7 |
tclsh Example:Enables the interactive Tcl shell and enters the Tcl configuration mode. |
||
|
Step 8 |
Enter the required Tcl command language syntax. Example:The commands you enter in the Tcl configuration mode are sent first to the interactive Tcl interpreter. If the command isn't a valid Tcl command, it's then sent to the CLI parser. |
||
|
Step 9 |
ios_config “ cmd ” “ cmd-option ” Example:Modifies the router configuration using a Tcl script by specifying the Tcl command ios_config with CLI commands and options. In this example, the first argument in quotes configures an Ethernet interface and enters the interface configuration mode. The second argument in quotes sets the keepalive option, which keeps the connection open for multiple servicing requests. If you entered these two CLI statements on separate Tcl command lines, the configuration does not work. |
||
|
Step 10 |
socket -myaddr addr -myport port -myvrf vrf-table-name host port Example:Specifies the client socket and allows a TCL interpreter to connect via TCP over IPv4/IPv6 and opens a TCP network connection. You can specify a port and host to connect to; there must be a server to accept connections on this port.
|
||
|
Step 11 |
socket - server -myaddr addr -myvrf vrf-table-name port Example:Specifies the server socket and allows a TCL interpreter to connect via TCP over IPv4/IPv6 and opens a TCP network connection. If the port is zero, Cisco IOS allocates a free port to the server socket by using the fconfigure command to read the -sock0 argument.
|
||
|
Step 12 |
fconfigure channelname - remote [host port ] - broadcast boolean - vrf [vrf_table_name ] Example:Specifies the options in a channel.
|
||
|
Step 13 |
udp_open -ipv6 port Example:Opens a UDP socket. If you specify a port, the UDP socket is opened on that port. Optionally, the system chooses a port and you can use the fconfigure command to obtain the port number. If you specify the -ipv6 argument, the socket is opened specifying the AF_INET6 protocol family. |
||
|
Step 14 |
udp_peek sock -buffersize buffer-size Example:Enables peeking into a UDP socket.
|
||
|
Step 15 |
exec “ exec-cmd ” Example:(Optional) Executes the Cisco IOS CLI EXEC mode commands from a Tcl script by specifying the Tcl command exec with the CLI commands.
|
||
|
Step 16 |
exit Example:Exits Tcl configuration mode and returns to privileged EXEC mode. |
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
.
.
.Perform this optional task to run a predefined Tcl script in Cisco IOS XE software.
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.
| Command or Action | Purpose | |
|---|---|---|
|
Step 1 |
enable Example: |
Enables privileged EXEC mode.
|
|
Step 2 |
tclsh Example: |
Enables the interactive Tcl shell and enters Tcl configuration mode. |
|
Step 3 |
Enter the Tcl source command with the filename and path. Example: |
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: |
Exits Tcl configuration mode and returns to privileged EXEC mode. |
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
}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
}
}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'/>}The following sections provide references related to the Signed Tcl Scripts feature.
|
Related Topic |
Document Title |
|---|---|
|
Cisco PKI Overview: Understanding and Planning a PKI Implementing and Managing a PKI |
Security Configuration Guide, Release 12.4 |
|
PKI commands: complete command syntax, command mode, command history, defaults, usage guidelines, and examples. |
Cisco IOS Security Command Reference, Release 12.4 |
|
Standard |
Title |
|---|---|
|
None |
-- |
|
MIB |
MIBs Link |
|---|---|
|
None |
To locate and download MIBs for selected platforms, Cisco software releases, and feature sets, use Cisco MIB Locator found at the following URL: |
|
RFC |
Title |
|---|---|
|
None |
-- |
|
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. |
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.|
Feature Name |
Releases |
Feature Information |
|---|---|---|
|
Cisco IOS XE Scripting with Tcl |
Cisco IOS XE |
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). In Cisco IOS XE Release 2.1, this feature was introduced on Cisco ASR 1000 Series Aggregation Services Routers. The following commands were introduced or modified: scripting tcl encdir , scripting tcl init , scripting tcl low-memory , tclquit , tclsh . |
|
Tcl SNMP MIB Access |
Cisco IOS XE |
The Tcl SNMP MIB Access feature introduces a set of UNIX-like SNMP commands to make access to Simple Network Management Protocol (SNMP) MIB objects easier. |
CA--certification authority. Service responsible for managing certificate requests and issuing certificates to participating IPsec network devices. This service provides centralized key management for the participating devices and is explicitly trusted by the receiver to validate identities and to create digital certificates.
certificates--Electronic documents that bind a user's or device's name to its public key. Certificates are commonly used to validate a digital signature.
CRL--certificate revocation list. Electronic document that contains a list of revoked certificates. The CRL is created and digitally signed by the CA that originally issued the certificates. The CRL contains dates for when the certificate was issued and when it expires. A new CRL is issued when the current CRL expires.
IPsec--IP security
peer certificate--Certificate presented by a peer, which contains the peer's public key and is signed by the trustpoint CA.
PKI--public key infrastructure. System that manages encryption keys and identity information for components of a network that participate in secured communications.
RA--registration authority. Server that acts as a proxy for the CA so that CA functions can continue when the CA is offline. Although the RA is often part of the CA server, the RA could also be an additional application, requiring an additional device to run it.
RSA keys--Public key cryptographic system developed by Ron Rivest, Adi Shamir, and Leonard Adleman. An RSA key pair (a public and a private key) is required before you can obtain a certificate for your device.
SHA1--Secure Hash Algorithm 1
SSH--secure shell
SSL--secure socket layer
Feedback