Quick Start

Installing the IxOS Tcl Client

This chapter provides a quick means of getting started with the Tcl API. An example test is presented and explained.

The IxOS Tcl Client provides an interface between an Ixia Tcl client application and Ixia IxOS Tcl functions. It runs on the Unix / Linux host.

The Windows version of IxOS Tcl Client is included with the IxOS software package; the Unix/Linux version is supplied as a separate a self-extracting archive (.bin) file. You can download it from Ixia’s website, www.ixiacom.com.

There are several versions of the IxOS Tcl Client. The correct file to install depends on the set up of the UNIX/Linux machine. Table:Tcl Client Install Files details the files and their use.

Table:Tcl Client Install Files

Install File Purpose

IxOS#.##
FreeBSD.bin

For FreeBSD operating system.

IxOS#.##Linux.bin.

For Linux platforms older than Redhat 9.

IxOS#.##Linux64.bin

For Linux 64 bit installer.

The versions of UNIX/Linux operating systems that are supported are:

Note: For 64-bit Linux systems, you should use the ixos9.10.XXX.XXXLinux64.bin. The installation is the same as described in the previous procedure.

Other versions of Linux may operate properly, but are not officially supported.

To install the IxOS TCL Client, do the following:

  1. Download the self-extracting archive that contains the Unix/Linux Tcl client.
  2. Use the following command to make the archive file executable:

    chmod +x <archive file name>

    chmod +x IxOS#.##Linux.bin

    (where #.## is the version number)

  3. Execute the archive to extract the installation files and begin the installation:

    ./<archive file name>

    ./IxOS#.##Linux.bin

    The installation is a typical InstallShield installation. The installer prompts you to select the version of the Tcl Client you want to install.

  4. Select the version and select Next.

    The installer also prompts you to select the path where the Tcl Client is installed. The default path is the current folder.

  5. Accept the default installation path or enter an alternative, then select Next.

Note: For 64-bit Linux systems, you should use the ixos6.60.XXX.XXXLinux64.bin. The installation is the same as described in the previous procedure.

About IxOS Native TCL Console for Linux

The new Platform Independent TCL includes the following executables:

Why IxOS Native Tcl Console?

When using traditional Platform Independent TCL (that is, ixtcl8.5.17 or ixtcl8.6.6) from Linux-based clients, connection to the chassis is made through the TCL server causing slowness when compared to Windows Wish Console. However, the native TCL console (that is, ixtcl8.6.8-native or ixtcl8.5.15-native) directly connects to chassis without needing TCL Server, thus improving overall performance as the number of TCL APIs increases when compared to traditional Platform Independent TCL. The behaviour of native TCL Console for Linux-based clients is similar to that of Windows Wish Console, hence the command ixConnectToTclServer returns successfully without actually doing anything (to allow executing TCL scripts written for traditional Platform Independent TCL).

UNIX Environment

On UNIX system, when IxOS client is installed, files named ixtcl and ixtcl-native are created under bin dir. This file sets up the environment variables needed to run the IxOS client and starts their respective shells.

To start up the ixtcl shell follow these steps:

  1. cd /opt/ixia/ixos-api/X.X.X.X/bin
  2. ./ixtcl

To start up the ixtcl-native shell follow these steps:

  1. cd /opt/ixia/ixos-api/X.X.X.X/bin
  2. ./ixtcl-native

When running scripts using TCL interpreter installed by the Operating System, set following environment variables as prerequisites:

  1. TCLLIBPATH=”/opt/ixia/ixos-api/X.X.X.X/lib”
  2. IXIA_VERSION=X.X.X.X

Note: TCL interpreter installed by the Operating System cannot be used to run ixtcl-native because it needs to use TCL interpreter provided by Ixia to load Ixia specific binary dependencies.

Note: PIT Notes:

Environment Variables

This section describes the environment variables that are set during installation.

Environment Variable Description

TCLLIBPATH

Contains the paths to the tcl packages (located in /opt/ixia/ixos-api/<version>/lib/<packetName>). This variable is set by ixtcl or ixwish. The paths are separated by a single space.

LD_LIBRARY_PATH

This is a colon-separated set of directories where libraries are searched before the standard set of directories. The script adds the paths to the libraries required by the packages to the existing settings of the variable.

IXIA_RESULTS_DIR

Results of all Ixia tests are placed in this directory.

IXIA_LOGS_DIR

Run-time Logs of all Ixia tests are placed in this directory.

IXIA_SAMPLES

The Samples files are located under this directory.

IXIA_VERSION It signifies the ixos-api version to be used.

UNIX Installation Notes

To run the GUI installer, your client computer must be configured with an operational X-windows server computer.

Be sure to set your DISPLAY environment variable to the host name or IP address of the client computer on which you want the installer GUI to display. The following examples explain the setting of the DISPLAY environment variable using various shells. If you need environment configuration assistance beyond this, consult your System Administrator.

// enable connections to X Server

xhost + or xhost [remote hostname]

 

// set DISPLAY environment variable

// determine shell

echo $SHELL

 

// depending on what shell you use - Bourne shell (bsh or sh),

// Bash (bash- Bourne shell again), C shell (csh) or Korn shell (ksh);

// set DISPLAY environment variable:

 

// bash:

export DISPLAY=hostname:0

 

// bsh or ksh:

DISPLAY=hostname:0

export DISPLAY

 

// csh:

setenv DISPLAY hostname:0

If you are updating an existing installation, be sure to run the installer as the same user who initially installed the software.

Always run the uninstaller before removing any files manually.

If you are installing as the root user using an install location in a network-mounted file system, ensure that you have write permission to the file system.

To install the Tcl Client on Linux computer, perform the following steps:

Note: The binary file name ‘IxOS<version>Linux.bin’ is used in the following example. In most cases, the file name is different.

  1. Download either the ZIP, BIN or TAR file from the Ixia Web site.

  2. Extract and copy all folders and files from the ZIP, BIN or TAR file into the lib folder of the IxOS client installation.
  3. Copy the IxOS<version>Linux.bin file to the Linux system.

  4. Change the file's attribute to make it executable. Example: chmod +x IxOS<version>Linux.bin

  5. Execute the IxOS installer file (use the –i gui option if your Linux version supports a graphical user interface). Example: ./IxOS<version>Linux.bin

  6. When the installer prompts you, select Tcl version 8.5 (required).

  7. Follow the rest of the instructions to complete the installation.

  8. Follow the installation prompts to complete the installation.
  9. After installation, set the following variables (

Note: The following examples match the sample installation. You must alter these parameters to match your installation.

    export IXIA_HOME=/opt/ixia/tcl/8.5.17.0 IXIA_VERSION=6.91.XXX.XXX

    export TCLLIBPATH=$IXIA_HOME/lib

  1. Alternatively, specify the following environment variable to specify the location the log, sample, and results files for IxOS:
  2. IXIA_LOGS_DIR=/tmp/Ixia/Logs

    IXIA_RESULTS_DIR=/tmp/Ixia/Results

    IXIA_SAMPLES=/tmp/Ixia//samples

    IXIA_TCL_DIR=$IxiaLibPath

  3. If the Tcl option was installed with an IxOS installation, add Ixia's bin and lib folder to the PATH and LD_LIBRARY_PATH variable to use it. For example:
  4. IxiaLibPath=$IXIA_HOME/lib

    IxiaBinPath=$IXIA_HOME/bin

    PATH=$IxiaBinPath:.:$TCLBinPath:$PATH

    LD_LIBRARY_PATH=$IxiaLibPath:$LD_LIBRARY_PATH

If the installation fails, check that there is enough disk space on the system by using the df -ak command.

There must enough space in the /tmp folder (to extract the files), and in the target folder (where files are to be installed). If the /tmp directory does not have enough space, specify the directory by setting IATEMPDIR environment and specifying the path to the folder where you have enough free space. The following example shows the use of the options:

export IATEMPDIR=<tempdir>

./IxOSx.xx.XXX.XXXLinux.bin

Windows Environment

On Windows operating system, the IxiaWish.tcl file is installed as part of the IxOS client installation. The path to the IxiaWish.tcl file is similar to this:
C:\Program Files\Ixia\IxOS\<version>\TclScripts\bin\IxiaWish.tcl

This IxiaWish.tcl file sets up the environment variables needed to run the IxOS Tcl client. When Tcl 8.5 wish is started, IxiaWish.tcl is sourced to set up the IxTclHAL environment as part of the startup.

Alternatively, you can use a third-party wish like ActiveTcl, and set up the environment for accessing the IxOS Tcl package by sourcing the file named in the path above.

Connect to IxServer

To connect to IxServer, perform the following steps:

  1. Source the environment file for tarball.
  2. ixConnectToTclServer <chassis-name>
  3. ixConnectToChassis <chassis-name>

IxSampleTcl Test Program

The IxSampleTcl.tcl file is included just below, along with comments which explain the test.

##############################################################################

# IxTclHAL Version :5.20.0.165

# Product version :5.20.0 Build 165#

# File: IxSampleTCL.tcl

#

# Copyright © 1997 - 2009 by IXIA

# All Rights Reserved.

#

# The following is an example of how streams, ports and filters are configured,

# data capture started, transmission started and statistics collected.

# The chassis is connected to first, streams are created, filters are set,

# then capture is started on Rx port and transmisssion is started on Tx port.

# After the transmition is complete, some statistics are collected and

# displayed

# to standard out.

# Note: This test requires two ports which should be connected via loopback

# cable.

#

##############################################################################

# This package is required to have access to the Ixia Tcl commands

package req IxTclHal

set userName IxiaTclUser

set hostname localhost

set retCode $::TCL_OK

 

# If on unix/linux, we must connect to the tclServer. This would need to be

# uncommented and a tclServer host name would need to be supplied. :

# NOTE: IxTclServer should not run on the chassis.

#if {[isUNIX]} {

# set retCode [ixConnectToTclServer $hostname]

#}

ixPuts "\n\tIxia Tcl Sample Script"

# Log in user

ixLogin $userName

ixPuts "\nUser logged in as: $userName"

set recCode [ixConnectToChassis $hostname]

if {$retCode != $::TCL_OK} {

return $retCode

}

 

set chasId [ixGetChassisID $hostname]

set card 1

#added line below on July 2 to make ports selectable instead of hardwired

set port1 3

set port2 4

 

# Assume transmit from port 1 to port 2 on same card for this example

set portList [list [list $chasId $card $port1] [list $chasId $card $port2]]

# Decide on some mac & ip addresses - lots of ways to do this, this is one

# example

 

set macAddress(sa,$chasId,$card,$port1) [format "be ef be ef %02x %02x" $card $port1]

set macAddress(sa,$chasId,$card,$port2) [format "be ef be ef %02x %02x" $card $port2]

set macAddress(da,$chasId,$card,$port1) $macAddress(sa,$chasId,$card,$port2)

set macAddress(da,$chasId,$card,$port2) $macAddress(sa,$chasId,$card,$port1)

 

set ipAddress(sa,$chasId,$card,$port1) [format "199.17.%d.%d" $card $port1]

set ipAddress(sa,$chasId,$card,$port2) [format "199.17.%d.%d" $card $port2]

set ipAddress(da,$chasId,$card,$port1) $ipAddress(sa,$chasId,$card,$port2)

set ipAddress(da,$chasId,$card,$port2) $ipAddress(sa,$chasId,$card,$port1)

 

# Take ownership of the ports

if [ixTakeOwnership $portList] {

return $::TCL_ERROR

}

 

proc clearOwnershipAndLogout {} {

global portList

ixClearOwnership $portList

# Log off user

ixLogout

cleanUp

}

 

# Display version information

ixPuts "\nIxTclHAL Version :[version cget -ixTclHALVersion]"

ixPuts "Product version :[version cget -productVersion]"

ixPuts "Installed version :[version cget -installVersion]\n"

# Set ports to factory defaults. Dumps out on error.

ixPuts "Setting ports to factory defaults..."

foreach item $portList {

scan $item "%d %d %d" chasId card port

if [port setFactoryDefaults $chasId $card $port] {

errorMsg "Error setting factory defaults on $chasId.$card.$port]."

clearOwnershipAndLogout

return $::TCL_ERROR

}

}

# Writes port properties in hardware

if {[ixWritePortsToHardware portList]} {

clearOwnershipAndLogout

return $::TCL_ERROR

}

 

# Check the link state of the ports

if {[ixCheckLinkState portList]} {

clearOwnershipAndLogout

return $::TCL_ERROR

}

 

ixPuts "Configuring streams..."

ixGlobalSetDefault

protocol config -ethernetType ethernetII

protocol config -name ip

# Set up some generic stream config items that are shared on all streams

# generated.

 

 

stream config -numFrames 10

stream config -rateMode streamRateModePercentRate

stream config -percentPacketRate 42

 

 

foreach item $portList {

scan $item "%d %d %d" chasId card port

set frameSize 64 ;# we will make 20 streams w/incr. framesizes

 

ip config -sourceIpAddr $ipAddress(sa,$chasId,$card,$port)

ip config -destIpAddr $ipAddress(da,$chasId,$card,$port)

 

######debug lines added by cz june 26#####

puts "debug info source IP address for port $port is:$ipAddress(sa,$chasId,$card,$port)"

puts "debug info destination IP address for port $port is:$ipAddress(da,$chasId,$card,$port)"

######debug#####

 

if [ip set $chasId $card $port] {

logMsg "Error setting IP on $chasId,$card,$port"

set retCode $::TCL_ERROR

break

}

stream config -sa $macAddress(sa,$chasId,$card,$port)

stream config -da $macAddress(da,$chasId,$card,$port)

 

######debug lines added by cz june 26#####

puts "debug info source MAC for port $port is:$macAddress(sa,$chasId,$card,$port)"

puts "debug info destination MAC for port $port is:$macAddress(da,$chasId,$card,$port)"

######debug#####

 

stream config -dma advance

set udfPattern [lrange [stream cget -da] 2 end]

######debug lines added by cz june 26#####

puts "udfPattern is :$udfPattern"

######debug#####

udf config -enable true

udf config -offset 42

udf config -initval $udfPattern

udf config -countertype c32

udf config -maskselect {00 00 00 00}

udf config -maskval {00 00 00 00}

udf config -random false

udf config -continuousCount false

udf config -repeat 1

if [udf set 4] {

errorMsg "Error setting UDF 4"

set retCode $::TCL_ERROR

break

}

# Configure 20 streams on Tx port

for {set streamId 1} {$streamId < 20} {incr streamId} {

stream config -name "Stream $streamId - IP sample stream"

stream config -framesize $frameSize

incr frameSize 42

if [stream set $chasId $card $port $streamId] {

errorMsg "Error setting stream $chasId,$card,$port.$streamId -

$ixErrorInfo"

set retCode $::TCL_ERROR

break

}

}

 

incr streamId -1

# Set last stream to STOP

stream config -dma stopStream

if [stream set $chasId $card $port $streamId] {

errorMsg "Error setting stream $chasId,$card,$port.$streamId -

$ixErrorInfo"

set retCode $::TCL_ERROR

break

}

 

#### TK change

set rxUdfPattern [lrange $macAddress(sa,$chasId,$card,$port) 2 end]

 

# Set the filter parameters

filterPallette config -pattern2 $rxUdfPattern

filterPallette config -patternOffset2 [udf cget -offset]

filter config -userDefinedStat2Pattern pattern2

filter config -userDefinedStat2Enable true

filter config -userDefinedStat2Error errGoodFrame

filter config -captureTriggerEnable true

filter config -captureFilterEnable true

if [filterPallette set $chasId $card $port] {

errorMsg "Error setting filter pallette for $chasId,$card,$port."

set retCode $::TCL_ERROR

break

}

if [filter set $chasId $card $port] {

errorMsg "Error setting filters on $chasId,$card,$port."

set retCode $::TCL_ERROR

break

}

}

 

# Dump out now if there were any errors.. maybe you want to throw instead of a

# return.

if {$retCode != $::TCL_OK} {

clearOwnershipAndLogout

return $retCode

}

 

# Writes all the configuration on ports in hardware

# NOTE: This does NOT take link down, so no point in checking link state

# afterward and no need for any delays

# Also note that this is an example of a throw instead of a return

if [ixWriteConfigToHardware portList] {

return -code error

}

# Zero all statistic counters on ports

if [ixClearStats portList] {

return -code error

}

ixPuts "Start capture..."

if [ixStartCapture portList] {

return -code error

}

ixPuts "Start transmit..."

if [ixStartTransmit portList] {

return -code error

}

# Let it transmit for a bit; if this were a real test, we might want to wait for

# approx. the total transmit time. Since it's not, 1 sec is sufficient for the

# streams we've created.

after 1000

# Checks whether transmission is done on a group of ports

if {[ixCheckTransmitDone portList] == $::TCL_ERROR} {

clearOwnershipAndLogout

return -code error

} else {

ixPuts "Transmission is complete."

}

 

# Stop capture on ports - not really necessary, as any read of capture will

# automatically stop capture

ixPuts "Stop capture..."

if [ixStopCapture portList] {

clearOwnershipAndLogout

return -code error

}

 

# This api will request stats from all ports in the portList - it's really

# efficient and the best way to collect stats when you have multiple ports to

# contend with.

ixRequestStats portList

foreach item $portList {

scan $item "%d %d %d" chasId card port

if {[statList get $chasId $card $port]} {

ixPuts "Error getting stats for $chasId,$card,$port"

set retCode $TCL_ERROR

break

}

 

# note that if a stat is not supported on a particular port type, the cget

# will throw so it is best to protect that in the following fashion:

if [catch {statList cget -scheduledFramesSent} numTxFrames ] {

set numTxFrames 0

ixPuts "WARNING: -scheduledFramesSent not supported on

$chasId,$card,$port. Value set to 0"

}

 

if [catch {statList cget -userDefinedStat2} numRxFrames ] {

set numRxFrames 0

ixPuts "WARNING: -userDefinedStat2 not supported on $chasId,$card,$port.

Value set to 0"

}

 

if [captureBuffer get $chasId $card $port 1 $numRxFrames] {

ixPuts "Error getting captureBuffer on $chasId $card $numRxFrames"

set retCode $::TCL_ERROR

#break removed by cz on July 2nd 2009

#break

}

 

ixPuts "Port: $chasId,$card,$port"

ixPuts -nonewline "Speed: [stat getLineSpeed $chasId $card $port]\t"

ixPuts -nonewline "Frames sent: $numTxFrames\t"

ixPuts -nonewline "Frames Rcvd: $numRxFrames\t"

ixPuts "Number of packets captured :[captureBuffer cget -numFrames]\n"

}

 

ixPuts "\nSample test complete.\n"

clearOwnershipAndLogout