Category: Tcl

Someone has asked me a while ago whether it's possible to retain variable values between invocations of an EEM policy. Since a new copy of Tcl interpreter is started for each event, global variables obviously won't work; they are lost as soon as the Tcl policy is finished. A potential solution is to modify the router's configuration and save the values you wish to preserve in event manager environment, but that's a time-consuming process that interferes with whatever router configuration management process you have.

The real solution is based on the appl_setinfo and appl_reqinfo calls. They work, but like many other Tcl-related IOS features they are … well … weird.

When I started exploring the details of MTU handling in Cisco IOS, I quickly got tired of analyzing various long printouts to extract the MTU sizes, so I wrote a Tcl script that display hardware, IP and MPLS MTUs in a tabular format. To install it on your router:

1. Download it from my web site and copy it to your router's flash or NVRAM.
2. Define an alias, for example alias exec mtu tclsh flash:displayMTU.tcl.

The script recognizes two parameters: the ip parameter displays only the interfaces that have IP configured and the mpls parameter displays only the MPLS-enabled interfaces.

Looking from the outside, it looks like Tcl SNMP routines in Cisco IOS were designed by a commitee or came straight from Dilbert. The snmp_getone function that reads a single SNMP value does not return an array or a list (as one would expect), but a string representation of something that looks like an XML object (but is not, since its attributes are not properly quoted). As Tcl on Cisco IOS has no built-in XML support, parsing the return values is a pure joy (and a nice exercise in writing regular expressions).

The following excerpt of a telnet session shows how to extract a single SNMP value in Tcl (I've used extra steps and an interactive tclsh session for illustration purposes). The SNMP community has to be configured in advance with the snmp-server community test ro configuration command.

rtr#tclsh
rtr(tcl)#set value [snmp_getone test system.3.0]
{<obj oid='sysUpTime.0' val='14886'/>}
rtr(tcl)#regexp -inline {oid='(.*)'.*val='(.*)'} $value
{oid='sysUpTime.0' val='14886'} sysUpTime.0 14886
rtr(tcl)#regexp {oid='(.*)'.*val='(.*)'} $value ignore oid result
1
rtr(tcl)#puts $result
14886

And now for a complete example: the following script prints the router uptime.

#
# Simple Tcl script to print system uptime
#
set value [snmp_getone test system.3.0]
regexp {oid='(.*)'.*val='(.*)'} $value ignore oid result
set result [expr $result / 100]
puts "Router uptime is $result seconds"

A few days ago, Jeremy Stretch asked me whether there's a command to display packet lists attached to router's interfaces. While he got pretty far with the output filters, he would like to have a nice tabular format as well as the contents of the access lists displayed next to the interfaces. The show ip access-list interface name command comes pretty close, but it displays the information only for a single interface, so it was time to write another Tcl script. To install it on your router:

1. Download it from my web site and copy it to your router's flash or NVRAM.
2. Define an alias, for example alias exec filters tclsh flash:packetFilters.tcl.

The script recognizes two parameters: the all parameter displays all interfaces, including ones with no access lists and the verbose parameter displays the contents of the access list after the interface name.

I've ported the dns package of the Tcl standard library to Cisco IOS. You can download it from my web site and install it on your router in just a few steps:

1. Extract all the files from the ZIP archive and copy the Tcl files into a subdirectory on your router's flash (I would recommend you use flash:tcllib/dns).
2. Configure the package initialization script with the scripting tcl init flash:tcllib/dns/pkgIndex.tcl global configuration command

To test the successful installation, start the Tcl shell from the command prompt and try to load the DNS package:

router#tclsh
router(tcl)#package require dns
1.3.1
router(tcl)#

Although it's not exactly trivial, you can use standard Tcl packages with Tcl
shell on Cisco IOS by following this procedure:

• Install a Tcl interpreter on your workstation (use ActiveState's ActiveTcl in Windows environment).
• Collect all the source files needed for your set of packages into one directory on your workstation.
• Execute Tcl pkg_mkIndex command in that directory.

$ tclsh
% pkg_mkIndex . *.tcl
% ^Z
$

• Edit the pkgIndex.tcl file created with the pkg_mkIndex command and set the $dir variable to the IOS directory before the first package command (for example, set dir "flash:tcl/").
• Alternatively, add the Tcl command set dir [file dirname [info script]] in front of the first package command. This command sets the $dir variable to the path of the pkgIndex.tcl file.
• Transfer all the source files into a directory on the router's flash (or any other local storage device).
• Configure the execution of the pkgIndex.tcl file at tclsh startup with the scripting tcl init configuration command (for example, scripting tcl init flash:tcl/pkgIndex.tcl).

When you have completed these steps, the pkgIndex.tcl file will be executed every time the Tcl shell is started in Cisco IOS, defining all the packages you've prepared. Now you can use the package require name Tcl command to load the packages you need in your Tcl script.

I have been aware of the typeahead Tcl command for months, but somehow I never got it to work.

It works perfectly in IOS release 12.4(15)T; this is what you have to do to clear interface counters:

In his comment, Michal has asked about the ability to execute IOS commands with prompts from Tcl shell. I haven't found a generic solution yet, but you can reload a router from a Tcl script. First you have to define an EEM applet that reloads the router and can be triggered from command-line interface:

event manager applet forceReload
 event none
 action 1.0 reload

Now you can use the exec "event manager run forceReload" Tcl command in your Tcl script to run the applet (and reload the router).

In a comment to the “Execute multiple commands at once” post, Michal has asked for a complete Tcl-shell-with-parameter example. Here's a short script that shuts down the interface and displays its status:

• Variable ifname is set to the value of the first command-line parameter (in many other programming languages, this would be written as argv[0]);
• If the ifname is empty, the script aborts and prints the usage guidelines (again, in a more human-oriented programming language, this would be if (ifname == “”) ...);
• The show ip interface ifname command is executed. If it fails, the interface name is not correct and the script aborts.
• IOS configuration commands interface ifname and shutdown are executed.
• The show ip interface brief configuration command is executed and filtered with the interface name.

#
# ifname is set to first CLI parameter (interface name)
#
set ifname [lindex $argv 0]
if {[string equal $ifname ""]} { puts "Usage: shutdown ifname"; return; }
if { [ catch { exec "show ip interface $ifname" } errmsg ] } {
  puts "Invalid interface $ifname, show ip interface failed"; return}

ios_config "interface $ifname" "shutdown"
puts [ exec "show ip interface brief ¦ include $ifname" ]

After I've published the Tcl script that displays the interface IP parameters in a formatted table, cos quickly pointed out a bug: I've expected the IP addresses in the address mask format. In the meantime, I've figured out the root cause of the problem (our remote labs are set to display IP masks in decimal format for compatibility reasons) and fixed the Tcl script. It temporarily sets the terminal ip netmask-format to bit-count before executing the show command. The new script recognizes three parameters:

• active: display only interfaces that are up/up;


• configured: display only interfaces with configured IP addresses (unnumbered interfaces using IP address of an interface without one count as configured since IOS reports their IP address as 0.0.0.0).


• address: displays IP address of the unnumbered interface, not the interface that it's borrowing the address from.

You can view the Tcl source or download it from my web site.