Tcl on Cisco routers

Getting started

An EEM Tcl script has the advantage of being able to be set to run when a predefined trigger event occurs, this could be a certain counter reaching a set level, a syslog message being generated, a time of day ect.
The event manager directory where the Tcl scripts are stored needs to be setup in global configuration mode and the tcl script itself needs registering for as a policy. If a script is edited then after upload it must be de-registered and reregistered in the global configuration mode before the code change will have an effect.
Note that in some circumstances an EEM Applet may be more suitable than a EEM Tcl Policy.

event manager directory user policy [folderLocation]
event manager policy [location][filename.tcl] type user

The first none comment line of the Tcl policy script must state the event registration command,

::cisco::eem::event_register_[commandExtensions]

EEM Policies are by default given a time limit of 20 seconds to complete, if the script continues to execute beyond this maxrun timer limit it is forcibly stopped and will return an error containing the message "Process Forced Exit". This time limit can be extended by adding the maxrun [limit] command to the end of the event registration command, specified in seconds.milliseconds, so maxrun 60 sets the script execution maxrun time limit to 60 seconds.

Passing information to the EEM Policy

Tcl policies running under the Embedded Event Manager can access information regarding how, why and when they were called through the event_reqinfo variable, which also under certain triggers and on the newer EEM versions can be used to pass variables to the Tcl policy like when running scripts in the Tcl shell. See here for further information. They can also read globally configured values set with the command,

event manager environment [variable-name] [string]

EEM policy scripts can also save variables using the Tcl Context Library Command Extensions context_save and context_retrieve or via the EEM Utility Tcl Command Extensions appl_read and appl_setinfo. In both cases when the values are read they are also deleted and so if required later need to be written again after being read.

Debugging

There is comprehensive debugging available for EEM from the router, for debugging an issue with policies not being triggered correctly use;

debug event manager detector [eventDetectorType]
debug event manager policydir
debug event manager server scheduling

For debugging CLI command execution use

debug event manager action cli

and for debugging the Tcl policy use

debug event manager tcl cli
debug event manager tcl commands

Example script using the various arguments/variables available to an EEM policy

An example script which gets and or sets the event_reqinfo, event manager environment..., appl_ and context_ variables and arguments.

# eemVarTest.tcl --
#
#   Sample EEM policy to get/set;
#       Get 'event_reqinfo' variable information (for event type none).
#       Get 'event manager environment' variables.
#       Get and or Set appl_ variables.
#       Get and or Set context_ content variables.
#   
#   For the last two types the script loops three times, 
#       Firstly it attempts to read the variables, upon first run they will not 
#           exits, so they are written.
#       Secondly it again attempts to read, as it wrote them last time they are
#           found and read.
#       Thirdly it again attempts to read, however as we read them in the second
#           loop and did not re-write them (commented out) they are not found.
#   
#  
#   Prerequisites:
#
#       Set: 'event manager directory user policy [folder]'
#       Upload file to [folderLocation]
#       register policy: 'event manager policy [folder][filename.tcl] type user'
#       Set: 'event manager environment owner [ownerName]'
#       Set: 'event manager environment location [location]'
#
#   Call with 'event manager run [folder][filename.tcl]'
#   or
#   alias with 'alias exec [aliasName] event manager run [folder][filename.tcl]'
#
::cisco::eem::event_register_none
#::cisco::eem::description "This policy counts the number of configuration changes"
 
namespace import ::cisco::eem::*
#namespace import ::cisco::lib::*
 
puts "Get event_reqinfo:"
array set arr_reqinfo [event_reqinfo]
foreach {var val} [array get arr_reqinfo] {
   puts "$var: $val" 
}
 
puts "\nGet from router config 'event manager environment' variables."
if {![info exists owner]} {
    puts "No router owner set in config"
    puts "try setting 'event manager environment owner [ownerName]'"
} else {
    puts "Router owner is: $owner."
}
if {![info exists location]} {
    puts "No router location set."
    puts "try setting 'event manager environment location [location]'"
} else {
    puts "Router location is: $location."
}
 
 
for {set x 0} {$x<3} {incr x} {
    puts "\nLoop $x #########"
 
    puts "\nGet EEM appl_ stored variables."
    set applEric [appl_reqinfo key eric]
    if {[lindex $applEric 0] == "data"} {
        puts "Got EEM key 'Eric': [lindex $applEric 1]"
        #Do not re-write, so on the next script run we will not be able to find it.
        #In normal operation the below should be uncommented to resave the value
        #appl_setinfo key eric data "is banana man"
    } else {
        puts "Could not find EEM Key 'Eric', setting it now"
        appl_setinfo key eric data "is banana man"
    }
    
    
    set applStig [appl_reqinfo key stig]
    if {[lindex $applStig 0] == "data"} {
        puts "Got EEM Key 'Sidekick': [lindex $applStig 1]" 
        #Do not re-write, so on the next script run we will not be able to find it.
        #appl_setinfo key stig data "of the dump"
    } else {
        puts "Could not find EEM Key 'Sidekick', setting it now"
        appl_setinfo key stig data "Crow"
    }
 
 
    puts "\nGet EEM context_ stored variables."
    set test1 result1
    set test2 result2
 
    if {![catch {context_retrieve TESTCTX "test1"} tempc]} {
        puts "Found context_retrieve test1: $tempc"
        #Do not re-write, so on the next script run we will not be able to find it.
        #In normal operation the below should be uncommented to resave the value
        #if {[catch {context_save TESTCTX "testvar*"} errmsg]} {
        #	  action_syslog msg "context_save failed: $errmsg"
        #} else {
        #	  action_syslog msg "context_save succeeded"
        #      puts "context_save succeeded for test1"
        #}
        
    } else {
        puts -nonewline "Could no find context_retrieve test1, setting now. "
        if {[catch {context_save TESTCTX "test1"} errmsg]} {
            puts "Context_save failed: $errmsg"
        } else {
            puts "Context_save succeeded for test1"
        }
    }
}

Example output of the above script.

Router#
Router#event manager run eemVariables.tcl
Get event_reqinfo:
event_type_string: none
event_pub_sec: 1386554295
event_id: 17
event_pub_msec: 122
event_type: 131

Get from router config 'event manager environment' variables.
Router owner is: Eric.
Router location is: 29 Acacia Road.

Loop 0 #########

Get EEM appl_ stored variables.
Could not find EEM Key 'Eric', setting it now
Could not find EEM Key 'Sidekick', setting it now

Get EEM context_ stored variables.
Could no find context_retrieve test1, setting now. Context_save succeeded for test1

Loop 1 #########

Get EEM appl_ stored variables.
Got EEM key 'Eric': is banana man
Got EEM Key 'sidekick': Crow

Get EEM context_ stored variables.
Found context_retrieve test1: result1

Loop 2 #########

Get EEM appl_ stored variables.
Could not find EEM Key 'Eric', setting it now
Could not find EEM Key 'Sidekick', setting it now

Get EEM context_ stored variables.
Could no find context_retrieve test1, setting now. Context_save succeeded for test1

Router#