Candela Technologies Logo
Network Testing and Emulation Solutions

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 of python modules which control LANforge. These allow the user to automate tasks. This cookbook will introduce inital to scripts to start LANforge automation, the libraries that need to be import to run Candela's python scripts, and how to create objects in python.
Before starting any scripting in LANforge, please clone the git repository locally. In the Candela device should come with a lanforge-scripts directory. However, if it doesn't, please paste git clone https://github.com/greearb/lanforge-scripts into your terminal in the directory to which the folder should be in.
 
  1. Importing libraries:

    Please visit the readme.md page in lanforge-scripts/py-scripts to make sure all the libraries that are needed are imported.
  2. Install necessary dependencies
    1. In the lanforge-scripts library there is a subfolder called py-scripts. Inside this folder is a program called update_deps.py. This program runs in both Linux and Windows and can be run with the following command python3 update_deps.py. This program installs the python dependencies which are used in this library on your system.
  3. How to run a script
    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.
  4. Station Creation screenshot
    1. The create_station.py script creates wi-fi stations from your terminal.
    2. 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.
    3. 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.
    4. You can specify the following flags as well:
      1. num_stations - Specify a different number of stations to create off of your antenna. The default is 2.
      2. debug - call this flag if you want detailed diagnostic information
  5. Find available networks
    1. You can find available WiFi networks on any Linux device by typing sudo iw dev wlan0 scan | grep SSID into your command line
    2. You can also find available WiFi networks by clicking on the station you created in the previous step,
  6. 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.
    1. Connect via Command line
      1. 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.
    2. Connect via GUI
      1. 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.
  7. Bridge Creation screenshot
    1. To create a bridge, you can use the create_bridge.py script in the py_scripts folder.
    2. Type
      ./create_bridge.py --target_device wlan0 --radio wiphy1
      Into your terminal, remembering to change the ssid, passwd, and security fields to match your network credentials.
    3. create_bridge requires the following arguments:
      1. target_device - which device the bridge is going to connect
      2. radio - default is wiphy0
    4. 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.
  8. VAP Creation screenshot
    1. You can create a VAP from your terminal with the create_vap.py script.
    2. 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.
    3. create_vap supports the following flags:
      1. num_vaps - A user defined number of VAPs to create off of your antenna
      2. upstream_port - if your ethernet cable to your router is not eth1, define it using this flag. Eth1 is the default for this flag.
      3. debug - call this flag if you want detailed diagnostic information
  9. MAC-VLAN Creation
    1. 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
  10. Monitor Creation: Under Construction
  11. Layer-3 Cross Connect
    1. In your py-scripts, there is a create_l3 script which allows you to create stations in your terminal.
    2. 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.
    3. 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.
    4. You can specify the following flags as well:
      1. num_stations - Specify a different number of stations to create off of your antenna.
      2. upstream_port - if your ethernet cable to your router is not eth1, define it using this flag. Eth1 is the default for this flag.
      3. debug - call this flag if you want to get error messages in case anything goes wrong.
    5. Your port manager will look similar to this screenshot
    6. Your Layer 3 connections will look similar to this screenshot
  12. Layer-4 Cross Connect
    1. In your py-scripts, there is a create_l4 script which allows you to create stations in your terminal.
    2. Type
      ./create_l4.py --radio wiphy0 --ssid lanforge --passwd password --security wpa2
      into your terminal
    3. 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.
    4. You can specify the following flags as well:
      1. num_stations - Specify a different number of stations to create off of your antenna.
      2. upstream_port - if your Ethernet cable to your router is not eth1, define it using this flag. Eth1 is the default for this flag.
      3. debug - call this flag if you want detailed diagnostic information
    5. Your port manager will look similar to this screenshot
    6. Your Layer 4 connections will look similar to this screenshot
    7. Your Netsmith display will look similar to this. The connections on this picture have been oriented for legibility.
  13. 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.
    1. 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.
    2. 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.
    3. test_ipv4_variable_time accepts the following flags:
      1. output_format - The format you want to save your results to
      2. col_names - Which columns should be saved in the output file
      3. test_duration - how long you want the test to last.
      4. report_file - where you want the results to be stored
    4. Your port manager will look similar to this screenshot
    5. Your Layer 3 connections will look similar to this screenshot
    6. Your Layer 3 endpoints will look similar to this screenshot
    7. You can view a dynamic report of the connectiosn creating traffic. It will look similar to this screenshot
Candela  Technologies, 2417 Main Street, Suite 201, Ferndale, WA 98248, USA
www.candelatech.com | sales@candelatech.com | +1.360.380.1618
Facebook | LinkedIn | Blog