Tclsh on Cisco IOS tutorial

From CT3

Tcl shell (started with the tclsh command IOS CLI command) was introduced in Cisco IOS release 12.3(2)T. The tclsh can be used to execute interactive Tcl commands interspersed with regular IOS CLI commands. It can also be used to run Tcl scripts that can substantially enhance the IOS CLI experience.

Due to security considerations, primarily the ability to write IOS-based password grabbers, the tclsh command is available only in CLI privilege level 15.

Early implementations of tclsh could consume all available memory in the router, resulting in a router crash. The earlies recommended IOS release to use with tclsh is 12.3(14)T and 12.2(29)S

This tutorial provides numerous tclsh details that are not described in the documentation for the Cisco IOS release 12.4T.

Running tclsh scripts

Cisco IOS tclsh implementation behaves similarly to the tclsh implementations on other operating systems. The tclsh command without parameters starts the interactive shell. When one or more parameters are present in the tclsh command, the first parameter represents the name of the Tcl script to execute and the remaining parameters are passed to the script.

The first parameter of the Cisco IOS tclsh command is an Integrated File System (IFS) URL that can point to a local file (for example flash:myScript.tcl or nvram:script.tcl) or a file accessible through any of the remote file access methods available in Cisco IOS (TFTP, FTP, RCP, SCP, HTTP or HTTPS).

Executing IOS commands

Cisco IOS provides three mechanisms to execute CLI and configuration commands from Tcl:

cli_open, cli_write and cli_close commands are used in Embedded Event Manager (EEM) Tcl policies.
exec and ios_config commands are used in Tcl scripts executed with tclsh command.
You can also mix IOS CLI commands with regular Tcl commands in tclsh scripts (but not in EEM Tcl policies).

Insert responses to CLI command prompts

Some IOS CLI commands (for example, the clear counter command) require user confirmations. The typeahead text-string Tcl command can be used to insert the simulated user response before an IOS CLI command is executed.

The typeahead command might not work correctly in earlier IOS releases. All the tests in this article were performed with the IOS release 12.4(15)T5.

Simulated typeahead is accepted only by the IOS commands executed through the exec Tcl command; if you execute an IOS CLI command directly from the tclsh script, Tcl cannot control its input/output and thus cannot insert the user response.

The typeahead text is consumed as needed. You can execute more than one IOS CLI command with multiple exec Tcl commands without replenishing the typeahead buffer; Cisco IOS obviously opens a single VTY session for the duration of the tclsh script and executes all IOS CLI commands requested with the exec command in that session.

Command line parameters

A Tcl script executed with the tclsh command can receive command line parameters: all words entered after the file name in the tclsh command line are passed to the Tcl script in the $argv list.

The Tcl list commands can be used to examine each individual parameter. When used in a scalar context, $argv returns the rest of the command line after the script name.

Generating Syslog messages from Tclsh

Tcl policies run within the Embedded Event Manager (EEM) environment can use the action_syslog command to generate logging messages. Other Tcl environments within Cisco IOS (for example, tclsh) do not provide a syslog message API to Tcl scripts. You can use the syslog: opaque write-only file system introduced in IOS release 12.4T in these environments to generate debugging syslog messages from the Tcl script.

If you need professional help in planning, developing or deploying Tclsh scripts in your network, contact the author or NIL's Professional Services team