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