7

Using CLI Scripting

This chapter includes the following sections:

G G G G

Overview on page 289 Setting Up Scripts on page 289 Displaying CLI Scripting Information on page 296 CLI Scripting Examples on page 298

Overview
CLI-based scripting allows you to create a list of commands that you can execute manually with a single command or automatically when a special event occurs. CLI-based scripting supports variables and functions, so that you can write scripts that operate unmodified on multiple switches and in different environments. CLI-based scripting allows you to significantly automate switch management. NOTE
Special scripts can be used to configure the switch when it boots. For more information, see Using Autoconfigure and Autoexecute Files on page 1336.

Setting Up Scripts
The following sections describe the tasks for creating, configuring, and executing scripts:
G G G G G G G G G G G

Enabling and Disabling CLI Scripting on page 290 Creating Scripts on page 290 Using Script Variables on page 291 Using Special Characters in Scripts on page 292 Using Operators on page 292 Using Control Structures in Scripts on page 293 Using Built-In Functions on page 294 Controlling Script Configuration Persistence on page 295 Saving, Retrieving, and Deleting Session Variables on page 295 Executing Scripts on page 296 Configuring Error Handling on page 296

ExtremeXOS Concepts Guide, Software Version 12.3

289

Using CLI Scripting

Enabling and Disabling CLI Scripting

CLI scripting is disabled by default. To support scripting, including the testing of script-related commands, you must enable scripting using the following command:
enable cli scripting {permanent}

The permanent option enables CLI scripting for new sessions only and makes the configuration change part of the permanent switch configuration so that the scripting configuration remains the same when the switch reboots. When the command is used without the permanent option, it enables CLI scripting for the current session only. If you do not include the permanent option, CLI scripting is disabled the next time the switch boots. To disable scripting, enter the following command:
disable cli scripting {permanent}

Creating Scripts
There are two ways to create scripts. The method you choose depends on how you want to execute the script. If you want to create a script file to configure a switch or a switch feature, and you plan to execute that script manually, you can create a script file. If you want to create a script that is activated automatically when a device or user connects to or disconnects from a switch port, you should create the script with the Universal Port feature. The following sections provide more information on these options.

Creating a Script File

A script file is an ASCII text file that you can create with any ASCII text editor program. The text file can contain CLI commands and can use the scripting options described in the following sections:
G G G G G

Using Script Variables on page 291 Using Special Characters in Scripts on page 292 Using Operators on page 292 Using Control Structures in Scripts on page 293 Using Built-In Functions on page 294

You can move an ASCII script file to the switch using the same techniques described for managing ASCII configuration files in Appendix B, Software Upgrade and Boot Options.

Creating Scripts for Use with the Universal Port Feature

The Universal Port feature allows you to create dynamic profiles that are activated by a trigger event, such as a user or device connection to a switch port. These dynamic profiles contain script commands and cause dynamic changes to the switch configuration to enforce a policy. The universal port profiles support all the scripting options listed above for creating script files. For more information on entering script commands in a universal port profile, see Chapter 6, Universal Port.

290

ExtremeXOS Concepts Guide, Software Version 12.3

Setting Up Scripts

Using Script Variables

Table 29 shows the predefined system variables that are always available for use by any script. Predefined variables are automatically set up for use before a script or profile is executed. NOTE
You must enable CLI scripting before using these variables or executing a script.

Table 29: Predefined System Variables

Variable Syntax $STATUS $CLI.USER $CLI.SESSION_TYPE Definition Status of last command execution. UserName who is executing this CLI. Type of session of the user.

Table 30 shows the system variables that you must define before use.

Table 30: System Variables that Must be Created

Variable Syntax $CLI.OUT Definition Output of last show command. The maximum size of this variable is 1 MB. This output can be used for operations such as match and regexp. For more information on these operations, see Using Built-In Functions on page 294. You must define this variable before it is used. To define this variable, enter either of the following statements: set var CLI.OUT " " set var CLI.OUT 0 Extreme Networks recommends that you delete this variable after each use.

You can create your own variables and change the values of variables. To create a variable and set a value for it, or to change a variable value, use the following command:
set var <varname> <_expression>

When using variables, the following guidelines apply:

G G G G G

Variable names are case insensitive and are limited to 32 characters. The variable name must be unique. A variable can be referenced as $X or $(X). If a variable already exists, it is overwritten. No error message is displayed. The expression can be a constant value, another variable, or a combination of the above with operators and functions. Operators are described in Using Operators on page 292, and functions are described in Using Built-In Functions on page 294. Only the set var CLI command supports expression evaluation. If the variable name X contains special characters such as +-/*, then the variable needs to be enclosed in parentheses. For example: set var z ($(x) + 100). When you use a variable with a special character, such as a period, in a TCL function, the variable must be enclosed in braces. For example: set var x $TCL(string length ${CLI.USER}). For more information on TCL functions, see Using Built-In Functions on page 294.

G G

ExtremeXOS Concepts Guide, Software Version 12.3

291

Using CLI Scripting The following examples show various ways to define or change variables:
set var x 100 set var x ($x + 2) set var y ($x - 100)

To display all variables or a specified variables, use the following command:

show var {<varname>}

Using Special Characters in Scripts

The dollar sign ($) character and quote (") characters have special purposes in scripts. The dollar sign character indicates a variable, and the quote characters surround text strings. To use these characters as regular characters, precede the special character with a backslash character. For example:
set var variablename \$<varname> set var $CLI.USER Robert \"Bob\" Smith

Scripts also support quote characters within quotes.

Using Operators
Operators allow you to manipulate variables and evaluate strings. Some operators can be used in all numeric expressions, while others are restricted to integer or string expressions. Table 31 lists the operators supported and provides comments on when they can be used. The valid operators are listed in decreasing order of precedence.

Table 31: Operators

Operator + ~ ! * / % + << >> < > <= >= == != Action Unary minus Unary plus Bit-wise NOT Logical NOT Multiply Divide Remainder Add Subtract Left shift Right shift Boolean less Boolean greater Boolean less than or equal Boolean greater than or equal Boolean equal Boolean not equal Each operator produces a zero or one result. These operators are valid for all operand types. These operands are valid for integer operands only. A right shift always propagates the sign bit. Each operator produces 1 if the condition is true, 0 otherwise. These operators can be applied to strings as well as numeric operands, in which case string comparison is used. None of these operands can be applied to string operands, and the remainder operand can be applied only to integers. The remainder always has the same sign as the divisor and an absolute value smaller than the divisor. These operands are valid for any numeric operations. Comments None of these operands can be applied to string operands, and the bit-wise NOT operand can be applied only to integers.

292

ExtremeXOS Concepts Guide, Software Version 12.3

Setting Up Scripts

Table 31: Operators (Continued)

Operator & ^ Action Bit-wise AND Bit-wise exclusive OR Bit-wise OR Logical AND Comments This operator is valid for integer operands only. This operator is valid for integer operands only. This operator is valid for integer operands only. This operator produces a result of 1 if both operands are nonzero. Otherwise, it produces a result of 0. This operator is valid for numeric operands only (integers or floating-point). This operator produces a result of 0 if both operands are zero. Otherwise, it produces a result of 1. This operator is valid for numeric operands only (integers or floating-point).

|
&&

||

Logical OR

x?y:z

If-then-else (as in the C programming language)

If x evaluates to non-zero, then the result is the value of y. Otherwise the result is the value of z. The x operand must have a numeric value.

Using Control Structures in Scripts

The CLI supports the control structures described in the following sections:
G G

Conditional Execution on page 293 Loop While Condition is TRUE on page 293

Conditional Execution
IF (<expression>) THEN <statements> ELSE <statements> ENDIF The expression must be enclosed in parentheses.

Loop While Condition is TRUE

WHILE (<expression>) DO <statements> ENDWHILE The expression must be enclosed in parentheses. Nesting is supported up to five levels. The Ctrl-C key combination can be used to break out of any While loop(s). The operators mentioned in Using Operators on page 292 can be used in an expression in the set
var command or in an IF or WHILE condition.

ExtremeXOS Concepts Guide, Software Version 12.3

293

Using CLI Scripting If there is incorrect nesting of an IF condition or WHILE loop, an error message appears. If a user tries to type more than five WHILE loops or five IF conditions, an error message appears. Breaking out of any number of WHILE loops always clears the WHILE condition. Comments can be inserted by using the number sign (#).

Using Built-In Functions

Built in functions allow you to manipulate and evaluate the variables inside your script and the script output. Table 32 shows the built-in functions. Table 33 shows the built-in Tool Command Language (TCL) functions.

Table 32: Built-In Functions

Syntax $MATCH(string 1, string 2) $READ(prompt) $TCL(function args) Function Compares the two strings string 1 and string 2. Returns 0 if string1 matches string2. It returns -1,0, or 1, depending on whether string1 is less than, equal to, or greater than string2. Displays a prompt for user input and accepts input until the user presses [Return] or the session times out. Replace prompt with the prompt to display to the user. Calls a TCL built-in function (seeTable 33). Note that the software does not support the simultaneous operation of multiple TCL functions. For more information on TCL functions, go to http://www.tcl.tk/man/tcl8.3/TclCmd/ contents.htm. $UPPERCASE(string) $VAREXISTS(varname) Returns the string uppercased. Returns zero if the specified variable does not exist. Returns non-zero if the specified variable does exist.

Table 33: Supported TCL Functions

Function append binary clock concat expr join lappend lindex linsert list llength lrange lreplace lsearch lsort regexp Function Type String handling String handling System related List handling Math List handling List handling List handling List handling List handling List handling List handling List handling List handling List handling String handling Description Append to variable. Insert and extract fields from binary strings. Obtain and manipulate time. Join lists together. Evaluate an expression. Create a string by joining list elements together. Append list elements onto a variable. Retrieve an element from a list. Insert elements into a list. Create a list. Count the number of elements in a list. Return one or more adjacent elements from a list. Replace elements in a list with new elements. See if a list contains a particular element. Sort the elements of a list. Match a regular expression against a string.

294

ExtremeXOS Concepts Guide, Software Version 12.3

Setting Up Scripts

Table 33: Supported TCL Functions (Continued)

Function regsub re_syntax split string Function Type String handling String handling List handling String handling Description Perform substitutions based on regular expression pattern matching. Syntax of TCL regular expressions. Split a string into a proper TCL list. Manipulate strings.

NOTE
When you use a variable with a special character, such as a period, in a TCL function, the variable must be enclosed in braces. For example: set var x $TCL(string length ${CLI.USER}).

For examples of scripts that use TCL functions, see CLI Scripting Examples on page 298.

Controlling Script Configuration Persistence

When a script runs, the commands within the script can make persistent changes to the switch configuration, which are saved across reboots, or it can make non-persistent changes. Non-persistent configuration changes remain part of the switch configuration only until the switch reboots. The default setting for scripts is non-persistent. To change the script configuration persistence setting, use the following command:
configure cli mode [persistent | non-persistent]

Saving, Retrieving, and Deleting Session Variables

Session variables are the set of variables that are active for a particular session. For example, if a device is detected on a universal port and this triggers a profile (and the script commands within it), the variable values that were active when the profile started are replaced with the variable values defined in the profile. The first session is the device-undetected session, and the second session is the devicedetected session. Each session has its own set of variables and values. The software allows you to save session variables before replacing them. In the example above, this allows you to retrieve the earlier values when the port returns to the device-undetected state. Up to five variables can be saved or retrieved at a time. These variables are saved to system memory using a key, which is an ID for the saved variables. When you want to retrieve the variables, you use the key to identify the variables to be retrieved. To save up to five session variables, use the command:
save var key <key> [<var1> <var2> ]

To retrieve saved session variables, use the command:

load var key <key> [<var1> <var2> ]

To delete saved session variables, use the command:

delete var key <key>

ExtremeXOS Concepts Guide, Software Version 12.3

295

Using CLI Scripting The variables saved by the save var command are saved using the specified key and are retrievable and restored in the context that this profile was applied. They are available to rollback events like userunauthenticate and device-undetect. You are responsible for generating unique keys.

Executing Scripts
You can execute scripts by loading a script file or through the Universal Port feature.

Executing a Script File

To execute a script file, transfer the script file to the switch and use the load script <filename>
{arg1} {arg2} ... {arg9} command.

Executing a Universal Port Script

Universal port scripts are called profiles and are executed based on several types of trigger events, including device detection and undetection and user authentication and unauthentication. For information on how to create profiles and configure the triggers, see Chapter 6, Universal Port.

Configuring Error Handling

The following command controls script error handling:
configure cli mode scripting [abort-on-error | ignore-error]

The default error handling behavior is to ignore errors. You can change options within the scripts.

Displaying CLI Scripting Information

You can use the information in the following sections to display CLI scripting information:
G G

Viewing CLI Scripting Status on page 297 Viewing CLI Scripting Variables on page 298

296

ExtremeXOS Concepts Guide, Software Version 12.3

Displaying CLI Scripting Information

Viewing CLI Scripting Status

The show management command displays whether or not CLI scripting is enabled, whether or not the configuration is persistent, and the CLI scripting error mode as shown in the following example:
show management

X450a-24t.2 # show management CLI idle timeout CLI max number of login attempts CLI max number of sessions CLI paging CLI space-completion CLI configuration logging CLI scripting CLI scripting error mode CLI persistent mode Telnet access SSH Access Web access Total Read Only Communities Total Read Write Communities RMON SNMP access : : : : : : : : : : : : : : : : : : : : Enabled (20 minutes) 5 16 Enabled (this session only) Disabled (this session only) Disabled Disabled (this session only) Ignore-Error (this session only) Persistent (this session only) Enabled (tcp port 23 vr all) Access Profile : not set ssh module not loaded. Enabled (tcp port 80) 1 1 Disabled Enabled Access Profile Name : not set Enabled Flags 2E 2E 2E 2E 2E 2E

SNMP Traps SNMP v1/v2c TrapReceivers Destination Source IP Address 10.255.43.38 /10550 10.255.43.11 /10550 10.255.99.13 /10550 10.255.57.2 /10550 10.255.43.15 /10550 10.255.42.81 /10550 Flags: Version: 1=v1 2=v2c Mode: S=Standard E=Enhanced InPkts 0 Gets 0 Sent 6

SNMP stats: SNMP traps:

OutPkts 6 Errors 0 GetNexts 0 Sets 0 AuthTraps Enabled

AuthErrors 0

ExtremeXOS Concepts Guide, Software Version 12.3

297

Using CLI Scripting

Viewing CLI Scripting Variables

You can use the show var command to display the currently defined variables and their values as shown in the following example:
SummitX450-24x.4 # show var ---------------------------------------Count : 3 --------------------------------------------------------------------------------------------------------variableName variableValue -------------------------------- -------------------------------CLI.SESSION_TYPE serial CLI.USER admin STATUS 0 ------------------------------------------------------------------

Controlling CLI Script Output

When the load script command is entered, the software disables CLI scripting output until the script is complete, and then CLI scripting output is enabled. When the CLI scripting output is disabled, the only script output displayed is the show var command and its output. When the CLI scripting output is enabled, all script commands and responses are displayed. Use the enable cli scripting output and disable cli scripting output commands to control what a script displays when you are troubleshooting.

CLI Scripting Examples

The following script creates 100 VLANS with IP Addresses from 10.1.1.1/16 to 10.100.1.1/16:
enable cli scripting Set var count 1 while ($count < 101) do Create vlan v$count configure vlan v$count ipaddress 10.$(count).1.1/16 set var count ($count + 1) endwhile show vlan

The following script displays the date and time:

set var CLI.OUT " " show switch set var date $TCL(lrange ${CLI.OUT} 27 29) set var year $TCL(lrange ${CLI.OUT} 31 31) set var date $TCL(linsert $date 3 $year) set var time $TCL(lrange ${CLI.OUT} 30 30) show var date show var time

298

ExtremeXOS Concepts Guide, Software Version 12.3

CLI Scripting Examples The following script sorts the FDB table in descending order:
set var CLI.OUT " " show fdb set var x1 $TCL(split ${CLI.OUT} "\n") set var x2 $TCL(lsort -decreasing $x1) set var output $TCL(join $x2 "\n") show var output

The following script extracts the MAC address given the age of an FDB entry:
set var CLI.OUT " " show fdb set var input $TCL(split ${CLI.OUT} "\n") set var y1 $TCL(lsearch -glob $input *age*) set var y2 $TCL(lindex $input $y1) set var y3 $TCL(split $y2 " ") set var y4 $TCL(lindex $y3 0) show var y4

ExtremeXOS Concepts Guide, Software Version 12.3

299