TCL Scripting for Cisco IOS
Petr Grygrek
2009 Petr Grygarek, Advanced Computer Networks Technologies
Automation using TCL Scriptiong
Network monitoring Troubleshooting tools Added intelligence
2009 Petr Grygarek, Advanced Computer Networks Technologies
Tool Command Language (TCL)
Invented by John K. Ousterhout,
Berkeley, 1980s Interpreted language
Runtime available for many platforms http://www.tcl.tk/
2009 Petr Grygarek, Advanced Computer Networks Technologies 3
support for compilation into bytecode
Tool Command Language (TCL)
Invented by John K. Ousterhout,
Berkeley, 1980s, http://www.tcl.tk/ Interpreted language
Intended for scripting, rapid
support for compilation into bytecode
prototyping, embedding into applications, creation of GUIs (TCL/Tk toolkit) Runtime engine available for many platforms
2009 Petr Grygarek, Advanced Computer Networks Technologies 4
(taken from http://en.wikipedia.org/wiki/Tcl)
TCL Basic Features
Prefix command notation No data types
variable number of arguments all values treated as strings
Everything can be dynamically redefined
and overriden Object-oriented extensions are available Many extension libraries were developed
2009 Petr Grygarek, Advanced Computer Networks Technologies 5
IOS Policies
Applets
TCL Scripts
sequences of IOS commands Stored in device's running config Programs in TCL Stored on FLASH or external storage
Policies are subscribed with Embedded
Event Manager (EEM) to be activated when specific event(s) occur(s)
They also can be activated manually
2009 Petr Grygarek, Advanced Computer Networks Technologies
Detects interesting events
using Event Detectors
Embedded Event Manager
Triggers specific policy based when a
specific event (or combination of events) occurs
2009 Petr Grygarek, Advanced Computer Networks Technologies
Event Detectors
Monitor SW and HW components for
specific events Examples of event detectors:
CLI, Timer Syslog Object Tracking interface state change detector insertion/removal of module detector ...
2009 Petr Grygarek, Advanced Computer Networks Technologies
How to Execute TCL Script from Cisco IOS
tclsh flash0:myScript.tcl TCL interactive shell mode: tclsh
are passed to IOS CLI
Urecognized (i.e. non-TCL) commands
2009 Petr Grygarek, Advanced Computer Networks Technologies
Basic TCL Commands and Structures
2009 Petr Grygarek, Advanced Computer Networks Technologies
10
info commands info exists <varName> info args <procName> info body <procName> info globals info vars
Getting Help
Command typed with wrong argument(s) make tclsh to display usage help # this is a comment
2009 Petr Grygarek, Advanced Computer Networks Technologies 11
Assignments, Expressions, Displaying Outputs
set x 1 puts $x set x [expr $x+1] puts $x incr x -10 set p1 kocour set p2 mour set p3 "$p1 $p2" -> kocour mour
2009 Petr Grygarek, Advanced Computer Networks Technologies
12
printf-like Output Formatting
set a 1 set s kocour set f [format "int: %d, string: %s" $a $s] f now contains int: 1, string: kocour Text in [] is replaced with result of executed TCL code contained in block
2009 Petr Grygarek, Advanced Computer Networks Technologies
13
Expr command
Examples:
set r [expr {rand()}] -> float (0,1)
2009 Petr Grygarek, Advanced Computer Networks Technologies
14
Array is treated as set of associated pairs
set a(1) 10 set a(dog) Zeryk puts $a(1) -> 10 puts $a(dog) -> Zeryk puts $a(2) -> can't read "a(2)": no such element in array array set a kocour mour number 2 puts $a(kocour) -> mour puts $a(number) -> 2
2009 Petr Grygarek, Advanced Computer Networks Technologies 15
Arrays
no space pre-allocation keys of any type
Array Functions
unset a(1) unset a
deletes one association from a destroys the whole array
set a(1) 10 set a(2) 20 array get a -> 1 10 2 20 array get a 1 -> 1 10 array size a -> 2 array names a -> 1 2
2009 Petr Grygarek, Advanced Computer Networks Technologies
16
Strings
string <operation> <argument(s)?
e.g. string first needle $hay
hay {aa bb cc bb dd} string first bb $hay -> 3
2009 Petr Grygarek, Advanced Computer Networks Technologies
17
Lists
List is a string consisting of values
separated by whitespaces. List manipulation functions:
Llength, lappend, linsert, lreplace, lrange lindex, lsearch, lsort
2009 Petr Grygarek, Advanced Computer Networks Technologies 18
Loops and Iterators
for {set i 0} {$i<10} {incr i} { puts $i } set i 0 while {$i < 10} { puts $i; incr i } set lst {1 2 3 4 5 6 7 8 9} foreach {a1 a2 a3} $lst { puts a1=$a1, a2=$a2, a3=$a3 } a1=1,a2=2,a3=3 a1=4,a2=5,a3=6 a1=7,a2=8,a3=9
2009 Petr Grygarek, Advanced Computer Networks Technologies 19
Conditional Execution
set x 1 if {$x < 10} { puts LESS } else { puts GREATER } -> LESS
2009 Petr Grygarek, Advanced Computer Networks Technologies
20
Procedures
proc myproc {p1 p2} { set res [expr $p1+$p2] return $res } set sum [myproc 10 20]
2009 Petr Grygarek, Advanced Computer Networks Technologies
21
Files
set fd [open flash:f.txt w] puts $fd kocour puts $fd mour close $fd Router# more flash:f.txt set fd [open flash:f.txt r] while { [gets $fd line] > 0 } { puts $line } close $fd tell $fd, seek $fd <pos> file <operation> <argument(s)> e.g. file delete flash:f.txt
2009 Petr Grygarek, Advanced Computer Networks Technologies
22
sample.tcl: puts "\n"
Handling Script Arguments
puts "Argument count: $argc" puts "Argv0: $argv0" puts "Argv: $argv" puts "Individual arguments:" foreach {iterVar} $argv { puts $iterVar } router #tclsh http://10.0.0.2/sample.tcl aaa bbb ccc -> Argument count: 3 Argv0: http://10.0.0.2/kocour.tcl Argv: aaa bbb ccc Individual arguments: aaa bbb ccc
2009 Petr Grygarek, Advanced Computer Networks Technologies 23
Interactions between TCL Policies and IOS CLI
2009 Petr Grygarek, Advanced Computer Networks Technologies
24
Running TCL Scripts
From TCL shell
router(tcl)#source flash:mysrc.tcl router(tcl)#source http://10.0.0.2/kocour.tcl
source TCL command
From IOS exec mode
router#tclsh http://10.0.0.2/kocour.tcl args
tclsh command followed by script name
Arguments cannot be passed to script
using source command Multiple scripts may run in parallel.
2009 Petr Grygarek, Advanced Computer Networks Technologies 25
Exec Mode Commands
log_user 0/1 disables/enables displaying of CLI commands outputs set cliOutput [exec "sh ip interface brief"] works both in interactive TCL shell and TCL scripts
2009 Petr Grygarek, Advanced Computer Networks Technologies
26
Config Mode Commands (TCL Shell)
ios_config "hostname MYNAME" ios_config "router rip" "network 10.0.0.0" "end"
It is
recommended to exit from TCL shell for the configuration changes to take effect Always end the configuration commands with end to avoid locking
2009 Petr Grygarek, Advanced Computer Networks Technologies 27
FD-style functions cli_open, cli_write,
Config Mode Commands (EEM TCL Policies)
cli_exec = cli_write + cli_read
cli_read, cli_exec
Work in TCL scripts, NOT in
interactive TCL shell. On the other hand, ios_config does NOT work in TCL scripts (?)
2009 Petr Grygarek, Advanced Computer Networks Technologies
28
Dealing with Interactive Commands
Router(tcl)#typeahead \n\n\n Router(tcl)#exec "copy run flash:x.x" Does not work in TCL Shell interactive mode Alternative: file prompt quiet IOS comand
2009 Petr Grygarek, Advanced Computer Networks Technologies
29
Policy Registration with EEM
Either applet or TCL script may be
registered to be activated when an event is detected
event manager directory user policy flash:/scripts event manager policy myScript.tcl
Specification of the event to trigger
::cisco::eem::event_register_timer cron name
myCron1 cron_entry "0-59 0-23 * * 0-7"
2009 Petr Grygarek, Advanced Computer Networks Technologies
the policy is defined at the beginning of policy's TCL script:
30
Checking Registered Policies
show event manager policy available
[user | system] show event manager policy registered sh event manager history event
EEM policies have to be stored on some local filesystem to ensure their availability regardless of the current state of the connectivity to any external storage server.
2009 Petr Grygarek, Advanced Computer Networks Technologies
31
Manual Policy Launching
event manager run myScript.tcl
with none event
only applicable for policies registered
2009 Petr Grygarek, Advanced Computer Networks Technologies
32
Router(config)#event manager
Specification of Policy's Environment
environment myVariable myValue Router(config)#event manager session cli username kocour sh event manager session cli username
2009 Petr Grygarek, Advanced Computer Networks Technologies
33
Example Policy (launched manually)
::cisco::eem::event_register_none namespace import ::cisco::eem::* namespace import ::cisco::lib::* array set cliconn [ cli_open ] puts $cliconn cli_exec $cliconn(fd) "hostname CHANGED-NAME" cli_close $cliconn(fd)
2009 Petr Grygarek, Advanced Computer Networks Technologies 34
EEM Applets
Definition consists of
applet
EEM versions
Events to be detected to trigger the
available events may vary with different IOS/
Sequence of IOS commands to be
executed
tags
Sorted lexicographically according to line
2009 Petr Grygarek, Advanced Computer Networks Technologies
35
Most Interesting Supported Features (1) Reaction to composite events Reacting to interface status change Processing of RIB change events Reacting to IOS object status change Enhanced Object Tracking Reacting to Syslog messages Reacting to increased resource utilization (CPU,
memory, ...) Integration with SLA monitoring Timers & Counters events
2009 Petr Grygarek, Advanced Computer Networks Technologies
36
Most Interesting Supported Features (2) Sockets Library SNMP Library (outgoing/incoming messages) SMTP Library Integration with Netflow CLI library & events issuing IOS exec and config commands interception of command handling process creation of user commands and/or extending
command parameters
2009 Petr Grygarek, Advanced Computer Networks Technologies
37
Most Interesting Supported Features (3) Messaging between policies running in parallel,
policy synchronization Policy priorization
Persistent storage to keep script's internal state
between runs Remote Procedure Call (RPC) XML-PI TCL scripts debugging support
multiple scheduling queues, nice, ...
2009 Petr Grygarek, Advanced Computer Networks Technologies
38
References
Summarized at
http://wh.cs.vsb.cz/sps/index.php/TCL _scripting_on_Cisco_IOS
2009 Petr Grygarek, Advanced Computer Networks Technologies
39
