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#.## |
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:
- Red Hat Enterprise Linux 7 and Red Hat Enterprise Linux 8
- Ubuntu 18, Ubuntu 19, Ubuntu 20
- CentOS 7, CentOS 8
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:
- Download the self-extracting archive that contains the Unix/Linux Tcl client.
-
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)
-
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.
-
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.
- 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:
- Existing executables: ixtcl8.5.17, ixtcl8.6.6, ixwish8.5.17, ixwish8.6.6
- New executables: ixtcl8.6.8-native, ixtcl8.5.15-native, ixwish8.5.15-native, ixwish8.6.8-native
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:
- cd /opt/ixia/ixos-api/X.X.X.X/bin
- ./ixtcl
To start up the ixtcl-native shell follow these steps:
- cd /opt/ixia/ixos-api/X.X.X.X/bin
- ./ixtcl-native
When running scripts using TCL interpreter installed by the Operating System, set following environment variables as prerequisites:
- TCLLIBPATH=”/opt/ixia/ixos-api/X.X.X.X/lib”
- 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:
- The Platform Independent tgz packages do not contain Perl, Python or Tcl interpreters. The Ixia dependencies (mpexpr, snit, tclx) are also not included. Download the all-in-one language packages and dependencies installer for Linux x86 and x64 to use with any app PIT installer from the Ixia website.
- It is required to install lftp, in case you want to connect to a Virtual Machine (VM) chassis through Tcl, from a Linux client.
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.
-
Download either the ZIP, BIN or TAR file from the Ixia Web site.
- Extract and copy all folders and files from the ZIP, BIN or TAR file into the lib folder of the IxOS client installation.
-
Copy the IxOS<version>Linux.bin file to the Linux system.
-
Change the file's attribute to make it executable. Example: chmod +x IxOS<version>Linux.bin
-
Execute the IxOS installer file (use the –i gui option if your Linux version supports a graphical user interface). Example: ./IxOS<version>Linux.bin
-
When the installer prompts you, select Tcl version 8.5 (required).
-
Follow the rest of the instructions to complete the installation.
- Follow the installation prompts to complete the installation.
- After installation, set the following variables (
Note: The following examples match the sample installation. You must alter these parameters to match your installation.
- Alternatively, specify the following environment variable to specify the location the log, sample, and results files for IxOS:
- 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:
export IXIA_HOME=/opt/ixia/tcl/8.5.17.0 IXIA_VERSION=6.91.XXX.XXX
export TCLLIBPATH=$IXIA_HOME/lib
IXIA_LOGS_DIR=/tmp/Ixia/Logs
IXIA_RESULTS_DIR=/tmp/Ixia/Results
IXIA_SAMPLES=/tmp/Ixia//samples
IXIA_TCL_DIR=$IxiaLibPath
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:
- Source the environment file for tarball.
- ixConnectToTclServer <chassis-name>
- 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