Spirent HOWTO/README
--------------------

How to create traffic on sprient in discrete steps.
---------------------------------------------------

Two files are needed for traffic generation: a config file and a state file. The config
file contains information about what the traffic will look like. The state file is the 
state of the spirent session across interactions with teh device. You can look at the state
file (it's JSON), but it should not be edited directly. 

HOWTO make traffic happen.
1) Load the python environment for the spirent scripts:
    > /proj/edgect/share/spirent/venv/bin/activate

2) Generate a default configuration:
    > ./spirent_generate_config.py -s 10.4.1.15 -d 10.7.1.25 > spi.config

3) Create an active sprient session with a new state file:
    > ./spirent_session.py -s spi.state -c spi.config create

    This will create a session on the spirent device and create
    the "spi.state" file which tracks the session.

4) Start traffic based on your configuration file:
    > ./spirent_session.py -s spi.state -c spi.config traffic_start

5) do stuff that wants active traffic.

6) Stop traffic:
    > ./spirent_session.py -s spi.state -c spi.config traffic_stop

7) Destroy the Spirent session and clean things up:
    > ./spirent_session.py -s spi.state -c spi.config destroy

Notes:
spirent_session.py can take multiple commands and will run them in the order given. So 
giving it "create traffic_start" will combine steps 3 and 4 into 1. The same for 
"traffic_stop destroy". 

Traffic can be started and stopped as neeeded while the session 
remains active. While the session is active, others will not be able to reserve the ports
your session has attached to.

Usage strings:
--------------
usage: spirent_generate_config.py [-h] -s SRCADDR -d DSTADDR
                                  [-t TRAFFIC_DURATION] [-p PROTOCOL]

Create a configuration for use in other Edgelab Spirent scripts. Writes to
stdout.

optional arguments:
  -h, --help            show this help message and exit
  -s SRCADDR, --srcaddr SRCADDR
                        Source address for traffic.
  -d DSTADDR, --dstaddr DSTADDR
                        Destination address for traffic.
  -t TRAFFIC_DURATION, --traffic_duration TRAFFIC_DURATION
                        How long in seconds to generate traffic.
  -p PROTOCOL, --protocol PROTOCOL
                        IP protocol to use for traffic. Default is UDP (17).

--------------
usage: spirent_session.py [-h] [-l {all,debug,info,error,critical}]
                          [--debugREST] -s STATEFILE -c CONFIGFILE
                          {create,traffic_start,traffic_stop,destroy}
                          [{create,traffic_start,traffic_stop,destroy} ...]

Connect to Spirent device and start a new session and reserve ports or connect
to an existing session. Read or write session information to the statefile
given.

positional arguments:
  {create,traffic_start,traffic_stop,destroy}
                        The command(s) to run using the given session/state.
                        May be given multiple times. Arguments will be
                        processed in order.

optional arguments:
  -h, --help            show this help message and exit
  -l {all,debug,info,error,critical}, --loglevel {all,debug,info,error,critical}
  --debugREST           If given, dump a lot of information about the HTTP/URL
                        calls being made by the REST API.
  -s STATEFILE, --statefile STATEFILE
                        The spirent state file. If it does not exist, it will
                        be created. The same state file should be passed to
                        all invocations of this script for a given spirent
                        session.
  -c CONFIGFILE, --configfile CONFIGFILE
                        The configuration to use in this session. Defaults
                        will be used to fill in any gaps in the configuration.
--------------


Other Scripts:
--------------
spirent_clear_sessions.py will clear and cleanup all existing sessions on the
edgect allocated slot on teh Spirent device. It takes no arguments.

spirent_system_info.py will dump useful and not-useful information about the 
Spirent device, including any active sessions.


OLDER BELOW. Still valid, but not used.

gen_traffic.py
==============
A standalone traffic generation script is gen_traffic.py. Here's the usage string:

usage: gen_traffic.py [-h] [-l {all,debug,info,error,critical}] [--debugREST]
                      [-c CONFIG] [--generate_config] [-t HOWLONG]

Start traffic between two enclaves.

optional arguments:
  -h, --help            show this help message and exit
  -l {all,debug,info,error,critical}, --loglevel {all,debug,info,error,critical}
  --debugREST           If given, dump a lot of information about the HTTP/URL
                        calls being made by the REST API.
  -c CONFIG, --config CONFIG
                        Customize the traffic via a config file.
  --generate_config     Generate a sample config file to stdout and exit.
  -t HOWLONG, --time-in-seconds HOWLONG
                        How long to generate traffic for in seconds.

The standard work flow for using gen_traffic is to create a default configuration file
via the --generate_config argument, optionally edit that file, then run gen_traffic.py
with the new configuration. 

The scripts must be run in a virtual environment to function. To enter the environment, 
source the appropriate script in /proj/edgect/share/spirent/venv/bin/activate:

. /proj/edgect/share/spirent/venv/bin/activate

Generate a default configuration file, edit it, and run traffic. 

/proj/edgect/share/spirent/gen_traffic.py --generate_config > ~/spirent.conf
vim ~/spirent.conf
/proj/edgect/share/spirent/gen_traffic.py -c ~/spirent.conf

By default, the script will generate UDP traffic for 10 seconds between pc8 and pc9. 
To modify which enclaves traffic is generated between, edit the configuarion 
ipv4->{sourceAddr, destAddr, gateway}. The items in the configuration file are 
documented in the Spirent Test Center Programmers Guide. The configuration given to the
script is passed directly to the Spirent REST API of the Spirent device pointed to 
in the "stc_session" stanza in the configuration. 

run_traffic.sh
==============
There is another barebones script which uses curl to speak directly to the REST API of
the Sprient device to send traffic. It's called run_traffic.sh. It was written to 
test/debug the Sprient device, but could be used to run traffic as well. There is a minimal
user interface to this script:

-----------------
run_traffic.sh -s source_addr -d dest_addr -p IP_protocol -l frame_len -r frames_per_second -t time_to_run

source_addr can also be set via $TRAF_SRCADDR in the environment.
dest_addr can also be set via $TRAF_DSTADDR in the environment.
IP_protocol can also be set via $TRAF_IPPROTO in the environment.
frame_len can also be set via $TRAF_FRAMELEN in the environment.
frames_per_second can also be set via $TRAF_FRAMEPERSEC in the environment.
time_to_run can also be set via $TRAF_TIME in the environment.

The addresses will control which enclave the traffic comes from and goes to
and should be 10.X.1.N for X=enclave and 2 <= N <= 255.
The gateway for each enclave is assumed to be 10.X.1.1.

Defaults are
        source_addr: 10.8.1.25
        dest_addr: 10.9.1.25
        IP protocol: 17
        Frame Length 128
        Frames/sec: 10
        Traffic time: 5
-----------------

This script can be copied and edited in place for "advanced" traffic generation. See Spirent docs for 
REST API details. 

Troubleshooting
===============
The system_info.py script may give useful error messages when run. If it runs to completion,
it will dump information about the Spirent device to stdout. 

Make sure the Sprient Test Center REST API script is running on the Test Center. (Ask Geoff about
this or login to the remote desktop and click the REST API icon "stcweb Shortcut" on the desktop.)

See Geoff or Paul.