Xena Scripting API

This manual describes the Xena Scripting API for the XenaBay and XenaCompact layer 2-3 test products.

As an alternative to using the XenaManager, you can interact with the testers using a command-line interface (CLI). This also allows the tester to be controlled from a scripting environment, and be part of a larger automation environment.

Detailed Script Parameters

To see the individual parameters, please visit the following pages:

Overview

Everything that can be done using the XenaManager can also be done through scripting, and in a nearly identical fashion. (Please keep this in mind even though most of the examples use the XenaManager for illustration.)

The commands are simple lines of text exchanged between a client and the Xena chassis. An example command to the chassis could be:

0/5 PS_RATEPPS [3] 500000

This goes to module 0, port 5, and sets stream 3’s rate to 500000 packets per second. The chassis responds with:

<OK>

You would query for the current value this way:

0/5 PS_RATEPPS [3] ?

And the chassis would respond in exactly the same way that you set the value yourself:

0/5 PS_RATEPPS [3] 500000

Note that this is exactly the same syntax used when saving and loading port configurations to files on the client PC. This lets you use saved configurations as a starting point for scripting, and it also allows you to modify the saved files before loading them back into the chassis.

Scripting Explained

The chassis of the Xena test platform can be controlled in two separate fashions: in a point-and-click interactive style using XenaManager, and in a command-line-interface style using a text-based scripting interface.

The script commands are simple lines of text exchanged between a client and the Xena chassis. An example command to the chassis could be:

0/5 PS_RATEPPS [3] 500000

This goes to module 0, port 5, and sets stream 3’s rate to 500000 packets per second. The chassis responds with:

<OK>

You would query for the current value this way:

0/5 PS_RATEPPS [3] ?

And the chassis would respond in exactly the same way that you set the value yourself:

0/5 PS_RATEPPS [3] 500000

This document contains a general overview of the scripting mechanism, followed by reference sections describing each group of scriptable parameters in detail. There are a few hundred parameters in total, but only a handful is required for typical simple tasks.

To set up basic traffic patterns and obtain traffic statistics, use the port parameters (starting with P_…), the stream parameters (starting with PS_…), and the transmit/receive statistics parameters (starting with PT_… and PR_…).

At the end of the overview sections there is a complete example of how to use a collection of script commands to define and execute some simple operations on a chassis.

Connecting to the Chassis

The chassis support multiple concurrent scripting sessions, just like they support multiple concurrent interactive Manager sessions. And like Manager sessions, scripting sessions interact with the chassis in its current state; establishing a scripting session does not in itself impact the chassis state.

In order to start a scripting session, you establish a TCP/IP connection with the chassis using port 22611, on the same IP address as when using XenaManager.

You then send lines of ASCII text to the chassis, terminated by CR/LF, and receive lines of ASCII text in response. The first command should be a logon with the valid password for the chassis, or the session will be terminated.

You can use any client platform that is able to establish a TCP/IP connection and send and receive lines of text through it. Typical client platforms include Tcl, Perl, Python, Java, Excel/VBA, and Telnet. You may use client-side functionality to execute script commands conditionally or repetitively.

REMEMBER: all lines sent to the chassis must be terminated by CR/LF. You will need to include these characters explicitly if the connection library of your platform does not do so automatically.

ALSO: please make sure to read all the responses send back to you from the chassis, so that the buffer is empty when the connection is eventually closed down.

Xena also provides a simple interactive scripting client application that runs on Windows and allows you to manually type commands to the chassis and see its responses.

client2

Figure 1 The Xena Script Client used to change a chassis description.

To keep the session alive the client must show some activity every minute or so; else the chassis will assume that the client has stopped, and there are also routers that will kill a TCP session that is inactive for more than a few minutes. The simplest way is to send an empty line, and the chassis will also respond with an empty line. The timeout interval can be changed with the C_TIMEOUT command, so that for instance C_TIMEOUT 99999 effectively disables the timeout.

Chassis resources must as always be reserved before they can be updated, whereas you can view any chassis, module, or port parameter as soon as the session is logged on. Reserving and releasing is done through the C/M/P_RESERVATION commands.

Before reservation, a user name must be provided for the scripting session using the C_OWNER command. If the chassis has resources reserved to this username they will automatically be granted to this session.

Any line starting with a semicolon is treated as a comment and ignored by the chassis, e.g.:

;This script implements the RFC2544 suite

Commands to the chassis are not case-sensitive, and replies from the chassis are in upper-case.

Relation to XenaManager

Anything you can do with XenaManager application you can also do via scripting, and the correspondence is quite straightforward. For example, just as the Manager’s PORT PROPERTIES panel has a field for viewing and changing a port’s minimum inter-frame gap, the scripting interface can view and change the P_INTERFRAMEGAP parameter for doing the same. The same applies to most of the other fields of the Manager’s user interface.

However, there are a few areas where the Manager has more advanced functionality which is missing in the scripting interface. This does not limit what you can do, but the way you must do it is more primitive.

  • Stream rates and capping. When you specify the rate of a stream using either a percentage, layer-2 Mbps, or packets per second, the Manager calculates the equivalent rates using the other two methods. It also checks that you do not exceed the available bandwidth for the port. This is not available through scripting: you just specify the rate using your method of choice, and you must take care not to exceed the available bandwidth.
  • Protocol field editing. The Manager knows the field-by-field layout of various common protocols, and allows you to inspect and edit packet data at the field level. With scripting you just specify packet data as a sequence of hexadecimal bytes.
  • Filter conditions. The Manager allows you to enter filter conditions as an easy-to-read Boolean expression on the various terms. With scripting you need to encode the condition using a set of bitmasks.
  • Capture protocol decoding. The Manager inspects the raw bytes of captured packets in order to identify the protocols at the header of the packet. With scripting you must decode the packet data yourself if needed.

Also, the manager will disable the user-interface whenever a particular operation is not currently allowed; for instance trying to update the configuration of a port that has not been reserved, changing a parameter for an enabled stream while traffic is on, or changing a filter term used in the condition of an enabled filter. Attempting such things in a scripting session will instead lead to error status messages.

At a more fundamental level, the Manager supports the notion of a testbed containing multiple chassis. This is not applicable through scripting, since each scripting session runs through its own connection to a single chassis, and indeed the chassis are not aware of each other. Any cross-chassis control must be handled at the scripting client environment; in particular cross-chassis statistics such as packet loss.

In contrast, the scripting environment provides wild-carding across modules and ports, which is not available through the Manager.

Command Syntax

The scripting language contains similar syntax for setting and getting values of individual parameters of the chassis resources. Some parameters, like inter-frame gap, support both set and get; others, like physical port type, support only get; and a few, like injecting errors, support only set.

You change the value of a settable parameter using:

module/port parameter [index,…] value value

Here, module and port are the numeric indices for a particular port (for chassis-level parameters neither of these are present, and for module-level parameters only module is present); parameter is one of the names specified later in this document in the reference sections; index is a possible sub-index of the parameter, for instance identifying a stream; and each value specifies a value appropriate for the particular parameter. All indices start at zero.

Values are specified using one of the following formats:

  • Integer (I): decimal integer, in the 32-bit range, e.g.: 1234567.
  • Long (L): decimal integer, in the 64-bit range, e.g.: 123456789123.
  • Byte (B): decimal integer, in the 8-bit range, e.g.: 123.
  • Hex (H): two hexadecimal digits prefixed by 0x, e.g.: 0xF7.
  • String (S): printable 7-bit ASCII characters enclosed in ”, e.g.: ”A string”. Characters with values outside the 32-126 range and the ” character itself are specified by their decimal value, outside the quotation marks and separated by commas, e.g.: ”A line”,13,10,”and the next line”.
  • Owner (O): a short string used to identify an owner, used for reservation.
  • Address (A): a dot-separated IP address, e.g.: 192.168.1.200.

Some parameters allow a variable number of values of a particular type (I*, B*, H*), and these are simply written with spaces in between. For hex values (H*), multiple bytes can be specified using a single0x prefix, e.g.: 0xF700ABCD2233.

Finally, certain parameters are actually integers, but use coded names for special numeric values to enhance readability, e.g.: (0=OFF,1=ON).

You query the current value of a gettable parameter using a very similar syntax:

module/port parameter [index,…] ?

The chassis responds with a line using identical syntax to the change-command, containing the current values. These responses can therefore be ‘replayed’ back to the chassis to re-establish the value from a previous query. This is actually the core of the load/save mechanism of the Xena Manager, as you can see by using an ordinary text editor to inspect the local files produced by save. You can also change the content if you want to; it is not interpreted by the Xena Manager.

Note that some queries, like P_INFO ? and P_CONFIG ?, are special in that they do not refer to one particular parameter, but rather to a collection of parameters. The response is multiple lines containing the current value of each of these parameters.

Status Messages

The set/change commands themselves simply produce a reply from the chassis of:

<OK>

In case something is unacceptable to the chassis, it may return one of the following status messages:

<NOTLOGGEDON> You have not issued a C_LOGON providing the chassis password.

<NOTRESERVED> You have not issued a x_RESERVATION for the resource you want to change.

<NOTWRITABLE> The parameter is read-only.

<NOTREADABLE> The parameter is write-only.

<NOTVALID> The operation is not valid in the current chassis state, e.g. because traffic is on.

<BADMODULE> The module index value is out of bounds.

<BADPORT> The port index value is out of bounds.

<BADINDEX> A parameter sub-index value is wrong.

<BADSIZE> The size of a data value is not appropriate.

<BADVALUE> A value is not appropriate.

<FAILED> An operation failed to produce a result.

In case of a plain syntax error, misspelled parameter, or an inappropriate use of module/port/indices, the chassis will return a line pointing out the column where the error was detected, e.g.:

0/5 PS_RATEPPS [] 5q00
---^
#Syntax error in column 24

Defaults and Wild-carding

The scripting environment provides you with optional default values for the module index and port index, allowing you to change and query parameters without providing the module and port index explicitly.

Default indices are enabled and disabled using the following short commands:

module/port Set default module and port to the specified values.

port Set default port to the specified value, retaining the default module.

-/- Disable the default module and port.

– Disable the default port, retaining the default module.

module/- Set the default module, and disable the default port.

? Show the current default module and port.

When a default module and port is provided, parameters that would otherwise require explicit module and port index values can be written without them, e.g.:

PS_RATEPPS [3] 500
^---
#Index error in column 1
0/5
PS_RATEPPS [3] 500
<OK>

Replies from the chassis will also use the current default values to suppress the explicit module and port indices when possible.

The scripting environment also provides wild-carding across modules and ports. Using an asterisk as a module or port index effectively makes the chassis execute the command for each value, e.g.:

0/* P_INTERFRAMEGAP 30

This sets the inter-frame gap for every port on module 0. It will generate an individual status response for each operation, and indeed some may succeed while others fail, for instance due to lack of reservation.

Wild-cards also work for queries. This will give you the inter-frame gap for each port of module 0:

0/* P_INTERFRAMEGAP ?

Wild-cards cannot be used as default values, but the default and wild-card mechanisms can be combined, for instance to use a default module together with a wild-carded port:

0/-
* P_INTERFRAMEGAP 30

Indeed, for chassis with a single module you will typically set it as the default module and then use only port indices.

Special Scripting Commands

The scripting environment provides a few commands that do not directly interact with the chassis state, but rather support the scripting process itself.

  • SYNC. This command simply produces a reply of <SYNC>, which can be helpful when parsing and delimiting the lines returned from the chassis, in particular when using multi-parameter queries. You can also do SYNC ON, which will subsequently cause an automatic SYNC after each command. SYNC OFF disables this.
  • WAIT n. This command waits for the specified number of seconds, up to 60, and then produces a reply of <RESUME>. This is a simple mechanism for inserting pauses into scripts that are contained in a file and simply sent to the chassis line-by-line. Longer waits and more sophisticated automation require client-side functionality, which must also handle the keep-alives.
  • HELP ?. This command gives you an overview of the built-in help function, useful when using the scripting environment interactively, as from the Xena Scripting Client.
  • HELP ”parameter”. Gives you a brief overview of the required indices and values for the specified parameter. You are allowed to specify only a prefix of the parameter name, which will then give you the overview for each matching parameter, e.g.: HELP ”P_” for all port-level parameters. The summary of the required values uses the abbreviations for the various types introduced in the command syntax above, e.g.:B(0=OFF,1=ON) which means a single byte value where the two relevant values can be specified using coded names.

Sample Script Session

Below is an example of using the scripting commands to define and execute a simple test. A file containing these commands can simply be uploaded to a chassis using the XenaScripting Client.

You can download the file here:

samplescript

Output from Sample Session

Below you can download a file containing the output generated by the chassis when it receives the commands shown in the previous section. A dump like this can be obtained and saved using the XenaScriptClient.

You need to do a line-by-line correlation of the two lists in order to fully understand the output. Note that there are sections of blank lines in the output corresponding to the comment lines in the input.

sampleoutput