Getting Started with Python scripting for LANforge

Goal: After reading this, a user will know what python modules which are available to use LANforge.

There are many python modules which control LANforge. These modules allow the user to automate many tasks. This cookbook will introduce the initial steps to start LANforge automation, the libraries that need to be imported to run Candela's python scripts, and how to create objects in python.

There are two options to run lanforge_scripts. If you are a programmer, you can clone the git repository locally by using git clone https://github.com/greearb/lanforge-scripts in your command line into the directory which the folder should be in.

Candela supports Fedora 27+ and Python 3.7+. Older python versions are not supported.

The advantage to cloning lanforge_scripts from git is that it is the latest code available, while the pip repository will lag slightly behind the git repo. The advantage to using pip is that there might be occasional errors in the git repository, which will be ironed out by the time we push it to the pip repository. The pip repository is always close to the master branch of the git repo, lagging no more than a couple weeks. Pick the one which best suits your needs.

Please run Python as the LANforge user on your system.

If you run python as root, you might break your LANforge system. The LANforge Linux OS requires some certain python packages and versions to operate and configure networking correctly. Candelatech does not recommend updating python packages as root. Your package manager will automatically update these dependencies when you run updates as well, which can overwrite your changes.

The safe way to run python scripts is as a non-root user. If you have python dependencies installed locally by using pip --user, if a dependency breaks you can fix it without potentially harming files your operating system needs to operate. Broken python dependencies on your system Python can break your operating system. When your system updates, it might overwrite the changes you have made.

Users are responsible for making certain the version of Python running on their system is supported by the Python Foundation. An up to date list can be found at Python Foundation support. Candela Technologies does not support versions of Python which have been deprecated by the Python Foundation. Customers with a support contract can contact support@candelatech.com to get support upgrading their LANforge systems.

Importing libraries:

Please visit the readme.md page in lanforge-scripts/py-scripts to make sure all the libraries that are needed are imported.
Install necessary dependencies
1. In the root of lanforge_scripts, run pip3 install --user -r requirements.txt --upgrade
How to run a script from a git clone
1. We start in the /home/lanforge/lanforge-scripts/py-scripts directory on your lanforge system
2. On a Linux system, open your terminal and navigate to the py-scripts folder. You can run any python script by typing
  python3 your_script_here.py --your_flag
  into your command line. After the script, put any flags you need in order to run your test.
How to run a script from pypi
1. In your terminal, run python3
2. In your python environment, run import lanforge_scripts


  Station Creation
  
  
    The create_station.py script creates wi-fi stations from your terminal.
    
    
    Type 
./create_station.py --radio wiphy0 --ssid lanforge --passwd password --security wpa2
into your terminal. Please reemember to change the SSID, Passwd, and Security fields to match your network credentials.
    
    
    This will create 2 stations on your lanforge device off of your wiphy0 radio. You might need to wait 30 seconds for them to stop being phantom ports.
    
    
    You can specify the following flags as well:

    
    
      num_stations - Specify a different number of stations to create off of your antenna. The default is 2.
      
      
      debug - call this flag if you want detailed diagnostic information
      
      
    
    
  
  
  Find available networks
  
  
    You can find available WiFi networks on any Linux device by typing sudo iw dev wlan0 scan | grep SSID into your command line
    
    
    You can also find available WiFi networks by clicking on the station you created in the previous step, 
    
    
  
  
  Associate to a specific BSSID: 

If you want to connect to a specific MAC Address for your router (which is called the BSSID) you can specify that on each station, you can do that in both the GUI and in the command line.
  
  
    Connect via Command line
    
    
      Each of your scripts has an optional AP tag where you can define the MAC address of the router you want to connect to. To do so, simply append --ap to the end of the command line argument you are running followed by the router's MAC Address.
      
      
    
    
    Connect via GUI
    
    
      When you double click on a Station there is an AP field inside WiFi Settings. Type the MAC Address of your router in that box and everything will work assuming the MAC Address is correct.
      
      
    
    
  
  
  Bridge Creation
  
  
    To create a bridge, you can use the create_bridge.py script in the py_scripts folder.
    
    
    Type 
./create_bridge.py --lf_mgr localhost --bridge_name br0 --target_device eth1 --no_cleanup
Into your terminal, remembering to change the ssid, passwd, and security fields to match your network credentials.
    
    
    create_bridge requires the following arguments:
    
    
      bridge_name - Name of the bridge to create
      
      
      target_device - which device the bridge is going to connect
      
      
    
    
    It is not valid to add stations to a bridge, they don't work like you would expect. Bridges can have: eth ports, redirects (rdd) ports, vaps, and qvlan ports. Ports in a bridge cannot have IP addresses.
    
    
  
  
  VAP Creation
  
  
    You can create a VAP from your terminal with the create_vap.py script.
    
    
    Type
./create_vap.py --radio wiphy0 --security wpa2 --ssid lanforge --passwd password
into your terminal, remembering to change the ssid, passwd, and security fields to match your network credentials.
    
    
    create_vap supports the following flags:
    
    
      num_vaps - A user defined number of VAPs to create off of your antenna
      
      
      upstream_port - if your ethernet cable to your router is not eth1, define it using this flag. Eth1 is the default for this flag.
      
      
      debug - call this flag if you want detailed diagnostic information
      
      
    
    
  
  
  MAC-VLAN Creation
  
  
    In the py-scripts folder, there is a script named create_macvlan.py, which creates a mac-vlan based on the macvlan_parent , num_ports , first_macvlan_ip, netmask, and gateway input
    
    
  
  
  Monitor Creation: Under Construction
  
  
  Layer-3 Cross Connect
  
  
    In your py-scripts, there is a create_l3 script which allows you to create stations in your terminal.
    
    
    Type
./create_l3.py --radio wiphy0 --num_stations 0
into your terminal, remembering to change the ssid, passwd, and security fields to match your network credentials.
    
    
    This will create a layer3 cross connect between each station you already built on your lanforge device and your wiphy0 radio. You might need to wait 30 seconds for them to stop being phantom ports. If you do not specify num_stations 0 it would have created two stations by default off your specified radio. You can change which port the cross connect will be connected to with the --upstream_port option.
    
    
    You can specify the following flags as well:
    
    
      num_stations - Specify a different number of stations to create off of your antenna.
      
      
      upstream_port - if your ethernet cable to your router is not eth1, define it using this flag. Eth1 is the default for this flag.
      
      
      debug - call this flag if you want to get error messages in case anything goes wrong.
      
      
    
    
    Your port manager will look similar to this
    
    
    Your Layer 3 connections will look similar to this
    
    
  
  
  Layer-4 Cross Connect
  
  
    In your py-scripts, there is a create_l4 script which allows you to create stations in your terminal.
    
    
    Type
./create_l4.py --radio wiphy0 --ssid lanforge --passwd password --security wpa2
into your terminal
    
    
    This will automatically create 2 stations on your Lanforge device off of your wiphy0 radio and also create a cross connect from each station to your eht1 port. You can change which port the cross connect will be connected to with the --upstream_port option.
    
    
    You can specify the following flags as well:
    
    
      num_stations - Specify a different number of stations to create off of your antenna.
      
      
      upstream_port - if your Ethernet cable to your router is not eth1, define it using this flag. Eth1 is the default for this flag.
      
      
      debug - call this flag if you want detailed diagnostic information
      
      
    
    
    Your port manager will look similar to this
    
    
    Your Layer 4 connections will look similar to this
    
    
    Your Netsmith display will look similar to this. The connections on this picture have been oriented for legibility.
    
    
  
  
  Monitor and record an IPV4 variable time test. The purpose of this test is to detect whether your router is able to keep a steady signal when being barraged by multiple users.
  
  
    In the first part of this tutorial, you are going to connect various numbers of stations, record them for 1 and 10 minutes, and then save as a CSV, excel, or pickle format. A station represents a device which is connected to a network, LANforge creates representations of stations which create real traffic on your network and then records statistics on that traffic. This module determines whether your device is able to sustain a heavy load of traffic for an user defined period of time. By recording the traffic it is then possible to go back and detect where any problems occurred which allows a network manager to fix problems which could be facing your network.
    
    
    Navigate to the py-scripts folder and type the following command into your command line 
./test_ipv4_variable_time.py --radio wiphy0 --security wpa2 --ssid lanforge --password password --output_format csv
Replace the security, ssid, and password variables with the settings for the network you are testing.This will create 2 wiphy stations by default, connect them to the network you are testing, and report the results to a CSV file.You will find a file with a timestamp within the last 5 minutes in the report_data folder in your home directory. If you are running this script from another machine using the --mgr function, you will need to define the report_file variable.
    
    
    test_ipv4_variable_time accepts the following flags:
    
    
      output_format - The format you want to save your results to
      
      
      col_names - Which columns should be saved in the output file
      
      
      test_duration - how long you want the test to last.
      
      
      report_file - where you want the results to be stored
      
      
    
    
    Your port manager will look similar to this
    
    
    Your Layer 3 connections will look similar to this
    
    
    Your Layer 3 endpoints will look similar to this
    
    
    You can view a dynamic report of the connectiosn creating traffic. It will look similar to this

		sales@candelatech.com support@candelatech.com +1 (360) 380-1618 [PST, GMT -8]
	Network Testing and Emulation Solutions