Candela Technologies Logo
Network Testing and Emulation Solutions

Various Techniques Cookbooks

The Various Techniques Cookbooks provide miscellaneous examples of how to perform various network configuration tasks. Each is a set of step-by-step instructions intended to help build your familiarity with network configuration in Linux and Windows.

Please contact us at if you have any questions.

All Network Configuration Cookbook Examples

  1. Server Install Script
  2. Configure Auxiliary Management
  3. Find Windows IP Addresses
  4. Find Windows MAC Addresses
  5. Custom DOS Window Settings
  6. Quickly Inspect Your DOS PATH Variable
  7. Connecting With PuTTY
  8. Install Arduino Mega Driver on Windows XP
  9. Install Arduino Mega Driver on Windows 7
  10. Install Arduino Mega Driver on Windows 10
  11. Connect to LANforge Using Remote Desktop
  12. Connect to LANforge Using VNC Viewer
  13. Display WireShark Using Cygwin
  14. Finding Report Data
  15. Writing Disk Images on Windows
  16. Adding a LANforge Virtual Machine
  17. Configuring Serial Connection to LANforge
  18. Connecting SMA Cables to LANforge
  19. Diagnose GUI Problems on Windows
  20. Recovering Filesystems
  21. Automatically Start LANforge GUI on Login
  22. Configure OpenVPN on Ubuntu
  23. Configure OpenVPN on Windows
  24. CI/CD Lights-Out Chamber Setup
  25. Instructions to Change Report Logo
  26. Instructions to Set Up an SSH Tunnel
  27. Understanding VRF Devices
  28. Use FireFox with a Virtual Station to Browse a DUT
  29. Backing Up and Migrating LANforge Data
  30. CT714B Stand Assembly
  31. CT840a Turntable Testing
  32. Remove old Reports and Data
  33. Clustering Multiple LANforge Systems
  34. Configure a Remote LANforge System
  35. Configure NTP Chronyd on Fedora
  36. Upgrading Offline LANforge Systems
  37. Multiplexed REST Access via Nginx Proxy
  38. LANforge Troubleshooting

Install Script

Goal: Install and reconfigure your LANforge server with the script.

The script can configure a majority of Linux OS features that LANforge requires changes to. This includes:
  • Disabling SELinux
  • Disableing firewall
  • Downloading dnf and LANforce updates
  • Adding VNC and RDP access
  • Adding firmware
  • Disabling or reconfiguring NetworkManager
  • Enabling serial console
  • Modifying kernel options for iommu, pci-aer and kernel memory
  • ...and more...

Usage --lfver {lanforge version} --kver {kernel version} {command}
Note: the parameters --do_kern and --do_grub requires the --kver option to specify the kernel version. Candelatech Linux kernels end with "+" to denote extra patches. Use --debug|--verbose|-d to enable debugging.
 Example: ./ --kver 3.5.7+ --lfver 5.2.7 --do_lanforge


Specify LANforge version (i.e., 5.2.6)
Specify kernel version, use a + at the end of kernel versions for Candelatech kernels
Do not install a kernel package, suppresses do_grub, do_kern
Specify the hardware string: CT521, CT52x-PR, CT521, CT520, LF0202, CT523, CT523c, CT314, LF0312, LF0313, CT522 Can help with html info page configuration. Leave blank if unsure.
Specify serial com speed (defaults to 115200)
Specify the serial com port (defaults to ttyS0)
Specify location of installation files (must be absolute path).
Specify the script temporary working directory and backups of system files.
Download files to tmp-dir, but do not install them or make other changes.
Ignore any (otherwise fatal) errors. May be useful for offline installs where some functionality is better than none.
Use a proxy for curl, e.g. http://%user:%password@%proxy-ip:%port
Enables all options except: --xrandr, --runlevel
Enables all options except: --xrandr, --biosdevname, --runlevel, and --serial Skips the CPU burn-in test.
Upgrades LANforge software, kernel, firmware, packages and OS packages. No system settings altered. Skips cpu-burn.
alias for do_upgrade
Download and install LANforge software and kernel only. Enables 'do_lanforge do_kern do_grub do_http do_selinux=0 do_iommu=0 do_firmware' No yum update. No system settings altered, except for selinux and iommu.
Download and install LANforge software but only update grub to point to an already installed kernel. Enables 'do_lanforge do_grub do_http do_selinux=0 do_iommu=0 do_firmware' No system settings altered, except for selinux and iommu.
Installs LANforge software ONLY, i.e. no kernel installed. No system settings altered.
Download and install ath10k 802.11AC NIC firmware.
Install the kernel via download or --source_dir. Enables 'do_grub' option.
Install and configure radius server (with default values).
Do not attempt to reconfigure radius. Useful when attempting to speed up do_sys_reconfig on slow systems.
Re-generate the HotSpot 2.0 R2 (HS20-R2) and/or RADIUS certs, even if we have previously created them.
Build keys, configure apache ssl and other actions to enable this system to act as an HS20-R2 server. Requires specific LANforge configuration as well before this will actually work. This option must be explicitly enabled: It is not enable as part of any of the other option groupings.
IP Address to advertise as HS20 servers. This could be IP address of management port in simple configurations, and for more realistic configurations, perhaps the IP address of something in same network as the HS20 OSEN and .1x APs.
Clone and build scrcpy tool (should not be needed for latest 5.4.6 builds)
Enable/Disable services to work well with LANforge.
Enable NetworkManager. It is disabled by default.
Install packages from Internet needed by LANforge.
Show top 20 largest packages. Useful during do_image_prep if you want to reduce install footprint.
Only install packages (and groups) and exit. Use when creating VMs or if you want to install all distro packages and reboot before proceeding. If you want to download everything needed, install yum packages for development imaging:
  1) touch /home/lanforge/did_cpuburn /home/lanforge/did_disktest
  2) ./ --lfver ___ --kver ___ --do_selinux=0 --skip_yum_all
  3) ./ --lfver ___ --kver ___ --skip_yum_all --do_all_ct --force_web \
--tmp_dir /home/lanforge/Downloads --download_from http://ctdownloads/ --download_only
  4) reboot
  5) ./ --lfver ___ --kver ___ --do_only_pkgs
  6) poweroff and make your snapshot
Update OS packages from Internet.
do not erase and rebuild yum cache
Configure selinux (it conflicts with LANforge.) do_grub should also be enabled to modify the kernel boot commands.
  0: Disabled (default, if do_all and related options are selected)
  1: Enabled
  -1: Use current settings
Modify the grub config files to boot the specified kernel.
Add work-around to disable LVDS1 using xrandr. This works around Gnome issues on the Lanner WiFi appliances, and perhaps other systems.
Configure VNC for user lanforge.
Serve LANforge related files at http://localhost
Tweak gnome settings (enble desktop icons, etc)
Create /etc/udev/rules.d/70-persistent-net.rules file if it does not already exist. It may still need hand-editing.
Enable biosdevname for interface names (uses terms like enp0s1 instead of eth0). Only takes affect when --do_grub is enabled.
  0: Disabled
  1: Enabled
  -1: Use current settings (default)
Enable serial console configuration in grub.
  0: Disabled
  1: Enabled
  -1: Use current settings (default) Only takes affect when do_grub is enabled.
Configure system to run-level 3 or 5
  0: Use current settings (do nothing)
  3: Set to use runlevel 3 (non graphical login)
  5: Set to use runlevel 5 (graphical login, needed for cinnamon)
Add kernel option elevator=noop (i.e. not deadline) for single SSD CFQ optimisation.
  0: Disabled
  1: Enabled
  -1: Use current settings (default) Only takes affect when do_grub is enabled.
Configure cma buffer for extra VRF buffer space. Use with --do_grub, applies on reboot. Use these choices:
  -1: do not change
  0: disable
  1: apply 64 megabyte value
  >1: apply this value in megabytes
 Example: --do_grub --do_cma 48
Configure system to enable/disable intel_iommu. This kernel feature decreases performance, so LANforge typically wants this disabled for optimal Ethernet performance. This can also be disabled in the BIOS by disabling the VT-d option and IOMMU options.
  0: Disabled (default for do_all_ct, do_all, do_ct_swak, do_ct_st)
  1: Enabled
  -1: Use current settings (default) Only takes affect when do_grub is enabled. IOMMU is useful in these conditions: * virtual machine hosting * MediaTek radios * Ath10k radios
Configure system to enable/disable spectre and related mitigations. We try to compile out most of these security features since LANforge is not designed to be secure and performance is more important to us. To help make sure all of these mitigations are disabled, we will also pass command-line args to the kernel on bootup to request disabling mitigations. Default is '1'.
  0: Do not add the mitigations=off option
  1: Do add the mitigations=off (default)
  -1: Use current settings Only takes affect when do_grub is enabled.
Configure IOMMU buffer size. Requires you use IOMMU setting, so use with --do_grub --do_iommu=1
 Example: --do_grub --do_iommu=1 --set_swiotlb=65536
Configure system to enable/disable pci error reporting. Requires --do_grub.
  0: Disabled (removes grub bootline parameter)
  1: Enabled (adds pci=noaer bootline parameter, DEFAULT)
  -1: Use current settings
Configure kernel option for kmemleak. Requires kernel to be compiled with appropriate options to actually enable this.
  0: Disabled
  1: Enabled
  -1: Use current settings (default) Only takes affect when do_grub is enabled.
Modify rw behaviour for SSDs in /etc/fstab.
  1: Yum update then save cache.
  20: Delete local cache first then update and save.
Attempt to re-configure system config files. Only works on certain platforms (APU2, Jetway, Noah2, Axiomtek)
forces --do_sys_reconfig to run, looking for enpX interfaces and no radios
avoids renaming interfaces and rewriting 70-persistent-net
updates Firefox Homepage
Set LANforge management interface, defaults to eth0 on most platforms. Does not presently use --mgt_dev option.
Creates /etc/sysconfig/network-scripts/ifcfg-eth0 from the eth0 entry found in /etc/udev/rules.d/70-persistent-net.rules. Fedora only. Edit 70-persistent first.
Delete previous install files.
Attemps the CPU burn task. NOTE: The --skip_cpu_burn flag below has precedence.
  0: Do not attempt it.
  1: Do it if we have not already run it on this system previously.
  2: Always run it.
  >10: Run CPU burn test for specified seconds.
should we fill and re-read disk to make sure it performs well?
  0: Do not attempt it
  1: Do it if /home/lanforge/did_disktest not found unless --skip_disk_test specified
  >1: Always run it, ignoring --skip_disk_test
avoid do_disk_test if /home/lanforge/did_disktest is missing
should we adjust the xrdp.ini and sesman.ini files:
  0: ignore files
  1: adjust files
Add fake URL argument to disable any HTTP caching.
Uninstall yum-fastest mirror.
Show usage help.
Show URLS for all files that should be downloaded, and exit.
show_urls without website check
print out .bat file contents to help with downloading LANforge updates
Force script to use webserver. Do not use with --source_dir.
Specify web url to download LANforge packages from, implies --force_web
This path is appended directly after the --download_from hostname. The default download path will not be used. The string r$lfver will not be inserted. Build paths will not adhere to a directory pattern, use the full path.
create a tarball in tmp_dir for copying to another LANforge system, will infer --osver, --osveri for current system unless you specify --force_osver, --force_osveri
/path/to/bundle.tar : Upgrade LANforge using an install bundle file. Sets $source_dir, $tmp_dir to directory containing bundle.tar file.
Force creating lfnotes.html
Override the detected osver string with this value.
Override the detected osversion integer with this value.
Don't do kernel install, even if other options would have selected it.
Don't install LANforge-GUI, even if other options would have selected it.
Don't install Xorp virtual-router package, even if other options would have selected it.
Don't alter systems existing use of yum-plugin-fastestmirror.
Don't burn-in CPU.
Don't yum update packages.
Don't yum update packages, or install new ones.
Don't try to use HTTP resume when downloading packages.
Enable do_http and reset the httpd.conf DocumentRoot and Directory from /home/lanforge/candela_cdrom to /var/www/html
Erase the network settings and dnf cache in preparation for making a disk image for a clone. Expects /root/
Erase the network settings and dnf cache in preparation for making a OVA image. Expects /root/
Select this option to use the fedrepos default command if your yum.repos.d repository URLs have become misconfigured. If fedrepos is not available, consider --do_restore_metalinks option.
Select this option if you see errors like below:
  1) Repository updates-debuginfo has no mirror or baseurl set.
  2) Repository updates-source has no mirror or baseurl set.
  3) Repository fedora-debuginfo has no mirror or baseurl set.
  4) Repository fedora-source has no mirror or baseurl set.
  5) Error: Failed to synchronize cache for repo 'updates'
  6) Your /etc/yum.repos.d repo files have had changes and are unable to reach
Select this option if your URLs are unable to provide your repository because the content has been moved to This option is pretty much opposite of --do_restore_metalinks.
creates a series of files in /var/www/html accessable using the url /slug_list.html
configures an /etc/hosts entry lanforge-srv that matches the ip address of the mgt_dev in /home/lanforge/config.values. Updates the /etc/httpd or /etc/apache2 files to bind to that address. Use this option each time you change the mgt_dev.
VLC video player requires RPMFusion repository. This adds the repository and then installs VLC.
shortcut for downloading Candelatech videos into /var/www/html/videos so that they might be served for video testing. See /usr/local/lanforge/nginx/ for stanza when enabling directory listings when using nginx.
shortcut to install packages necessary for using RF generator hardware
create cronjob that espunges systemd slices from logged out session every hour
removes the passwords from accounts root and lanforge and reconfigures sshd to accept empty passwords. Yes...really, it IS crazy, right?
Use the following two options to print a label with model and mac address information
  1) print_host: hostname owning printer
  2) print_queue: name of print queue, often 'QL-800' or 'LaserWriter-450'
  3) serialno: provide the serial number for chassis, or use 'HOSTNAME'
 Example: --do_print_label --print_host --print_queue QL-800 --serialno HOSTNAME
turn off checking md5sum of ./
regenerate the /etc/pki/tls/$hostname.crt and .key files so that they have F33+ 4096 bit keys, not smaller keys.
Upgrades pip userland
Avoid doing pip upgrades; might be necessary if you have proxies
Use when pip3 updates were installed as root and you have system pip3 package conflicts. This will reinstall the python-pip3 package and 'pip3 remove -r requirements.txt' to remove pip3 libraries from system folder. Follow this with --update_pip to get pip3 libraries into user lanforge folder.
this will uninstall the python pip user environments and build a new one from scripts/requirements.txt; if you see errors, you probably are missing newly required library packages provided by the distro. To make sure your packages are up to date, use:
 Example: ./ --do_pkgs
this does a pip3 install of lanforge-scripts. This is not necessary if you just need to use /home/lanforge/scripts/py-scripts casually.
Affects kernel audit messages. Use with --do_grub and reboot to have this setting take effect.
  0: enable kernel audit logs (auditd.service not enabled)
  1: disable kernel audit logs
write /etc/sysctl.d/70-lanforge.conf and apply agressive zram configuration (Fedora >= 30) To undo, remove file and reboot.
Start GUI in VNC server session which starts on boot. Requires LANforgeGUI of specified version to already be installed.
  0: disable GUI autostart
  1: enable GUI autostart
Use this to restore GUI settings on reboot. Running this a second time copies a changed LANforgeGUI/lfcfg.txt file to $home to save new changes.
  1) backup: copies the LANforgeGUI/lfcfg.txt file to $home. Disables lfcustom_gui.bash if it exists.
  2) static: implies backup, creates lfcustom_gui.bash that replaces lfcfg.txt into LANforgeGUI directory every time LANforgeServer is started.
Removes pulseaudio-pipewire packages.
  0: do not remove pipewire (default)
  1: remove pipewire
installs LANforge server, GUI, firmware and required packages on system to sufficient to allow it to be a resource in a LANforge cluster. Right now, this focuses on Ubuntu based systems. This also will configure Networkmanager to ignore ports except the management interface. We cannot necessarily disable NM on interop equipment.
backs up /etc/NetworkManager/NetworkManager.conf and recreates one that specifies that no interfaces except the one with the default route be managed. Enabled by default during do_interop. NM settings you do not want modified should live in separate conf files in /etc/NetworkManager/conf.d. When this option is used without the --mgt_dev option, a new management device will be determined. Default value is 1.
  0: do not modify NetworkManager.conf
  1: update NetworkManager.conf and mgt_dev.nmconnection
  2: update NetworkManager.conf, mgt_dev.nmconnection, but do not restart NetworkManager
indicate what interface should be configured as the management interface. LANforge works best in cases where there is a dedicated management interface and management network (out of band management). In the case there is only one interface and it has to serve as a traffic port and a management port, that is possible (in band management). Currently this option is only used by the --regen_nm_conf option. If this option is not specified Specify one of these options:
  1) {interface_name}: name of the interface to set
  2) "existing": force the use of the mgt_dev in /home/lanforge/config.values
specify IP address to add to [ipv4]mgt_dev.dns value in mgt_dev.nmconnection
specify either "dhcp" or a "ip/cird/gateway" combination for mgt_dev.nmconnection:
  1) mgt_ip=dhcp
  2) mgt_ip=
change NetworkManager dns=systemd-resolved to dns=default and disable systemd-resolved.service
create_raid|make_raid|create_lvm|make_lvm : turn two or more blank drives into a mirrored LVM filesystem If there have been filesystems installed on these drives before, use --wipe_raid to remove the filesystems wipe_raid|remove_raid|remove_lvm : remove LVM volumes and signatures from specified disks. Use this before doing --create_raid the first time on any disk that already has a filesystem.
turn this help into html text for publication *_dd
Note: If you use commands "yum update" or "dnf update", and you need to use a kernel provided by the repository, use:
 Example: grub2-mkconfig -o /boot/grub2/grub.cfg

Configure Auxiliary Management Interfaces

Goal: Allow LANforge to create its own wireless management network.

In cases where is is not convenient to use an existing management network, LANforge WiFi systems can be configured to provide their own WiFi management network. This may be especially useful when testing in environments where LANforge needs to be moved around or where you have no good access to existing management LANs. This example assumes that you already know how to create and configure VAP and Stations in LANforge.
  1. Configure LANforge for Auxiliary Management.
    1. Connect LANforge systems through the normal management LAN for initial configuration. The resources should be visible in the management tab screenshot
    2. In this case, we are using wiphy0 for the Aux-Mgt interfaces. On the manager system, configure wiphy0 to be on the desired channel, create a virtual AP on wiphy0, and configure it appropriately. The Aux-Mgt checkbox should be selected, a static IP should be assigned, and an appropriate SSID configured. The AP Aux-Mgt port will automatically serve DHCP and will try to NAT and route packets to the wired Management interface. screenshot
    3. On the other resources, configure the wlanX interface to connect to the AP on the manager system, and select the Aux-Mgt checkbox. screenshot
    4. The Port-Mgr tab should look something like this when the Aux-Management interfaces are configured. screenshot
    5. To test that it works properly, you can now remove the wired Manament port connection and wait about 1 minute for the old connection to time out and re-connect to the Auxiliary Management port. Or, just reboot systems with the wired ports unplugged and they should be discovered on the Aux-Mgt ports promptly.

Windows IP Addresses

Goal: Find and change network ip addresses on Microsoft Windows.

Here are some techniques for finding and setting IP addresses on Microsoft Windows using the Control Panel and the command line.
  1. Find the IP Address of the Windows PC. There are two methods you can use:
    1. Using the Control Panel:
      1. Click Start, Run, control, [enter] screenshot
      2. Search and select Network Status and Devices screenshot
      3. We click on our device, Ethernet 3: screenshot
      4. Find and/or set the IP address: from Status, click Properites screenshot
      5. double click TCP/IPv4 screenshot
      6. you will see and can change the IP address.: screenshot
    2. Various DOS commands to find the IP addresses on the system:
      1. ipconfig and ipconfig /all
      2. netsh interface ipv4 show address
    3. Resetting your DHCP address via command line:
      1. ipconfig /release
      2. ipconfig /renew

Windows MAC Addresses

Goal: Find MAC Addresses in Microsoft Windows.

Here are some techniques for finding MAC addresses on Microsoft Windows using the Control Panel and the command line.
  1. Find the MAC Address of the Windows PC. There are two methods you can use:
    1. Method 1: use the Control Panel
      1. Click Start, Run, control, [enter] screenshot
      2. Search and select Network Status and Devices screenshot
      3. We click on our device, Ethernet 3: screenshot
      4. Click Details... screenshot
      5. Details will show the MAC address (physical address): screenshot
      6. (Suggested) Set the IP address if you have not already.

        For more information see Finding Windows IP Address

    2. Method 2: use the DOS command-line. You want to correlate the IP address and MAC address of the Windows ethernet port:
      1. Click Start, Run, and type cmd, and press [Enter] screenshot
      2. Show interfaces by name with the command: netsh interface ipv4 show addresses screenshot
      3. (Optional) if you do not see results, you might need to start the network autodiscovery service: net start dot3svc screenshot
      4. (Optional) Depending on the edition of Windows, the command netsh lan show interfaces will display mac addresses. screenshot
      5. Show mac addresses with: getmac /v /fo csv
        (The CSV formatted command of the command ensures that we will see the entire name of the interface which can be trimmed short in the default output format.)
      6. These commands will make it easier to copy using notepad:
        netsh interface ipv4 addresses > ifnotes.txt
        getmac /v /fo csv >>ifnotes.txt
        notepad ifnotes.txt
      7. Now you can easily copy the values: screenshot

Customizing DOS Window Settings

Goal: Make your DOS windows large and do cut and paste easier.

Here we review DOS window settings that will help you to work faster.
  1. Customizing DOS Window Settings starts by right clicking the Start Menu
  2. Type in cmd and hit Enter screenshot
  3. To get to your DOS window faster, you can pin it to your task bar. Right click the task bar CMD window icon and select Pin this program to taskbar screenshot
  4. On the DOS window title bar, Right click and select the Defaults menu item screenshot
  5. Select the Quick Edit Mode setting. This allows you to highlight text in the window easily. screenshot
  6. In the Font tab, select a slimmer TrueType font, like Consolas or Lucida Console, and set the font size to 10 screenshot
  7. In the Layout tab, change the Window Size to 132 columns and 56 rows screenshot
  8. Click OK to save. The next DOS window you open will appear with your customized settings.

Quickly Inspect Your DOS Path

Goal: Find if a program or is in your %PATH%

Use this technique to inspect your DOS environment variables for specific strings using findstr.
  1. Follow this example to see if perl is installed and your %PATH% environment variables is updated. First, open up a DOS window: Windows+RcmdEnter
  2. Type in the DOS Window: echo %PATH% | findstr /i perlEnter
  3. If perl is installed correctly, you should have it in your path. screenshot
  4. You can also use this technique to find any environment variable. E.G., find if you have a temporary directory set:
    set | findstr /i temp

Connecting with PuTTY

Goal: Using PuTTY on Windows to connect to LANforge Linux servers.

Lots of tasks, like scripting, can be done over SSH from your Windows desktop. Here are a few steps to help you customize your PuTTY terminal to work faster.
  1. Configuring a PuTTY Session
    1. When you double click on the PuTTY icon and it launches, you can start customizing your session preferences. We'll name this session jedtest screenshot
    2. Let's default the window to something large, like 120 columns and 56 rows. screenshot
    3. The Fixed font can be replaced with the Consolas font. screenshot
    4. Let's turn on TCP Keep-alive and set IPv4 as the default networking protocol. screenshot
    5. We login to LANforge resources with user lanforge screenshot
    6. Generating a SSH keypair is not difficult. Let's enter the path to our public key file. screenshot
    7. We have done our PuTTY config. Now back to the top Session screen, and click Save screenshot
  2. Configure Pagent with your public key
    1. Create your own public ssh key.

      For more information see WinScp Net

    2. Start Pagent. Configure it to load on startup.
    3. In the System Tray you will see the Pagent icon. screenshot
    4. Right-click the Pagent icon and click Add Key to select your key screenshot
    5. You will need to provide your pass-phrase to load your key screenshot
    6. We see a loaded key screenshot
    7. Here is our key, we will view the .pub file to copy out the public key. screenshot
    8. In a putty window you will log into your LANforge server and edit /home/lanforge/.ssh/authorized_keys
    9. Copy the text and place the "Comment" section at the end when you paste it into your ssh screenshot
    10. Here is the public key string, with newlines and spaces removed. The Comment text goes at the end. screenshot
    11. Check the permissions of the authorized_keys file. You might need to use the command
      chmod 600 authorized_keys
      to correct the permissions. screenshot
    12. The next time we load the jedtest PuTTY session we should not be prompted for our password.

Installing the Arduino Mega Driver on Windows XP

Goal: Installing the the Arduino Mega device driver on Windows XP.

The automatic driver install process for Windows XP might automatically install a Microsoft Windows version of the Arduino Mega driver. This is not the driver LANforge expects. These instructions will guide you how through uninstalling an old driver and installing the new driver.
  1. Follow the link to the Arduino project to download the latest driver :Download Arduino IDE

    For more information see Installing LANforge Server on Windows

  2. Download the Arduino IDE zip file to your desktop. Use Right-click→Extract All... to expand the contents to a folder on your desktop. screenshot
  3. Connect USB cable from the Attenuator to the PC
  4. Click Start→Control Panel and choose the Add Hardware option. screenshot
  5. In the hardware list page, select Add a new hardware device, and click Next

  6. Select the Install the hardware that I manually select option, and click Next screenshot
  7. Select the Ports (COM & LPT) option, and click Next screenshot
  8. Select (Standard port types) option, then Communications Port and then click Have Disk... screenshot
  9. Click Browse screenshot
  10. Navigate to your Desktop\arduino-1.8.9\drivers folder, and click Open screenshot
  11. Click Next screenshot
  12. Click Next screenshot
  13. Click Continue Anyway screenshot
  14. Click Finish screenshot
  15. You should not need to reboot your system in order to run the Attenuator
  16. For LANforge to recognize the new attenuator, restart the LANforge server on the machine that has the attenuator connected. On Windows, close the LANforge server CMD windows and then restart LANforge with using your desktop icon.

Installing the Arduino Mega Driver on Windows 7

Goal: Installing the the Arduino Mega device driver on Windows 7.

LANforge CT70x attenuators require recently signed Arduino drivers. The automatic driver install process for Windows 7 might automatically install a Microsoft Windows version of the Arduino Mega driver. This is not the driver LANforge expects. These instructions will guide you how through uninstalling an old driver and installing the new driver from the Arduino website.
If you have recently removed a driver, you might need to reboot your Windows system for it to complete the driver installation process.
  1. You want to install the windows version of the LANforge Server beforehand.

    For more information see Installing LANforge Server on Windows

  2. Follow the link to the Arduino project to download the latest driver :Download Arduino IDE screenshot
  3. Download the Arduino IDE zip file to your desktop. Use Right-click→Extract All... to expand the contents to a folder on your desktop. screenshot
  4. This process requires you to operate the Control Panel as Administrator. Some patch-levels of Windows 7 have secured this. A useful work around for this will be discussed shortly.
  5. Getting to the Device Manager
    1. In Control Panel, select Hardware and Sound screenshot
    2. Select Device Manager screenshot
    3. In the Device Manager window, right-click on the computer and select Scan for hardware changes screenshot
      1. There will be an Other devicesUnkown Device entry. Right-click on it. If the options menu only gives you either Scan for hardware changes or Properties, you might need to restart your control panel as Administrator, that is discussed next.
      2. Using the Run as Administrator option to start the Control Panel in administrator mode.

        1. This works best with a CMD window pinned to the task bar. You can do that using Start MenucmdENTER; and then right-clickPin to Task Bar option on the task bar icon for the cmd.exe window.
        2. Then right-clickRun as Administrator on the CMD taskbar icon screenshot
        3. Repeat your navigation steps to get to the Device Manager
  6. Uninstall Old Driver

    If you find a previously installed driver, uninstall it. Especially if this is labeled Windows Arduino Mega
    1. Right-clickUninstall screenshot
    2. Select Delete the driver software for this device, and click OK screenshot
    3. Right-click on the computer, and select Scan for Hardware Changes
    4. You might need to un-plug and plug-in your Attenuator.
    5. If the right-click options menu does not allow you to change drivers, reboot your system.
  7. Install new driver

    Select Browse my computer for driver software
    1. Browse to Desktop\arduino-1.8.9\drivers and click Next screenshot
    2. You will see the Update Driver Software confirmation. Click Close. screenshot
  8. You should not need to reboot your system in order to run the Attenuator.

Installing the Arduino Mega Driver on Windows 10

Goal: Installing the the Arduino Mega device driver on Windows 10.

LANforge CT70x attenuators require recently signed Arduino drivers. The automatic driver install process for Windows 10 might automatically install a Microsoft Windows version of the Arduino Mega driver. This is not the driver LANforge expects. These instructions will guide you how through uninstalling an old driver and installing the new driver from the Arduino website.
If you have recently removed a driver, you might need to reboot your Windows system for it to complete the driver installation process.
  1. You want to install the windows version of the LANforge Server beforehand.

    For more information see Installing LANforge Server on Windows

  2. Follow the link to the Arduino project to download the latest driver :Download Arduino IDE screenshot
  3. Download the Arduino IDE zip file to your desktop. Use Right-click→Extract All... to expand the contents to a folder on your desktop. screenshot
  4. This process requires you to operate the Control Panel as Administrator.
  5. Getting to the Device Manager
    1. Type Control-F for Find
    2. Search for Device screenshot
    3. Select Device Manager
    4. In the Device Manager window, right-click on the computer and select Scan for hardware changes screenshot
  6. If you find a previously installed driver, uninstall it. Especially if this is labeled Windows Arduino Mega
    1. Right-clickUninstall screenshot
    2. Select Delete the driver software for this device, and click OK screenshot
    3. Right-click on the computer, and select Scan for Hardware Changes
    4. You might need to un-plug and plug-in your Attenuator.
    5. If the right-click options menu does not allow you to change drivers, reboot your system.
  7. Install the Arduino IDE Driver

    1. In Device Manager, you want right-click on the Unknown Device and select Update Driver Software... screenshot
    2. Select Browse my computer for driver software: screenshot
      1. Browse to Desktop\arduino-1.8.9\drivers and click OK screenshot
      2. Click Next screenshot
      3. You will see the Update Driver Software confirmation. Click Close. screenshot
    3. You should not need to reboot your system in order to run the Attenuator.

Connect to LANforge using Remote Desktop

Goal: Operate your LANforge's Linux desktop by accessing it with Windows Remote Desktop utility.

LANforge computers on Intel hardware are typically installed with a full Linux desktop. You can use the LANforge GUI, do traffic sniffing, open terminal windows, and office software to look at report data over remote desktop. LANforge computers are pre-configured with RDP and VNC desktop services.
  1. From your Windows Start Menu, type "remote" and Remote Desktop Connection should be an option. screenshot
  2. If you are using the Start→Run menu, type mstscEnter screenshot
  3. If you want to create a desktop shortcut, explore the folder C:\windows\system32 and right-click mstsc.exe
  4. Configure your connection:
    1. Fedora version 24 and 25 have a bug in the vncserver triggered by xrdp. The effective way to use rdesktop on those systems is to select an Xorg session for connecting (not a Xvnc session).
    2. When connecting to Fedora 14-23 systems:
      1. User Name: lanforge screenshot
      2. You will not need to fill out the xrdp login screen.
    3. When connecting to Fedora 24-25 systems:
      1. Do not specify a user name, and select Always ask for credentials. screenshot
      2. Select Xorg as the session type screenshot
      3. Specify username lanforge and password lanforge screenshot
    4. Local Resources screenshot
      1. If your rdesktop session immediately closes, you might have hit the xrdp clipboard bug. If so:
      2. For Windows Remote Desktop (mstsc.exe): unselect Local Devices→Clipboard
      3. For Linux rdesktop, use the command: rdesktop -a16 -r cliboard:off -u lanforge [machine-name]
    5. Disable remote audio settings screenshot
    6. Disable local printers screenshot
    7. Set Server authentication to Connect and do not warn screenshot
    8. Connection quality can be 16-bit (millions of colors)
  5. Click Connect to connect to the default desktop, the default password is lanforge screenshot
  6. When you are DONE with your connection, you may close the Remote Desktop window. You will not be logged out. However, if you log in without setting the Username option, you will be logged into a new session alongside your old session. If you see this screen below, you are starting a new desktop session: screenshot
  7. To reconnect to your previous desktop session, make sure you use the Username lanforge in your connection settings.
  8. To logout of the desktop session, select System→Log Out from the top window of the Linux desktop. screenshot

Connect to LANforge using VNC Viewer

Goal: Operate your LANforge's Linux desktop by accessing it with the VNC Viewer utility.

LANforge computers on Intel hardware are typically installed with a full Linux desktop. You can use the LANforge GUI, do traffic sniffing, open terminal windows, and office software using a VNC Viewer program. LANforge computers are pre-configured with RDP and VNC desktop services.
  1. You can download a variety of viewers:
    1. Check for viewer packages on your LANforge web page: screenshot
    2. or download RealVnc
    3. or download TightVnc
  2. From your Windows Start Menu, type "vnc" and VNC viewer should be an option. screenshot
  3. If you are using the start menu, it will be under either in All Programs > RealVNC or TightVNC screenshot
  4. Double click the vnc icon and it will ask you for the IP address. You want to set the Encryption option to off because we presume you are connected directly to the LANforge. screenshot
  5. VNC Viewer might warn you about connecting without encryption. This is a valid warning if you are connecting across public networks. screenshot
  6. The password is lanforge. screenshot
  7. You will see the LANforge Linux desktop. This is not the same desktop that is actually running on the console if you have a monitor and keyboard connected. screenshot
  8. When you are done with your connection, you may close the VNC viewer window. You will not be logged out. When you connect using VNC viewer again, it show the current state of that desktop. connect you to the last used VNC session.
  9. To restart the vnc desktop session, select you can issue either of these two commands. You start using ssh (PuTTY et. al.) to connect as lanforge to the LANforge machine, and:
    1. sudo systemctl restart "vncserver@:1.service"
    2. or
    3. sudo vncserver -kill :1

Display WireShark Using Cygwin

Goal: We will display the WireShark application on Windows using Cygwin when we press Sniff Packets which actually runs WireShark on the Linux LANforge machine.

The native display protocol for Linux (and Unix) is the X Display Protocol. The project provides Linux software that runs natively on Windows. You can run an X display server on Windows that accepts connection from LANforge. We will walk through setting up Cygwin and configuring an X display.
  1. Installing Cygwin and the X display components
  2. We will start at and download the Cygwin installer. screenshot
  3. Download setup-x86.exe or setup-x86_64.exe as appropriate. Go to your Downloads folder and double start the program. screenshot
  4. Next screenshot
  5. Next screenshot
  6. Next screenshot
  7. Choose a mirror that might be close to you, click Next screenshot
  8. Now you see a the software selection screen, sorted by category. Some of these entries appear two or more times, because they belong to multiple categores. Try using the search box in upper middle above the software list to search for the packages listed below. screenshot
  9. The items you want to search for are
    • openssh
    • xorg-server
    • xinit
    • rxvt
    • xlaunch
    1. Search for openssh and click the Skip property once to change it to the most recent version to set it to install. screenshot
    2. xorg-server provides the X display system screenshot
    3. xinit helps the X system launch screenshot
    4. xlaunch is what you will drag to your task bar to launch your Cygwig X server screenshot
    5. rxvt and rxvt-unicode are more useful terminals than the minterm program that Cygwin provides by default. screenshot
  10. Click Next and let the installer finish the installation of the Cygwin packages. You will see a Cygwin Terminal icon appear on your desktop and new Cygwin icons in your Start menu. screenshot
  11. Next we will right-click on the Cygwin Terminal icon and select Open File Location screenshot
  12. In the Explorer window, scroll to find xlaunch.exe, and drag it to the Task Bar screenshot
  13. Click the xlaunch icon on the task bar, and click Next screenshot
  14. Next screenshot
  15. Check Disable Access Control and add the option: -listen tcp. Click Next screenshot
  16. Firewall, Click Allow Access screenshot
  17. If the LANforge Messages window reports 'No Access', you might need to use xhost.exe to grant X11 access. screenshot
    1. Open a CMD window screenshot
    2. Go to the cygwin\bin folder:
      C:\> cd \cygwin\bin
    3. Use xhost.exe to open permissions:
      C:\> .\xhost.exe +
  18. Now your X display service is running. You can check that it's running by clicking into the System Tray and seeing if the icon is there. screenshot
  19. Launch the LANforge GUI from your desktop. Select a port from the Port Mgr tab. Notice how the Disp field has your laptop's LAN address. This is the display address the remote machine will display the Wireshark window to. screenshot
  20. You will see WireShark screenshot
  21. Resources and other Documentation:

Finding LANforge Report Data

Goal: Properly configured, the LANforge server or the LANforge GUI can collect connection performance information in CSV format.

By default, your LANforge server and your LANforge client do not save the data on connection and port performance. When you configure the save destination for this data, you can use it with any other tool that can read a CSV file.

Finding LANforge Report Data

Select your Save Location

You can tell the LANforge server to save data to a directory locally on the management machine, and you can configure your workstation running the the LANforge GUI to save data to a local desktop folder. First, find the Reporting Manager dialog by in the Reporting menu, and select Report Manager the client.

GUI Data Collection (Desktop Folder)

Collecting data on your local workstation is very convenient if you can leave the GUI running for the duration of your test scenario. The format of the data here should be similar to the format of the data saved to the server directory. The folders for collecting data are relative to the folder you start your GUI from. If you type in lf_data that probably means C:\Users\mumble\AppData\Local\LANforge-GUI\lf_data. You probably want to put in a fully qualified path thats more intuitive, like C:\Users\mumble\Documents\lf_data.

Generate Report

The Report Generator uses the local data files. In that dialog shows the Report Input Directory field is a local folder where the CSV files collect. The Save Reports to Directory field is where HTMl and PDF files should collect.

Server Data Collection (Server Directory)

If your test scenario runs longer than your GUI can be up, you can configure the LANforge server to collect the data. The directory is relative to the /home/lanforge directory, so if you enter lf_data, you would find the CSV files in /home/lanforge/lf_data.

You can take a look at the data files easily. Here is a server data collection directory:

And using a utility like notepad, vi, more or less you can look at the file contents:

Using Libre Office

Importing the file into a spreadsheet like LibreOffice Calc is simple:

You only need to separate on comma (,)

The timestamp column

Libre Office does not have a builtin formula to do this, but it has been discussed here. And the solution is a formula that looks like this:

and then you format the column as Date.

Scripting with Bash

There are a number of ways to collect an dort the data with shell utilities. The first utility to consider is cut, then awk. The first column of the endpoint file we are going to read is the timestamp, the 14th is the rx bytes.

Reading the Data and RX Bytes

Converting Unix Date
 $ head -n2 c201-A_1488414451.csv | cut -d, -f1
 $ date -d @1488414454125
Mon Dec 23 19:28:45 PST 49135
Using bash
 $ head -n2 c201-A_1488414451.csv | (while IFS=, read -a L; do echo ${L[13]}; done)
Using cut
 $ head -n2 c201-A_1488414451.csv | cut -d, -f14
Using awk
 $ head -n2 c201-A_1488414451.csv | awk -F, '{print $14}'

head -n2 c201-A_1488414451.csv | awk -F, '{print $1 "\t" $14}'
TimeStamp       rx_bytes
1488414454125   33847640064

Scripting with Perl

It is a lot easier to do math with a perl script than a bash or an awk script. You can pipe things into perl or perl will read the last argument of the -ne switches as an input file.

 $ head -n2 c201-A_1488414451.csv \
      | perl -ne '@v=split(/,/,$_); print "$v[0]\t$v[13]\n";'
TimeStamp      rx_bytes
1488414454125  33847640064

perl -ne 'BEGIN{$tt=0;@tstamps=();@rxb=();} \
  {@v=split(/,/,$_); push(@tstamps, $v[0]); push(@rxb, $v[13]);} \
  END{$dt=$tstamps[$#tstamps] - $tstamps[1]; $db=$rxb[$#rxb] - $rxb[1]; \
    print "Time: $dt,  Total:$db\n";}' \
Time: 18959363,  Total:1213399040

Not everthing you do in perl is going to be a one-liner. Here's an example of the same script as a more properly formatted perl file:

my $tt=0;
my @tstamps=();
my @rxb=();
while(<>) {
  @v = split(/,/, $_);
  push(@tstamps, $v[0]);
  push(@rxb, $v[13]);
$dt = $tstamps[$#tstamps] - $tstamps[1];
$db = $rxb[$#rxb] - $rxb[1];
print "Time: $dt,  Total:$db\n";

Writing Disk Images on Windows

Goal: Copy an installed OS file-system image onto a drive that you will install into a LANforge system that lacks display hardware.

Many LANforge ICE WAN emulator machines are embedded systems that lack display hardware. Installing an OS using only the serial console can be very inconvenient. The easy solution is to perform the installation on similar hardware that does have display hardware, and then move the drive to the embedded device. Here, we learn how to use Etcher on Windows to write a compressed disk image to an mSata drive plugged into a USB3 adapter.
  1. Here we're using Etcher which handles compressed file system images without any trouble. There are other programs (like Win32 Disk Imagaer or dd for windows) but those are more complex to use.
  2. Items we'll want:
    1. 30GB or larger mSATA drive screenshot
    2. USB3 mSATA drive adapter screenshot
    3. The image writing program Etcher
  3. Download and install Etcher screenshot
  4. Identify your drive in Control Panel → Hardware and Sound → Hardware and Printers. screenshot
  5. Download your image file: screenshot
  6. Start Etcher screenshot
  7. Select the compressed image: screenshot
  8. Select the removable drive screenshot
  9. You might have to enable unsafe mode if the drive you plugged in has previously been used
    1. in Settings, enable Unsafe mode screenshot
    2. Select the removable drive screenshot
  10. Select the removable drive screenshot
  11. Write image.
    1. click Flash screenshot
    2. It might take 20 minutes to write a 20GB (uncompressed) image. screenshot
  12. Make coffee. screenshot
  13. When the image is finished writing, close etcher and use the Safely Eject Thing dialog in the system tray.
    1. right click screenshot
    2. select device screenshot
  14. Unplug your drive from the computer, remove the msata drive drive from the USB caddy and then install into your embedded device

Adding a LANforge Virtual Machine

Goal: Add a virtual machine running LANforge to a LAN with a physical LANforge manager.

We review the configuration steps necessary to add a virtual LANforge resource. The guest instances will be configured to export MAC-VLAN ports to run traffic on their physical management port. The example here uses VirtualBox 5.2.10 and Fedora 27 Server edition, but our current recommendation for virtual machine platforms is actually libvirtd/kvm.
  1. Create a new guest instance.
    1. When creating the guest, we should use 2 GB of RAM: screenshot
    2. 60 GB of disk: screenshot
    3. Omit a floppy drive, use a USB table as pointing device: screenshot
    4. Allocate two or more cores and PAE/NX: screenshot
    5. And the usual virtual processor features: screenshot
    6. We don't need graphics on these nodes, so use minimum graphics memory: screenshot
    7. Enable RDP access, that is useful. It might be a good habit to allocate separate RDP ports per host, we'll use 9134 for the first guest, 9135 for the second screenshot
    8. Enable Host I/O caching for your SATA device. Specify the Fedora 27 Server ISO image as the DVD: screenshot
    9. Disable Audio screenshot
    10. Configure the network adapter to: screenshot
      1. Use the LAN bridged adapter br0
      2. Use a server adapter driver
      3. Enable Promiscuous Mode to allow sniffing
    11. Start the installation screenshot
    12. Under System->Installation Destination please manually partitioning is necessary. screenshot
      1. Avoid selecting XFS or BTRFS file systems formats.
      2. Create a 1GB partition for /boot, select ext4 filesystem format.
      3. Use the remainder of the drive space for /
      4. If you want to separate the / and /home partions select 35GB for / partition.
    13. Set the root password to lanforge. Click Done twice. screenshot
    14. Add user LANforge: screenshot
      1. Make user lanforge an Administrator
      2. Set password to lanforge
      3. Click Done twice
    15. When installation finishes, reboot. You will see a login prompt: screenshot
    16. Login as root. Do updates: dnf update -y
    17. Install perl: dnf install -y perl
    18. Set guest's hostname: hostnamectl --static set-hostname atlas-fedora27s01
    19. Reboot: shutdown -r now
  2. Install LANforge on the guest instance. Start by logging in as root: screenshot
    1. Use wget (or curl) to download lf_kinstall.txt:
    2. cd /root
    3. wget
    4. chmod +x
    5. You don't need to do a burn in, so turn off the disk check:
    6. touch /home/lanforge/did_cpuburn
    7. Install LANforge: ./ --lfver 5.3.7 --kver 4.13.16+ --do_all_ct
    8. You can disable the VNC Server and Xrdp services on these guests:
      systemctl stop vncserver@\:1 xrdp.service
      systemctl disable vncserver@\:1 xrdp.service
      systemctl daemon-reload screenshot
    9. When installation finishes, reboot: shutdown -r now
    10. On next boot, you will see a LANforge kernel option, it should be automatically selected: screenshot
  3. From your LANforge GUI, configure a MAC-VLAN the on default Ethernet port.
    1. In the LANforge GUI, choose the Port Mgr tab, and highlight the new enp0s17 port: screenshot
    2. Click the Create button
    3. create one MAC-VLAN port screenshot
      1. Select MAC-VLAN
      2. Quantity: 1
      3. Select DHCP-IPv4
      4. Click Apply
    4. You will see the new port in the GUI: screenshot
    5. In the guest VM, you will also see the new port:ip -br a show screenshot
  4. Add a second VM
    1. Shut down the previous VM: shutdown -r now
    2. clone the VM
      1. Select the Reinitialize MAC addresses choice, these machine will operate simultaneously. screenshot
      2. Verify the MAC address of the new guest is set screenshot
      3. Boot the second guest
    3. Change the hostname of the second guest: [root@localhost]# echo 'atlas-fedora27s02' > /etc/hostname screenshot
    4. Make sure that the MAC address of the second guest is not listed in the ifcfg-enp0s17 file. screenshot
      1. Compare the adapter to the file:
      2. cd /etc/sysconfig/network-scripts
      3. cat ifcfg-enp0s17
      4. If it is listed, change it or remove it.
    5. LANforge changes the /etc/udev/rules.d/70-persistent-net.rules file.Edit tht file those as to match the value of your mac address:
      cd /etc/udev/rules.d
      ip li show enp0s17
      cat 70-persistent-net.rules
    6. Stop LANforge and change the resource ID for this guest:
      service lanforge stop
      cd /home/lanforge
      resource 5
      config screenshot
    7. Reboot the second guest: shutdown -r now
    8. Start up your first guest (resource 4)
    9. In your LANforge GUI, you should see your two VMs.
    10. Create a MAC-VLAN port for the second guest
  5. Create a VOIP connection between the two guests.
    1. In the VOIP tab, click Create screenshot
    2. You configure: screenshot
      1. Side-A will be resource 3
      2. Side-B will be resource 4
      3. Click Apply
    3. See the newly created connection: screenshot
    4. In the VOIP/RPT tab, click Start
    5. Monitor traffic on the connection with the Modify->View button screenshot

Configuring Serial Connection to LANforge

Goal: Using a serial cable and terminal emulator on Windows to connect to LANforge.

If you experience crashes or system misconfiguration, a network link to LANforge can become unavailable. LANforge machines are shipped with a serial cable for just this possibility. Most LANforge servers come with standard RS232 DB9 pin serial ports, other models have a special RJ45 style connector. You might need a USB to Serial adapter to connect your laptop to the serial cable.
  1. Connect Serial Cable to LANforge
    1. We will use a CT525 for our example There are two different types of CT525, some have a I/O shield with colors, others do not. Both have DB9 serial ports:
    2. Picture of an unmarked I/O plate: screenshot
    3. Picture of a colorized I/O plate: screenshot
    4. Picture of a colorized I/O plate plugged in: screenshot
    5. Other LANforge chassis models can have either RJ45 or DB9 serial ports.
  2. Connect Serial Cable to Windows
    1. Chances are you will be connecting a USB to Serial adapter to your laptop.
    2. Typically, right after you connect the cable to your USB port, you will see a message from Windows letting you know a new drive has been installed.
    3. Windows will map this USB adapter to a COM port. Use Device Manager to discover the new COM port:
      1. Press the Windows key and type device manager screenshot
      2. Hit Enter to open the Device Manager
      3. In Device Manager, select Ports screenshot
      4. In this example, we see that our new USB device was assigned COM3.
  3. Configure PuTTY to connect to serial port
    1. Press the Windows key and search for putty screenshot
    2. When you double click on the PuTTY icon and it launches, you can start customizing your session preferences screenshot
    3. Start by setting your connection type (serial), serial device (com3) and speed (115200). Name your session 'com3' screenshot
    4. Select category Serial, specify the Serial Line COM3, speed (115200) and set both Parity and Flow Control to None. screenshot
    5. Select the Session→Logging category, select Printable Output and name set the Log file name as you prefer. This allows you to collect your commands as notes for later. screenshot
    6. Select the Session category, save the com3 profile and click Save screenshot
    7. Click the Open button. You will see a terminal window appear.
  4. Use PuTTY to Log In over COM3
    1. If the screen is blank, hit Enter to see a login prompt.
    2. Enter username lanforgeEnter, password lanforgeEnter screenshot
  5. Collect console output to a logfile
    1. step 1 screenshot
    2. step 1 screenshot
  6. Common Commands Cheat Sheet: Hit Enter after all commands
    1. pwdEnter ⋮ print current directory
    2. lsEnter ⋮ list items in directory
    3. cdEnter ⋮ change to your Home Directory
    4. cd /home/lanforgeEnter ⋮ go to LANforge home directory
    5. cd /rootEnter ⋮ go to root user's home directory
    6. sudo ./serverctl.bash restartEnter ⋮ Restart LANforge service
    7. sudo rebootEnter ⋮ reboot machine
    8. ip a showEnter ⋮ show interface addresses
    9. df -hEnter ⋮ show disk usage
    10. mv /home/lanforge/scripts/script.shEnter ⋮ move file to new name
    11. dos2unix script.shEnter ⋮ Remove DOS/Windows CRLF style line endings
    12. chmod +x script.shEnter ⋮ Turn script executable
    13. ./script.shEnter ⋮ Run script in current directory
  7. Example of clearing disk space on a LANforge machine
    1. One common problem with any LANforge machine is cleaning out old kernels. This is an example that shows you how to check disk space and how to remove unused kernels.
    2. Check disk space with the df -h command screenshot
    3. Use the dmesg command to see if there are system warning. screenshot
    4. go to the /boot directory. The uname -r command tells you which kernel you are currently running. You may remove old ct kernels. screenshot
    5. In addition to removing old kernels, you can remove modules that correspond to those kernels screenshot
    6. After old kernels and modules have been removed, we re-run grub2-mkconfig to regenerate the boot menu: screenshot
    7. the results will look like this: screenshot

Connecting SMA Cables to LANforge

Goal: Connect the antennas of your device under test to LANforge using SMA cables and a fixed attenuator.

Many WiFi testing scenarios benefit from some amount of WiFi isolation. Connecting the radios of the Device Under Test (DUT) to LANforge's radios using SMA cables can improve connection quality. Using a fixed attenuator can reduce a direct signal so that it is heard by the radios without distortion.
  1. The polarities of the cables must match screenshot
  2. Begin by connecting the SMA Female end of the fixed attenuator to the SMA adapter. screenshot
  3. We see that the exposed end of the sma_adapter is RP-SMA-Male. RP means Reverse Polarity. screenshot
  4. Connect the attached attenuator and adapter to the LANforge radio antenna. This exposes the SMA Male end of the attenuator. Your DUT might not have adequate space to mount a fixed attenuator to it, so we suggested connecting it to the LANforge. screenshot
  5. The polarities of the cable end must match the end of the fixed attenuator. The cable end for this side is SMA-Female. screenshot
  6. See how the cable connected to the lanforge has both the adapter and the attenuator. It should be safe to use the attenuator and adapter anywhere along a SMA path. screenshot
  7. Connect the other end of the cable to the Device Under Test (DUT). Your DUT might use different antennas so you might need to use another adapter. screenshot
  8. We have connected one antenna of our DUT to the one antenna of our LANforge. Repeat this for multiple antennas. screenshot

Diagnose Problems with GUI on Windows

Goal: Learn how to diagnose problems running LANforge client on Windows.

The LANforge client (GUI) can encounter variety of difficulties depending on the amount of RAM and version of Java running on your desktop. Read this guide to learn steps to take to collect error messages and how to fix out of memory problems.
The LANforge client can be both the GUI running interactively, or in headless HTTP mode.
  1. Run the client from a CMD window

  2. Right click on LANforge GUI icon and select Open File Location screenshot
  3. You will see the folder wher the LANforge client is installed screenshot
  4. Right click on folder area to right of files, and select Run CMD here or Run PowerShell here. This might require that you Shift-Click on anything that might be selected in the directory to un-select it. screenshot
  5. You will see a terminal window open screenshot
  6. Start the client using the command .\lfclient.batENTER screenshot
    1. Double-clicking lfclient.bat in the Windows Explorer window will start the client in a CMD window, but the window will disappear when the client quit/exits/leaves.
  7. Be Aware of Quick Edit

    1. Quick Edit allows you to highlight text quickly with the mouse; it is a feature of both the CMD and PowerShell windows. CMD windows have the distinct drawback of halting execution while text is highlighted.
    2. Press ESC to clear text selection
    3. You can change the setting by clicking in the upper left corner, selecting Preferences, then look for Qui,ck Select. screenshot

      For more information see Windows Server 2016 Features

  8. Copy an Error

  9. Candelatech introduces features into LANforge quickly, and discovering a problem in the LANforge Client occasionally happens--and we want to hear when it does! You can help by copying the terminal output and emailing it to us (at

    Various kinds of errors leave messages we can find in the terminal like when the LANforge client:

    1. ...will not start after double clicking the icon. This might be caused by a missing or mismatched version of the Java runtime, an error in the start-up script, or a program error.
    2. ...unexpectedly quits. Probably a program error.
    3. ...does not respond. Possibly a program error, caused often you will see many exceptions printed to the terminal.
  10. A Java exception is a rather long list of method calls (a stack trace) that starts with the exception message. Sometimes the exception message is IllegalArgumentException, sometimes it is null (a null pointer exception)

  11. Scroll the terminal window to see the top of the exception and highlight the exception message and as much of the stack trace as possible. Below is a picture of a condition where the LANforge client script has an error and will not start. screenshot
    1. Pressing Enter after highlighting the text copies the text into your clipboard.
    2. The laptop might not have an email client installed. In that case, open notepad.exe or wordpad.exe from via the Start menu, and paste your stack trace into your text editor. screenshot
    3. If your circumstances don't allow highlighting, copying and pasting, you can take a screen capture, usually by pressing Alt+PrtScr shortcut.
    4. When contacting us, please describe the steps you took to reach this error. We need to be able to reproduce the error in order to fix it.
  12. Out of Memory Conditions

  13. Candelatech provides a 32-bit and a 64-bit version of the LANforge client. We generally suggest people use the 64-bit client, because most recent laptops are running 64-bit operating systems. This is a common fix for running out of memory.

    For more information see LANforge Downloads

  14. When running a WiFi Capacity Test, the generated report consumes significantly more memory than a mere HTML or PDF version of the report does. If you have multiple WiFi Capacity Test reports open, we suggest you save them and close the report windows.
  15. Running tests for longer periods of time (like days) can also consume significant memory. By default, the LANforge client will only allocate up to two-thirds (2/3s) of the system memory it detects available at start-up. If there are programs like Chrome, Outlook and possibly Electron based applications open, those can be using most of your laptop's memory to begin with. You might need to exit other programs in Windows and restart the LANforge client in order allow it to have more memory.
  16. You can also edit the start-up script to configure the maximum memory permitted to the Java runtime. That is discussesd next.
  17. Edit the start-up script

  18. While it is possible to edit files with notepad.exe, that text editor has few conveniences. Please consider using Notepad++ if you don't already have a text editor available.

    For more information see Download Notepad++

  19. Right click on the lfclient.bat startup script, and select Edit with Notepadd++ screenshot
    1. The file opens in the editor at the top. You will want to jump to the end of the file. screenshot
    2. At the end of the file, notice the -Xmx option for the java program. You will edit this to the maximum amount of memory you want to allow the program. screenshot
    3. In this example, we've edited the start up script to request 2GB of memory. If you request more than the system will give you, the Java will give you an error and quit. screenshot

      For more information see Tuning Java Machines

  20. Email if you have questions or need help.

Recovering Filesystems

Goal: Recover a LANforge system that boots into Emergency Mode

If your LANforge boots into Emergency Mode, your system is experiencing file-system corruption. Follow these instructions to check the filesystems. This process will require a monitor and keyboard or a serial cable connected to the LANforge.
File system corruptions are caused by power-off events without properly shutting down the system
  1. The emergency mode prompt looks similar to this:
    Give root password for maintenance
    (or type Control-D to continue):
    1. The messages beforehand that begin with [ OK ] can be ignored.
    2. Messages beginning with ath10k_pci can be ignored.
  2. We assume you'll press the Enter () key when executing the commands in further examples.
  3. Provide the root password: lanforge
  4. The we next need to determine where our filesystems are mounted. You might have filesystems on partitions, or on LVM volumes. Use the command mount | grep ext4 to find your partitions:
    mount | grep ext4
    /dev/sda2 on / type ext4 (rw,relatime,nodelalloc)
    /dev/sda4 on /home type ext4 (rw,relatime,nodelalloc)
    /dev/sda1 on /boot type ext4 (rw,relatime,nodelalloc)
    This example shows partitions.
    Note that inspecting /etc/fstab often does not show you device partitions, rather it shows you volume or partition UUIDs.
  5. Example of filesystems on volumes:
    mount | grep ext4
    /dev/mapper/fedora-root on / type ext4 (rw,relatime,nodelalloc)
    /dev/mapper/fedora-home on /home type ext4 (rw,relatime,nodelalloc)
    /dev/sda1 on /boot type ext4 (rw,relatime,nodelalloc)
    Notice that /boot is typically not a LVM volume.
  6. Issuing the fsck commands

  7. For each of those filesystems in the partition example above, you will execute the below commands:
    1. fsck -fy /dev/sda2 (for /)
    2. fsck -fy /dev/sda4 (for /home)
    3. fsck -fy /dev/sda1 (for /boot)
  8. For the volumes example above, you will execute the below commands:
    1. fsck -fy /dev/mapper/fedora-root (for /)
    2. fsck -fy /dev/mapper/fedora-home (for /home)
    3. fsck -fy /dev/sda1 (for /boot)
  9. Configuring Filesystems Check on Reboot

  10. The commands below involve setting the 'mount count' parameter to 1. Every time the filesystem is mounted, it will perform a check. The following examples ensure that full journaling is enabled on the filesystem. This ensures the most amount of recovery. And after that, modern versions of Fedora have metadata checksumming available. Older LANforge systems do not have this.
    1. Filesystem Check on Every Mount

      The filesystems do not need to be unmounted to set this parameter. Only the partition example is shown, the volumes example uses similar commands.
      1. touch /forcefsck (this technique works with any model of filesystem)
      2. tune2fs -c 1 /dev/sda2 (for /)
      3. tune2fs -c 1 /dev/sda4 (for /home)
      4. tune2fs -c 1 /dev/sda1 (for /boot)
    2. Tune the Filesystem for Full Journaling

      The filesystems do not need to be unmounted to set this parameter. The commands for the volumes version is similar to the partition example below.
      1. tune2fs -o journal_data /dev/sda2 (for /)
      2. tune2fs -o journal_data /dev/sda4 (for /home)
      3. tune2fs -o journal_data /dev/sda1 (for /boot)
    3. Note: Inspect /etc/fstab for conflicting mount options. The folling example shows mount options applied in the fstab file:
      mount | grep ext4
      /dev/sda2 on / type ext4 (rw,relatime,nodelalloc)
      /dev/sda4 on /home type ext4 (rw,relatime,nodelalloc)
      /dev/sda1 on /boot type ext4 (rw,relatime,data=writeback)

      grep data= /etc/fstab
      UUID=1c1b4732-653f-47dd-a106-ae17cf5b12a9 /boot ext4 data=writeback  1 2
      Notice the fstab entry for /boot? It has overridden the data journaling mode. Erase that setting from the fstab mount options.
    4. Enable Metadata Checksumming (optional)

      It is only practical to apply metadata checksumming in the below conditions. You will not be able to apply it to the root filesystem / because it cannot be unmounted when you boot the system.
      1. Fedora 27 or more recent
      2. tune2fs 1.43 or more recent
      3. crc32c or libcrc32c modules loaded
      4. you can unmount the filesystem.
    5. To Boot into Emergency Mode, follow these steps:
      1. Reboot system into Emergency Mode by appending the word emergency at the end of your grub boot option.
      2. umount -f /home
      3. umount -f /boot
      4. fsck -fD /dev/sda1 (remember that's /boot)
      5. fsck -fD /dev/mapper/fedora-home
      6. tune2fs -O metadata_csum /dev/sda1
      7. tune2fs -O metadata_csum /dev/mapper/fedora-home
    6. Disable Drive Write Caching (optional)

      Drives typically ship with write caching enabled for a performance boost. SSDs have this as well. By turning it off you trade some performance for increased data safety. LANforge systems do not ship with write caching disabled. To make this setting enabled every boot, it needs to be added to /etc/rc.local. LANforge systems have rc-local.service enabled by defualt.
      Only disable write caching if your machine powers off without shutdown frequently
      1. vi /etc/rc.local
      2. Add the line /sbin/hdparm -W0 /dev/sda
      3. Save the file.
      4. Reboot, or issue the command for this booted session:
        /sbin/hdparm -W0 /dev/sda

Automatically Start LANforge GUI

Goal: Configure LANforge to automatically start LANforge GUI on boot or login.

Follow these steps to Configure LANforge to automatically start LANforge GUI on boot or login. Requires version 5.4.1 or greater.
  1. Quick Start
    1. Open a terminal or connect to your lanforge machine via ssh:
    2. $ cd /home/lanforge/LANforgeGUI_5.4.1
      $ cp LANforge-auto.desktop ~lanforge/.config/autostart
      $ sudo systemctl restart vncserver@:1.service
    3. If you were connected via VNC, your session will close. When you reconnect via VNC, you will see a LANforge GUI running on the desktop. This will now start again every reboot.

Configuring OpenVPN on Ubuntu

Goal: Connect your laptop to a VPN with the provided keys and configuration file.

Connecting to the office network remotely requires you to install the openvpn package and place the config files in the correct places. You can start and stop the VPN using simple commands at a terminal.
  1. Install OpenVPN

  2. Open a terminal and see if you already have openvpn installed:
    $ which openvpn
    This means you have OpenVPN installed.
  3. Installing openvpn is a simple command:
     $ sudo apt install openvpn
  4. Add your Config Files

  5. You should be provided with these files:
    1. your-laptop.key ← This is your private key
    2. your-laptop.crt ← This is your certificate
    3. ca.crt ← This is the VPN server certificate
    4. candelatech.conf ← The config file for the connection
    You will place these files in /etc/openvpn. The files should be owned by root, so become root and copy them with this technique:
     $ sudo -s
    [/home/amelia] # cd /etc/openvpn
    [/etc/openvpn] # cp ~amelia/Downloads/your-laptop.key .
    [/etc/openvpn] # cp ~amelia/Downloads/your-laptop.crt .
    [/etc/openvpn] # cp ~amelia/Downloads/ca.crt .
    [/etc/openvpn] # cp ~amelia/Downloads/candelatech.conf .
  6. Starting and Stoping the VPN Connection

  7. In a terminal, cd to /etc/openvpn and start the connection as root:
     $ cd /etc/openvpn
    $ sudo openvpn candeltech.conf
    Press Control-C in that window to stop the VPN connection.
  8. Example Config File

  9. client
    dev tun1
    proto udp
    remote 1194
    #remote 443
    script-security 2
    resolv-retry infinite
    verb 3
    ca ca.crt
    cipher AES-256-CBC

Configuring OpenVPN on Windows

Goal: Connect your laptop to a VPN with the provided keys and configuration file.

Connecting to the office network remotely requires you to install the openvpn package and place the config files in the correct places. You can start and stop the VPN using simple commands at a terminal.
  1. Install OpenVPN

  2. Download and install the latest version of OpenVPN GUI on windows.
    The list of packages to download is at the bottom of the page: screenshot

    For more information see Openvpn Community Downloads

  3. In your Downloads folder, double click to start the installer. screenshot
  4. When the installer asks you what components to choose, you just need those necessary for being a client. You do no need to install the EasyRSA script package. screenshot
  5. Add your Config Files

  6. OpenVPN keeps configuration files in C:\Program Files\OpenVPN\config. Open this folder with Windows Explorer. screenshot
  7. You should be provided with these files:
    1. ca.crt ← This is the VPN server certificate
    2. your-laptop.key ← This is your private key
    3. your-laptop.crt ← This is your certificate
    4. candelatech-udp.conf ← The config file for establishing a UDP connection. This is the faster type of connection.
    5. candelatech-tcp.conf ← The config file for establishing a TCP connection. TCP OpenVPN connections do not perform as well, and are useful if you are in an environment that only allows outbound TCP port 443.
    You will place these files in C:\Program Files\OpenVPN\config. you will probably be asked to give your password because the folder is owned by Administrator. screenshot
  8. Double click the OpenVPN GUI icon. If you see a warning message about no configuration files found, we're about to fix that in the next step. Click OK. screenshot
  9. Configuring OpenVPN

  10. When the OpenVPN software starts, it places an icon in the system tray.
    Click on Taskbar up arrow to see hidden taskbar items
  11. Right click the Screen with Padlock icon to see the menu. Select Settings. screenshot
  12. You will see the Settings→General tab. Here you can set OpenVPN to start automatically if you desire. screenshot
  13. Click on the Advanced tab. You will alter these settings: screenshot
    1. Change the Configuration Files→Folder value to where you saved your config files.
    2. Change the Configuration Files→Extension value to conf.
    3. Change the Log Files→Folder value to where you want to find your connection logs.
    4. Click OK
  14. Editing your Config File

  15. The candela-udp.conf configuration file is going to be formatted for a Linux machine. You will need to change the location of the certificates to absolute Windows paths.
    Backslashes \ need to be escaped: \\
    Any paths with spaces need to be "double-quoted";.
  16. Here is an example file you can highlight and copy:
    dev tun1
    proto udp
    remote 1194
    #remote 443
    script-security 2
    resolv-retry infinite
    verb 3
    ca ca.crt
    cert "C:\\Program Files\\OpenVPN\\config\\"
    key "C:\\Program Files\\OpenVPN\\config\\"
    cipher AES-256-CBC
  17. Starting and Stoping the VPN Connection

  18. After saving your config files, return to the taskbar to start an openvpn connection: screenshot
    1. Click on Taskbar up arrow
    2. Right click on the Computer with Padlock
    3. Select your connection name
    4. Select Connect

CI/CD Lights-Out Chamber Setup

Goal: Assemble a LANforge and a device under test (DUT) to operate in an unattended lab setup.

The CI/CD lights-Out chamber is composed of a CT840a chamber, a CT523c LANforge and a test-controller[1], that connects to them via serial and Ethernet.
1) A test controller is a Linux system that can be remotely accessed, and does not need LANforge installed.

Inside the chamber we have:

  • a remotely controlled power switch
  • a powered USB hub for connecting serial ports of the LANforge and DUT
  • a LED lamp
  • a USB camera connected to the LANforge machine
  • a short table to place above the LANforge for the DUT
  • the LANforge machine
  • the DUT
Once assembled, this setup can perform a battery of connectivity and traffic tests that do not require a programmable attenuator. Requires LANforge 5.4.2.
  1. Parts review

    Let's review the parts the chamber setup requires:
    1. Cables include: screenshot
      1. 3 cat5e cables
      2. 2 cat6 cables
      3. 1 USB serial adapter
      4. 1 DB9 female-female cable
      5. Also shown are annenas, with-pin
    2. You will also get two small monitor stands and a network power switch. You will be using the legs of both, but discarding one of the stand tops. screenshot
    3. You will be getting a LED lamp, a USB camera, 8 port network switch, USB hub, camera clamp, USB A-A cables.
    4. Your chamber will come with a universal power strip, AC power cord, fan AC-DC power adapter, and a printed test report. This assembly guide does not use the universal power strip. You might find a use for it. screenshot
    5. Your chamber will also come with a brass pipe mounted to a steel plate. This is a fiber tube that you can pass fiber optic cabling through. For this setup, you can refrain from installing the fiber-pipe. It is not necessary because we are using copper Ethernet cabling. screenshot
  2. First items

    1. Place the lamp in the chamber screenshot
    2. Place the power distribution unit (PDU) in the chamber on it's side.
    3. Plug the DC barrel connector for the fans into the fan power supply screenshot
    4. Plug the USB hub USB cable into back of the chamber. The bottom USB port is chamber USB 1 near the top ethernet filter port 3. The top USB port is chamber USB 2.
  3. Power Switch

    1. Port 1: USB Hub
    2. Port 2: Interior Light
    3. Port 5: 5 Chamber Fans
    4. Port 6: LANforge system
    5. Port 7: DUT
    6. Others are un-labeled. If you want to add an Ethernet switch in here, we suggest plugging it into one of the always on ports on the right side.
  4. Assemble the USB camera

    1. Your camera clamp and USB camera. Your USB camera might be manual-focus. screenshot
    2. Screw the bolt of the clamp into the tripod mount of the camera screenshot
    3. Tighten the clamp to the arm of the lamp near the top joint. The USB cable should be plugged into the LANforge when it is added. If you plug it into the USB hub, only the test-controller will be able to use it. screenshot
  5. Check espresso levels in human system

  6. Power cables

    1. Plug the PDU cable into the rear of the chamber
    2. Plug the USB hub power into port 1
    3. Plug the lamp cable into port 2
    4. Plug the chamber fan AC cable into port 5
    5. Plug the LANforge power-supply into port 6
    6. You will probably plug in your DUT power supply last, into port 7
  7. Inline Attenuators

    1. This is an SMA connector chart. Make sure your antennas and in-line attenuators have the correct pins screenshot
    2. Your 16 LANforge SMA terminals are SMA-Female. screenshot
    3. Screw 16 SMA-Male/SMA-Female inline attenuators onto your CT523c. screenshot
  8. Antennas

    1. Check that you have SMA-Male antennas (antennas are with-pin). screenshot
    2. Screw on your antennas. You will not leave them straight like this. screenshot
    3. Bend the antennas various ways to ensure they provide diversity. Not providing diverse antenna orientation means your equipment will not reach desired MCS rates. screenshot
  9. Shelf for DUT

    1. You are provided two monitor stand kits as to combine into a shelf for the DUT to rest above the LANforge CT523c. You are going to use the legs from the second kit to extend the legs of the first kit. screenshot
    2. Use a utility knife or a screw driver to separate any feet from legs sections you do not need. screenshot
    3. Here is a shelf with five segments per leg. Depending on the size of the rubber feet on your CT523c, it might be just tall enough. The other photos show a table with six segments per leg. Looks like Batman likes my work. screenshot
    4. This table clears the LANforge unit well. screenshot
  10. Network and Serial Cables

    1. The network ports on the chamber are passive Ethernet RF filters. The do not have activity lights, they do not require power. screenshot
      1. The top USB3 port is USB 2
      2. The bottom USB3 port is USB 1
      3. The top Ethernet port is 3
      4. The middle Ethernet port is 2
      5. The bottom Ethernet port is 1
    2. Cable the PDU network to chamber Ethernet port 1 screenshot
    3. Place the LANforge CT523c in the chamber and attach a CAT5e cable to the management port labeled [ MGT ] screenshot
    4. Plug the management port cable into the chamber port 2 screenshot
    5. Use a CAT6 cable to connect the LANforge [ eth3 ] port to the chamber 3 port. This represents your WAN connection. screenshot
    6. Connect the DB9 female-female serial cable to the CT523c serial port. It is labled Serial: 115200 8n1. Connect the USB serial adapter to the other end of the DB9 cable. screenshot
    7. Plug the USB end of the USB serial adapter into the USB hub. Your test controller will be able to login to the LANforge for network configuration and debugging. screenshot
    8. Plug in power to the CT523c. It is a green DC connector. Place the table over the CT523c. screenshot
    9. You may place the DUT on the table. Use a CAT6 cable to connect the DUT to the LANforge [ eth2 ] port. LANforge will serve DHCP on [ eth2 ] for the DUT and its connected stations, and will NAT and route packets out of [ eth3 ]. screenshot
    10. Plug your DUT power to into PDU port 7 screenshot
    11. Your DUT probably has a serial connector. Cable your DUTs serial cable into the USB hub. screenshot
  11. Controller Setup

    1. The test controller (aka Jump Host) pictured here is a 1U rack unit. screenshot
      1. Your rack KVM will use the left USB2 ports and VGA port of the test-controller.
      2. Connect chamber port USB 1 to a USB3 port on the test-controller.
      3. You might have to use an extra USB3 hub to control more than two CT820a chambers.
      4. Cable chamber ethernet 1 to switch, this is your PDU
      5. Cable chamber ethernet 2 to switch, this is your LANforge management port.
      6. The picture shows chamber ethernet 3 connected to the switch. This connection is at your discretion. You might have a different WAN upstream network to attach to chamber ethernet 3
      7. The USB ports may be renamed each time the system restarts. To fix this, you can create an /etc/udev/rules.d/81-usb-serial.rules file that defines the USB ports by name using the serial-number of the USB cable if it supports it, or the path (effectively port to which the USB cable is connected).
        #LF on cable with serial number
        SUBSYSTEM=="tty", ENV{ID_SERIAL_SHORT}=="AK066NLY", SYMLINK+="ttyLF1", MODE="0666"
        # AP
        # In case we have something w/out a serial number
        SUBSYSTEM=="tty", DEVPATH=="1-2.1.4", SYMLINK+="ttyAP1", MODE="0666"

        You can find the appropriate information with the udevadm info -n /dev/ttyUSB0 command.
    2. In the picture the red cable represents the control network. The yellow cable is your connection to your test controller ETH0 screenshot

Changing the logo generated in GUI reports

Goal: Correctly access and change the logo displayed at the top of GUI-generated reports in your local Lanforge GUI.

It is possible to provide your own logo and report header graphics.
  1. Open your LANforge GUI, click on Reporting, and Reporting Manager screenshot
  2. Click on Generate Report screenshot
  3. Find a desired image instead of the default report logo that fits the report logo size (within 200 x 90 px size range) and save the image into the html/images/ path within the bt_bits directory. screenshot
  4. Once the desired image is within the appropriate images folder, scroll over back to the Reporting Manager tab, click on Report Logo and select the image (and image path) to be placed in the Report logo path. Then select Report Logo. Now, once a user generates a report, the new report should print out with a different logo at the top. screenshot

Set up an SSH-tunnel on Windows, Linux, or Mac

Goal: Connect to a LANforge Linux system via a compressed tunnel connection

When connecting to your remote LANforge hardware (presumably accessible over a VPN) you will notice poor response time and lag in your LANforge GUI or your VNC connection. Many VPN connections are based on UDP protocols and packet loss might be affecting your connection quality. Below we explain how to set up SSH tunnels that increase the quality of your connection.
  1. Linux SSH tunnel Setup
    1. From the computer that you are trying to connect your SSH tunnel from, open the .bashrc file from '/home/user/'. The .bashrc file can be opened via gedit, vim, or nano. This .bashrc file is where the alias will be setup to properly invoke your ssh. screenshot
    2. Once the .bashrc file is open, type in your alias in any blank spot (that is not within another for-loop or definition). Flags used in the bash alias creation example below are as followed:
      1. -C = Requests compression of data. This is desirable for slower connections. Recommended.
      2. n = redirects stdin /dev/null. Required when SSH is running in the background.
      3. N = do not execute a remote command, useful for forwarding ports.
      4. v = Verbose mode. Causes SSH to print debugging messages about its progress.
      5. -L = bind_address:port:host:hostport format. Use this flag multiple times to forward multiple ports with one command.
      6. Please visit the SSH man page for further flags and switches:
    3. The generic setup of bash aliases for SSH are ssh -flags localport:ipaddress:remoteport. In the example included above we've included the following ports for the according reasons: screenshot
      1. 4001 -- perl scripts use this for ascii connection to LANforge server
      2. 4002 -- GUI uses this for binary connection to LANforge server
      3. 5901 -- VNC port for display :1
      4. 4131 -- local port for perl scripts to connect to .92.12
      5. 4132 -- local port for GUI to connect to .92.12
      6. 5903 -- local port for VNC to connect to .92.12
    4. Further example ssh aliases include: screenshot
      1. alias FreyaTunnel="ssh -CnNv -L 5903: -L 4131: -L 4132: lanforge@"
      2. alias SaltTunnel="ssh -CnN -L 4001: salt@"
    5. After editing the .bashrc file, source the file in order for the changes to be applied. This will enable the code without the need to turn off and restart the device. screenshot
    6. In order for our machine to remember certain passwords and access configurations, some additional edits in the ~/.ssh/config file or $HOME/.ssh/config.
    7. Next, this ssh connection will require an ssh key. This means that one needs to be generated. The private key and public key of the key pair must be saved to the local computer while only the public key of the pair must be saved to the remote server.
    8. Add your SSH key to the device being forwarded. Finally, add your public key that you generated earlier via SSH. This can be done by typing in ssh-copy-id user@ipaddress (see below example). screenshot
    9. Once the alias is added to .bashrc file and the ssh key is added to the remote device, open any terminal and simply type in the alias name. This will initiate the tunnel. For example, "FreyaTunnel" in this example would be the alias typed into any terminal. This should incur an instance of your tunnel.
  2. Windows SSH tunnel Setup
    1. There are many ways to set up an SSH tunnel, however, this cookbook will utilize PuTTy. screenshot
    2. Once PuTTY is downloaded, configure the SSH connection before adding the tunnel.

      For more information see Connecting with PuTTy.

    3. Once your session is setup, select your session that was just saved from the last cookbook, then on the left-hand panel, select Connection -> SSH -> Tunnels. screenshot
    4. After setting up the tunnel, select SSH and enable compression. This will ensure that the tunnel uses data compression. screenshot
    5. Once all the settings desired are configured, select Session, highlight the session again in Saved Sessions and hit Save for the new session settings. This will make sure that the next time logged in will include all the settings here. screenshot
    6. Now, the session is saved and can be opened by clicking Open

Understanding VRF Devices

Goal: Understand and inspect private VRF routing tables.

VRF devices are a Linux kernel networking driver that allows private routing tables for individual ports in the system. The examples below show how to find these routes. Requires version 5.3.9 or greater.
  1. VRF Driver

    LANforge has been using the Virtual Routing and Forwarding driver since around 2018. This allows private routing tables for each LANforge managed interface. VRF provides specific networking benefits to LANforge:
      1. Virtual stations gain authentic routing as delivered from the AP's DHCP service.   IP sockets bound to that station will not send DNS requests out the host's default gateway, for instance.  This helps accurately test captive portal and HS2.0 web requests that should never know about the management network.
      1. Multiple identically numbered networks can be modeled in parallel.   Emulating a peer-to-peer VPN tunnel between two STA devices   that both are on networks separated by a WAN.
  2. Disabling VRF

    This does make it more difficult to monitor the routes per port.
  3. If this feature is undesirable, you can use the following command to disable VRF:
    1. $ touch /home/lanforge/LF_NO_USE_VRF
    2. $ sudo reboot
  4. Finding VRF private routes

    To find the routes, you want to use these commands for any particular vrf device:
    1. Look for the station's master device:
      ip a show wlan3
      wlan3:  mtu 1500 qdisc noqueue master _vrf6 state DOWN mode DEFAULT group default qlen 1000
      link/ether 00:0e:8e:44:07:a1 brd ff:ff:ff:ff:ff:ff promiscuity 0 minmtu 256 maxmtu 2304
    2. When you know the master device you can display that specific routing table:
      1. A routing table with a gateway:
        ip route show vrf _vrf10
        default via dev br0 dev br0 scope link src
      2. With no default gateway:
        $ ip route show vrf _vrf15
        unreachable default

Use FireFox with a virtual station to Browse a DUT

Goal: Use FireFox with a virtual station to Browse a DUT

Access points used as a DUT in a wireless-mesh scenario might not have an ethernet port available to be able to access their management screen. Rather, they require a station to associate to the DUT to access the management console. LANforge virtual stations operate in the context of a VRF (virtual routing) device that protects them from the default routing table of the system. This makes using a browser over a station unintuitive; special commands are required to do this. Requires LANforge 5.3.9 or later.
  1. Associate a station to your DUT

    1. Create a station as necessary or use the wlan0 device
      1. if you know the SSID credentials, enter those.
      2. If you need to discover the SSID, enter anything into the SSID box, like asdf so you can start a scan. screenshot

      For more information see Create stations

    2. Scan for your DUT SSID. screenshot
    3. Configure your station to use the DUT SSID credentials and DHCP.
  2. Use the vrf_exec.bash script to start Firefox

    The vrf_exec.bash script changes the networking context for the browser so it can use your station.
    1. Open a terminal
    2. Become root: sudo -s
    3. Go to the LANforge directory: cd /home/lanforge
    4. Start firefox: ./vrf_exec.bash wlan0 firefox
  3. Possible difficulties

    If you have just rebooted your LANforge system and are jumping to step 2 without starting the LANforge GUI, you might have difficulty getting Firefox to display. By starting the GUI, it runs the xhost + command and relaxes some basic X11 security settings to let other users display windows on the desktop.

Backing Up and Migrating LANforge Data

Goal: Learn what directories under /home/lanforge are important to backup and transfer to a new LANforge.

Most of the data that LANforge produces lives in the directory /home/lanforge. Not all the files and directories under there are useful to backup or migrate to a new LANforge machine. This guide relates to Linux based LANforge machines.
We will assume for this cookbook during a restore situation you have the two LANforge systems connected on the same management network.
  1. LANforge data lives in various directories under /home/lanforge, and this is a brief explanation of the directories you will want to transfer.
    LANforge scenario data for a realm is saved on the manager (typically resource 1).
    The LANforge client (GUI) can save reports on various machines where it is running. It does not save scenario data.
  2. Below are listed the important sub-directories from /home/lanforge,. Each has a note about how important it is to back up. Directories not listed are unlikely to contain LANforge related data.
    When in doubt backing up the entire /home/lanforge directory is OK
    1. DB/
      YES this is were all your scenarios are saved
    2. Desktop/
      only if you save things here
    3. Documents/
      only if you save things here
      only if you save things here
    5. html-reports/
      yes if you want the reports
    6. lf_reports/
      yes if you want the data
    7. local/
      unlikely unless you customize strongswan
    8. report-data/
      yes if you want the data
    9. scripts/
      only if you have modified or custom scripts in here
    10. trb_entities/
      Table Report Builder saved settings only necessary if you use TRB frequently
    11. vr_conf/
      only if you save virtual router settings, nginx configs or want to save dhcp lease files
    12. wifi/
      only if you have customized wpa_supplicant.conf or hostapd.conf files
  3. Archiving Data

    Starting on your old LANforge machine, use the tar command to archive data. Add directories you want to archive to the end of the command.
    cd /home/lanforge
    tar cjf /home/lanforge-bu.tar.bz2 DB html-reports lf_reports report-data
    If you run out of space, try using /home/lanforge/check_large_files.bash to help clear room.
  4. Copy the Archive

    Copy the archive to the new LANforge:
    scp /home/lanforge-bu.tar.bz2 lanforge@your-new-machine-ip:/var/tmp
  5. Restore the Data

    On the new machine:
    cd /home/lanforge
    tar xvf /var/tmp/lanforge-bu.tar.bz2
    sudo service lanforge restart

CT714B Stand Assembly

Goal: Fully assemble a stand for CT714B attenuators.

The CT714B attenuator can be assembled in a stack with a base and threaded rods.
  1. Insert rods until they stick out a bit through the bottom. screenshot
  2. Bottom view: screenshot
  3. Add nuts to all four rods on bottom side of plate. Hand tighten. screenshot
  4. Full view: screenshot
  5. Add one spacer to each rod. screenshot
  6. Full view. screenshot
  7. Add the first CT714B. screenshot
  8. Add another set of spacers. screenshot
  9. Full view. screenshot
  10. Repeat steps 4 and 5 until all CT714Bs are stacked. screenshot
  11. Add washers to all rods. screenshot
  12. Add wing nuts to all rods. screenshot
  13. Full view. screenshot
  14. Add caps to all rods. screenshot
  15. Full view. screenshot
  16. The nuts on the bottom can easily come loose during assembly. Tighten again as needed.

Testing the CT840a Turntable

Goal: Use the script to interact with chamber door sensor, lights and turntable.

The CT840a chamber has a Modbus interface that can provide telemetry about the the door-closed sensor, light control, and turntable control and position. In order to have access to the Modbus protocol, you need a Modbus package installed on your system. The modbus controller in these chambers is simple and does not understand IP routing. You have to be connected on the same network as the modbus system.
  1. Using LANforge on Linux

  2. Test your connection to the chamber with the /home/lanforge/ script. This will verify you can reach the modbus controller.
    Available here:
    1. Source the lanforge.profile script:
      $ source /home/lanforge/lanforge.profile
    2. Use the command:
      $ ./ --targ --status 1
        Expect output similar to:
        Current-Angle: 3599 Door-Open: 0 Table-Moving: 0 Lights: 0 Fan: 1 Jog-Speed: 3 Return-Speed: 3 Absolute-Speed: 3 Jog Angle: 0
  3. Use the script to test all the chamber features.
    Availble here:
    1. $ ./  
          The desktop linux is, remember to use Alt-F2, 'mate-terminal' to get a shell.  
          Testing chamber at  
          Please close door.  
          Current-Angle: 3599 Door-Open: 0 Table-Moving: 0 Lights: 0 Fan: 1 Jog-Speed: 3 Return-Speed: 3 Absolute-Speed: 3 Jog Angle: 0  
          check output if door is closed: door == 1  
          Please open door.  
          Current-Angle: 3599 Door-Open: 0 Table-Moving: 0 Lights: 0 Fan: 1 Jog-Speed: 3 Return-Speed: 3 Absolute-Speed: 3 Jog Angle: 0  
          check output if door is closed: door == 0  
          Toggle lights  
          Did lights turn on?  
          Current clockwise angle: 3599  counter-clockwise-angle: 1  new-angle: 450  
          Did platform rotate 45 degrees?  
          Did platform rotate another 45? It should be at 90  
          Current clockwise angle: 2978  counter-clockwise-angle: 622  new-angle: 1  
          Did platform rotate back to zero?  
          Did fan turn on?  
          Toggle fan  
          Did fan turn off?  
          Toggle lights  
          Did lights turn off?  
          Current-Angle: 2700 Door-Open: 0 Table-Moving: 0 Lights: 0 Fan: 0 Jog-Speed: 3 Return-Speed: 3 Absolute-Speed: 3 Jog Angle: 621  
          You may close the chamber.
  4. Using Linux without LANforge

  5. You will want to download

    1. LANforgeServer that matches your version of Fedora. For example, Fedora 30 would be LANforgeServer-5.4.5_Linux-F36-x64.tar.gz
    2. The modprobe interface script:
    3. The chamber test script:
  6. Setup

    : This setup is intended for versions of Fedora that LANforge has been compiled for. The version of mbpoll bundled with the Server archive is specific to the glibc version the Fedora distro is built with. You do not have to run the script or use the install.bash script in the LANforgeServer directory.
    1. Create the following directories:
      sudo mkdir -p /home/lanforge/local/lib
      sudo mkdir -p /home/lanforge/local/bin
    2. Chown the directories to your current user:
      sudo chown -R $USER: /home/lanforge
    3. Expand the LANforgeServer archive in /home/lanforge:
      tar xf LANforgeServer-5.4.5_F30-x64.tar.gz
    4. Copy the mbpoll files to the new directories:
        ,,cp -r LANforgeServer/local/lib/* /home/lanforge/local/lib,,
      cp -r LANforgeServer/local/bin/mbpoll /home/lanforge/local/bin
  7. Run the scripts

    : These scripts require the mbpoll libraries in the LD_LIBRARY_PATH. The example below uses the address as the address of the CT840a chamber. Please do not confuse this with the IP of the LANforge that might be in or attached to the chamber.
    1. $ export LD_LIBRARY_PATH='/home/lanforge/local/lib:/usr/lib64'
      $ export PATH="/home/lanforge/local/bin:$PATH"
      $ ./ --targ --status 1
  8. Using Windows without LANforge

  9. Not at this time.

Remove old Reports and Data

Goal: Find and remove old reports and test data.

Running tests on LANforge for long periods of time can leave a lot of data behind. The check_expired_data.bash script can find old files to delete.This file is similar to check_large_files.bash but looks at the age of files.Introduced in LANforge 5.4.5.
  1. Download the script

    Download the script if it is not in /home/lanforge/scripts already. If you need to download the script, use the following commands:
    1. cd /home/lanforge/scripts
    2. wget
    3. chmod +x check_expired_data.bash
  2. Find the script help

    ./check_expired_data.bash -h
    -d  Find data within this directory (required)
    -t Find data this many days old or older (required)
    -f Delete files (not a default option)
    -v Print files

    See the files you would delete:
    ./check_expired_data.bash -d /home/lanforge/report-data -t 11 -v

    Actually delete the files:
    ./check_expired_data.bash -d /home/lanforge/report-data -t 11 -f

    You may create a script in /etc/cron.daily like this:
    ----- ----- ----- ----- ----- ----- ----- ----- -----
    $E -d $LF/report-data -t 11 -f
    $E -d $LF/html-reports -t 11 -f
    ----- ----- ----- ----- ----- ----- ----- ----- -----
  3. Running the script is likely places

    Places we would expect large amounts of files to be saved include:
    1. /home/lanforge/Documents
    2. /home/lanforge/lf_data
    3. /home/lanforge/report-data
    4. /home/lanforge/html-reports
    5. /home/lanforge/Downloads
  4. Survey where your data

    You can use the df command to get an idea where data is accumulating. Example:df -s * | sort -n | tail
     12736    interop-5.4.5.apk 
    22164 btserver
    23500 MonkeyRemote-0.4-shaded.jar
    39500 gua.64
    116536 local
    190444 LANforgeServer-5.4.4
    210004 LANforgeServer-5.4.5
    262628 LANforgeGUI_5.4.4
    267344 backup-lanforge-gui.tar
    269196 LANforgeGUI_5.4.5
  5. Please Avoid...

    Please avoid running the script in the /home/lanforge directory itself. A command like ./check_expired_data.bash -d /home/lanforge -t 10 -f would delete your LANforge Server, LANforge GUI and your saved scenarios.

    Packet Capture Files

    If you are saving PCAP files, please save them in /home/lanforge/Documents or/home/lanforge/report-data. Please do not save them in /home/lanforge. The check_expired_data.bash script should not be run with -d /home/lanforge it is too destructive.

    Also avoid:

    1. /
    2. /boot
    3. /etc
    4. /home
    5. /lib
    6. /opt
    7. /run
    8. /usr
    9. /root
    10. /var/log
    11. /var/cache
    12. /var/spool
    13. /var/www
    14. /var/run
  6. Creating a cronjob

    As the help text indicates, you can copy those lines into a cron job task that can run daily.
    1. sudo -s
    2. cd /etc/cron.daily
    3. nano expired_data.bash
    4. Copy in your script data and adjust:
      $E -d $LF/report-data -t 11 -f
      $E -d $LF/html-reports -t 11 -f
    5. chmod +x expired_data.bash
    6. Check for errors by running it by hand:
    7. ./expired_data.bash

Clustering multiple LANforge systems together

Goal: Cluster multiple LANforge systems together to use while Wifi network testing. Clustering enables multiple LANforges to act as one large LANforge.

Multiple LANforge machines can be used as a group with one manager LANforge.
  1. An unclustered LANforge is both 'Manager' and 'Resource'. In a cluster (with multiple LANforges), there is one LANforge that is a 'Manager' and 'Resource' and there are other LANforges that are only 'Resources'. The LANforges that are only a 'Resource' use the first LANforge as their 'Manager'. There are two ways to cluster. One way is via the command line, second is via the User Interface. This cookbook demonstrates how to cluster via the User Interface. First, configure the first LANforge (which is typically both a 'Resource' and 'Manager')
    1. Open a VNC/RDP window to the LANforge wished to be used as the 'Manager' and 'Resource' of the final cluster. Click on the Configure LANforge icon located on the VNC session desktop. screenshot
    2. Once the 'LANforge Installation and Configuration (as superuser)' window opens, click on the Basic tab. Set the Setup Mode to Both, Resource ID to 1, and pick a realm 1-254 (example below is realm 2). Realm 255 means the LANforge is un-clustered. screenshot
    3. Click on Apply and Exit LANforge Config to save settings.
  2. Next, configure the following LANforges to cluster to the first LANforge. These LANforges will be only Resources.
    1. Open a VNC/RDP window to the LANforge wished to be used as the 'Manager' and 'Resource' of the final cluster. Click on the Configure LANforge icon located on the VNC session desktop. screenshot
    2. Once the 'LANforge Installation and Configuration (as superuser)' window opens, click on the Basic tab. Set the Setup Mode to Resource, Resource ID to 2 or what the next unused Resource number is, and pick the same realm as the manager LANforge (in our example, realm 2). screenshot
    3. Click on the Clustering tab and in the Connect to Manager input box, put in the Manager's IP address followed by a ':4002' screenshot
    4. Click on Apply and Exit LANforge Config to save settings.
  3. Restart LANforge Manager on all LANforges of cluster. The 'Status' tab of 'the Manager' of the clustered systems should show multiple resources now, as shown in the example below. If systems are not clustering and LANforge version build dates are too far apart between systems in cluster, LANforges may need to be upgraded so build version dates are closer to each other. Please contact for assistance. screenshot

Configure a Remote LANforge

Goal: Configure LANforge to be securely accessed via an Internet accessible gateway.

Follow these guidelines to configure a LANforge server so that it is less abusable if accessible via the Internet. Ideally the only method of access is via SSH. Remember that LANforge systems are designed for isolated environments and convenient usability. Never connect a LANforge system directly to the Internet. It is not secure. Requires version 5.4.6
  1. Prepare the Gateway

    The internet gateway would want the LANforge system management address plugged into it. The following steps assume the gateway is configured to provide DHCP on the LAN and the LANforge management port (eth0) is using DHCP. Use the LANforge Configuration tool or lfconfig as necessary.
    1. We do not suggest placing the LANforge in a full DMZ network where all public requests are forwarded to the LANforge. That is not secure.
    2. Just forward the SSH port (22/tcp) to the LANforge
    3. Disable Universal Plug-n-Play (UPnP)
    4. Disable WAN administration ports (those are never secure)
  2. Prepare the LANforge

    We will configure the LANforge server to change the management port and to not manage the default ethernet interface. The server should not accept LANforge protocol commands on every interface, making it much more secure. For this discussion, we will use the lfconfig script because that is always easy to access from an SSH connection. Also, we will assume that the LANforge GUI will NOT run on this machine.
    1. Stop the GUI and disable the autostart GUI feature

      1. killall lfclient.bash
      2. killall java
      3. rm -f /home/lanforge/.config/autostart/LANforge-auto.desktop
    2. Configure LANforge server to use loopback as management port

      1. sudo -s
      2. cd /home/lanforge
      3. ./serverctl.bash stop
      4. ./lfconfig
      5. Typical screen:
        Interfaces: eth0
        Resource interface assignment:
        Resource 1:
        Specified Resource Addresses:
        Key Acceptable Values Value
        log_level [0-65535] 7
        log_dir [directory path] /home/lanforge
        add_resource_addr [host:port] SEE LIST ABOVE
        rem_resource_addr [host:port] SEE LIST ABOVE
        realm [1-255] 255
        resource [1-511] 1
        mgt_dev [ethernet device] eth0
        mode [resource, manager, both] both
        log_file_len [0-2G] 0
        bind_mgt [0-1] 0
        shelf [1-8] 1
        dev_ignore [eth0 eth1 ... ethN]
        first_cli_port [1025-4199] 4001
        connect_mgr [host:port]
        gps_dev [device file] NONE
        max_tx [1-500] 5
        max_send_mmsg_mem [1000-500000] 32000
        max_send_mmsg_pkts [1-1000] 500
        keepalive [1000-500000] 30000
        wl_probe_timer [50-2000] 50
        Other Commands: help, show_all
        If these values are correct, enter "config", otherwise change
        the values by entering the key followed by the new value, for example:
        mode manager
        Your command:
      6. Your command: mgt_dev lo
      7. Your command: bind_mgt 1
      8. Your command: dev_ignore eth0
      9. Your command: show_all
      10. Key               Acceptable Values          Value
        log_level [0-65535] 7
        log_dir [directory path] /home/lanforge
        add_resource_addr [host:port] SEE LIST ABOVE
        rem_resource_addr [host:port] SEE LIST ABOVE
        realm [1-255] 255
        resource [1-511] 1
        mgt_dev [ethernet device] lo
        mode [resource, manager, both] both
        log_file_len [0-2G] 0
        bind_mgt [0-1] 1
        shelf [1-8] 1
        dev_ignore [eth0 eth1 ... ethN] eth0
        first_cli_port [1025-4199] 4001
        connect_mgr [host:port]
        gps_dev [device file] NONE
        max_tx [1-500] 5
        max_send_mmsg_mem [1000-500000] 32000
        max_send_mmsg_pkts [1-1000] 500
        keepalive [1000-500000] 30000
        wl_probe_timer [50-2000] 50
        Other Commands: help, show_all
      11. Your command: config
      12. ./serverctl.bash restart
  3. Other Security Considerations

    The fewer services listening on all ports on the LANforge the safer it will be.
    Check netstat -ntulp to find services listening on address
    You might want to disable or reconfigure services that could reduce your security posture, such as:
    1. nfs-server.service (only useful for NFS testing)
    2. radiusd.service (used in 802.1x roaming testing)
    3. rpc-bind.service (only useful for NFS testing)
    4. rpc-mountd.service (only useful for NFS testing)
    5. rpc-statd.service (only useful for NFS testing)
    6. vncserver@:1.service (if no local GUI needs to run, should only need ssh)
    7. xrdp.service (because it can be logged in multiple times)
  4. Connect via SSH

    SSH not only does port forwarding, but it can compress the data stream between a GUI and a LANforge Server.
    1. Using PuTTY

    2. See other cookbook
    3. Using OpenSSH

    4. OpenSSH is available on Linux, MAC OS X and Windows
      1. The SSH -L option specifies [local-port]:[remote-host]:[remote-port]
      2. ssh -L 4002: -CnNv lanforge@gateway-host
      3. Leave that connection running.
    5. Using public keys

      You can install a public key to your LANforge and use to avoid typing passwords. Those keys usually reside in your $HOME/.ssh directory.
      1. ssh-keygen -t ed25519
      2. ssh-copy-id lanforge@gateway-host
      3. It is possible to specify the ssh key to avoid copying the wrong one
      4. ssh-copy-id -i $HOME/.ssh/id_ed25519 lanforge@gateway-host
      5. ssh -CnNv -i $HOME/.ssh/ed25519 -L 4002: gateway-host
    6. Using Your .ssh/config File

      Edit the hostname and IP configuration for the host:
      Host lanforge-a1
      Hostname gateway-host
      User lanforge
      IdentityFile ~/.ssh/id_ed25519 # needs to match the ssh key you shared with ssh-copy-id
      IdentitiesOnly yes # useful if you have >6 ssh keys
      Compression yes
      LocalForward 8000 # for browsing reports on LF system
      LocalForward 4001 # for CLI telnet scripts
      LocalForward 4002 # for binary GUI protocol
      ssh -vnN lanforge-a1
  5. Connect the LANforge GUI your Forwarded Connection

  6. After starting your SSH connection to gateway-host, start your Local GUI and connect to localhost:4002
    If you cannot connect, you might need to edit your /etc/hosts file.
    It might be listing ::1 localhost or no localhost entry at all.
  7. cat /etc/hosts
    ::1 localhost6.localdomain6 localhost6 lanforge.localnet lanforge.localdomain
    # Loopback entries; do not change.
    # For historical reasons, localhost precedes localhost.localdomain:
    # See hosts(5) for proper format and other examples:
    # foo
    # bar
    ###-LF-HOSTNAME-NEXT-### localhost localhost.localdomain vm-a490 vm-a490-local

Configure NTP Chronyd on Fedora

Goal: configure an NTP time source for a customer Fedora system

Some customer systems are in offline labs that are unable to reach the Internet, and without that connection, NTP will not continue to adjust the system time. Below are examples of how to configure the chrony service to look at the manager system of a LANforge realm to get time updates. The resulting times will be more consistent with respect to the whole realm of machines, but times will still be different than global time sources.


It is possible to configure chronyd on Fedora to look at specific local servers for time synchronization, and to configure a LANforge to be a NTP time server. For more reference, see

In the examples below, we will consider two systems:

Maintenance: Adjusting the time

sudo -s
chronyc tracking    # display the details about how far off the system is from NTP time
chronyc sources     # display the releationship to the sources
chronyc makestep    # force a catch-up to the NTP server
chronyc tracking    # to see the resulting time difference.  

Configure a Server

Use the allow directive to provide access to the NTP protocol from the management network:

hwtimestamp *
local stratum 9

Configure a Client

Edit the /etc/chrony.conf file and add a these lines:

server iburst auto_offline
local stratum 10
hwtimestamp *

Apply Changes

Restart the chronyd service to apply:

systemctl restart chronyd.service

Check journalctl for anything wrong.

All that other stuff in the file

There’s plenty of notes in the chrony.conf file. The two network time source directives of interest are:

pool iburst maxsources 4
server iburst auto_offline

If you are in an offline setting, you might consider commenting out the remote pool/server directives, but the consequence of that is the next time the system is placed on a routable network, it will never try to look for NTP time sources again and hence never attempt to re-set the system hardware clock. It is harmless to leave those directives un-commented.

Upgrading Offline LANforge Systems

Goal: upgrade a LANforge system that does not have access to the Internet.

LANforge systems are often in off-line or isolated test environments where the only updates they get can be brought to them on a laptop that can taken to the isolated network manually. Candelatech provides Bundle upgrades that contain all the files necessary for performing the equivalent of a --do_lanforge upgrade action. It is also possible to create a mirror of the software that LANforge systems can query. Offline bundle files were introduced in 5.4.1. Offline upgrade by listing files from was introduced in 5.3.3.

Proxy from Controller Method

Given a network gateway that allows one-way access to LANforge systems, an outside management laptop can be used to upgrade the offline LANforge systems. There is no need to mirror everything, because your LF systems do not span all combinations. You don’t want to mirror everything. It’s over 13GB. Also, If you do not have ssh-keys installed between bizproxy and the LF systems, this technique will prompt you for passwords!

Mirror Packages Proxy option

If the proxy has a web server URL on the management LAN where LF files can be cached, follow these steps to update the bundles on the proxy and upgrade the LF systems. This option mirrors the LANforge tar archives and not the bundles. For this example the proxy system will have these properties:

  1. On bizproxy, mirror files from to bizproxy. Below something close to the commands you would need to put into a shell script.

  2. Size of the files files you would expect to mirror is about 8GB

  3. mirror.bash:

    cd /var/www/html/lanforge/r$VER
    curl -s -o ${CT}/
    curl -s -o list.html ${CT}/
    perl -ne '/a href="([^"]+)"/ && print "$1\n";' list.html > list.txt
    rm -f list2.txt
    perl -ne '/^((ath|board|ct[56]|firmware|interop-|LANforge-Server-).*)/ && print "$1\n"' list.txt > list2.txt
    perl -ne '/(LANforge-?GUI[-_]5.*)/ && print "$1\n"' list.txt >> list2.txt
    grep "[Lx].*[-]${OSV}" list.txt >> list2.txt
    mapfile -t URLS < list2.txt
    for file in "${URLS[@]}"; do echo "${CT}/${file}" ; done > urls.txt
    wget -i urls.txt
  4. After running mirror.bash, you now have a copy of the LANforge packages you want on bizproxy.

  5. From bizproxy, the below script can use the first argument as the IP of the system to upgrade. web_upgrade.bash:

    if [ -z $LFHOST ]; then echo "Please specify hostname or ip"; exit 1; fi
    # specify a kernel version in parameter 2:
    scp root@${LFHOST}:/root/
    ssh root@${LF_HOST} "chmod +x /root/"
    ssh root@${LF_HOST} "/root/ \
        --lfver $VER --kver $KV \
        --do_lanforge --skip_yum_all --skip_pip --skip_installer_check \
        --download_from $BIZ \
        --tmp_dir /home/lanforge/Downloads"

    Example: ./web_upgrade.bash 6.2.4+

SSH Copy Packages Option

If the LANforge cannot reach the proxy controller because of firewall or routing reasons, the proxy controller can copy the files to the LF system and use a local-only install with the --source_dir option.

  1. Use the above mirror script for mirroring the LANforge packages.

  2. Use a script like the one below to query and copy the correct files to the LF system:

    cd /var/www/html/lanforge/r5.4.6
    if [ -z $LFHOST ]; then echo "Please specify hostname or ip"; exit 1; fi
    # specify a kernel version in parameter 2:
    OSV=$(ssh lanforge@$LFHOST "awk -F\= '/VERSION_ID/{print \$2}' /etc/os-release")
    scp root@${LFHOST}:/root/
    ssh root@${LF_HOST} "chmod +x /root/"
    ssh root@{$LF_HOST} "/root/ --print_only --show_urls \
        --skip_pip --skip_yum_all --do_upgrade \
        --lfver $VER --kver $KV | grep '# http' > /tmp/lf_list.txt"
    scp root@${LF_HOST}:/tmp/lf_list.txt /tmp
    mapfile -t urlz < /tmp/lf_list.txt
    for url in "${urlz[@]}"; do 
        scp $file root@${LFHOST}:/home/lanforge/Downloads/
    scp md5.txt root@${LFHOST}:/home/lanforge/Downloads/
    ssh root@${LFHOST} "/root/ --offline \
        --lfver $VER --kver $KV --do_lanforge \
        --source_dir /home/lanforge/Downloads \
        --tmp_dir /var/tmp --skip_yum_all --skip_pip"

SSH Copy Bundles Option

This option is for mirroring the Bundle files only. This is useful if the default kernel version is acceptable.

  1. On bizproxy, mirror files from to bizproxy. Below something close to the commands you would need to put into a shell script.

    Sizes of the bundle files you would expect to mirror:

    $ ls Bundle*F{27,30,34,36}* | xargs du -shc
    1.7G    Bundle_lfver-5.4.6_kern-5.19.17+_osver-F27-i-27_x64.tar.xz
    1.7G    Bundle_lfver-5.4.6_kern-5.19.17+_osver-F30-i-30_x64.tar.xz
    1.7G    Bundle_lfver-5.4.6_kern-5.19.17+_osver-F34-i-34_x64.tar.xz
    1.7G    Bundle_lfver-5.4.6_kern-5.19.17+_osver-F36-i-36_x64.tar.xz
    6.7G    total
  2. We’ll call this “bundle_mirror.bash”:

    cd /var/www/html/lanforge/r$VER
    curl -s -o ${CT}/
    curl -s -o list.html ${CT}/
    perl -ne '/a href="([^"]+)"/ && print "$1\n";' list.html > list.txt
    perl -ne '/^(Bundle.*?(F(27|3[046])).*)/&& print "/$1\n"' list.txt > urls.txt
    wget -i urls.txt
  3. From bizproxy, the below script can use the first argument as the IP of the system to upgrade. scp_bundle_upgrade.bash:

    cd /var/www/html/lanforge/r5.4.6
    if [ -z $LFHOST ]; then echo "Please specify hostname or ip"; exit 1; fi
    OSV=$(ssh lanforge@$LFHOST "awk -F\= '/VERSION_ID/{print \$2}' /etc/os-release")
    scp $BNAME lanforge@${LFHOST}/home/lanforge/Downloads/
    scp root@${LFHOST}:/root/
    ssh root@${LF_HOST} "chmod +x /root/"
    ssh root@${LF_HOST} "./ --use_bundle /home/lanforge/Downloads/$BNAME"

    Example: ./scp_bundle_upgrade.bash

Bundle method

The bundle upgrade is a standard manner of doing an offline upgrade.



Offline Windows lfserver upgrades will require a place to download the windows lanforge update zip from. The existing offline Bundle_lfver_X tar file does not include these files. Rather this requires the file.

  1. on the Fedora lanforge, configure a test-network port to serve HTTP.

  2. edit the resulting vr_conf/nginx_eth3.conf to add the Downloads directory:

  3. # Remove the first line '# Autogenerated by ...' and edit the file as
    # desired for a custom config file.
    worker_processes        1;
    error_log logs/br1000_error.log;
    pid             /home/lanforge/vr_conf/;
    events {
        worker_connections  1024;
    http {
        include       /usr/local/lanforge/nginx/conf/mime.types;
        default_type  application/octet-stream;
        access_log  logs/br1000_access.log;
        sendfile            on;
        keepalive_timeout  65; 
        server {
            listen bind_dev=br1000;
            server_name  localhost;
            access_log  logs/br1000_host.access.log;
            location / { 
                root   html;
                index  index.html index.htm;
            error_page   500 502 503 504  /50x.html;
            location = /50x.html {
                root   html;
            location /Downloads {
               root   /home/lanforge/;
               autoindex on;

    Notice the:

    1. location /Downloads {
          root   /home/lanforge;
          autoindex on;
    2. and of course: remove the top line of the file

  4. reset the port to make the changes take effect

    1. first, tail the logfile:

      [lanforge@ct523-jedway1 logs]$ pwd
      [lanforge@ct523-jedway1 logs]$ tail -F br1000_error.log 
    2. next down and up the port. A simple port reset does not restart nginx

  5. check on the Windows system to make sure you can browse the url:

  6. Get the correct files into Fedora /home/lanforge/Downloads:

    1. wget

    2. check that you did not create

  7. Download on windows, or use posh wget:

    1. Using Edge: click on the […] dots, select Keep, on next card select Extra Options → Keep

    2. wget -o

  8. Stop LANforge on the windows system

  9. Extract the zip file:

    1. cd %env:PROGRAM<TAB><TAB> tab complete to get to cd 'C:\Program Files (x86)\LANforge-Server\'

    2. Expand-Archive -Path $HOME\Downloads\LANforge* -Dest .

  10. run the upgrade_lfconfig script:

    1. .\upgrade_lfconfig.ps1

    2. click OK

    3. The server will have started

  11. Check the LANforge manager system to check it has re-regeistered

    1. In the Resources tab, you should see the host-name has returned

    2. check the Build Date column to check the version is recent.

Multiplexed REST Access via Nginx Proxy

Goal: Configure an NGINX proxy to allow REST traffic to a variety of isolated LANforge machines

It is possible to configure a Nginx proxy in a manner to allow remote REST clients access to multiple isolated LANforge systems. This leverages the proxy_pass feature in Nginx. There are multiple ways to configure proxy access.

For the example below, we will assume these values:

LANforge GUI HTTP Processing

The HTTP library that the LANforge GUI incorporates is very simple. It is not configured to parse Host: headers. There is no need to rewrite the Host header when proxying to port 8080.

Proxying to Apache on LANforge (mgt_ip, port 80) is different. If you want to proxy requests to a LF Apache instance on port 80, you should incorporate Host header rewriting. (No examples below, sorry.)

Proxy Request Rewriting

Three ways of making proxy requests include:

Port Rewriting

This manner of proxying just translates different server listening ports to the target machines. It is another easy transformation, but it opens up quite a number of high-numbered ports on bizproxy.
Nginx config:

server {
   listen 1910;
   server_name _;
   root /usr/share/nginx/html;

    location / {
       rewrite            /(.*) /$1 break;
       proxy_redirect     off;
       proxy_set_header   Host $host;
       proxy_set_header   X-Real-Ip $remote_addr;
       proxy_set_header   X-Forwarded-For $remote_addr;
server {
   listen 1911;
   server_name _;
   root /usr/share/nginx/html;

    location / {
       rewrite            /(.*) /$1 break;
       proxy_redirect     off;
       proxy_set_header   Host $host;
       proxy_set_header   X-Real-Ip $remote_addr;
       proxy_set_header   X-Forwarded-For $remote_addr;

Use curl to test access:

curl -sqv -H 'Accept: application/html' http://bizproxy:1910/port/1/1/list

Example script usage:

./ --mgr bizproxy --mgr_port 1910 \
    --load BLANK --action overwrite

Hostname Rewriting

It is possible to rewrite hostnames and host headers to isolated LF systems. This is complicated rewrite because the DNS names need to be present at the developer’s workstation. (It is unlikely that the the headers in the HTTP request can be manipulated to add the Host header.) Ideally, the non-isolated LAN DNS can be configured to return the return the IP of when hostnames like are requested.

On the developer workstation, this is possible with extra effort on the user side by manipulating the /etc/hosts file on a workstation:

# etc/hosts    ct523-jedway1

Nginx config:

server {
    listen 80;
    server_name ct523-jedway1;
    root /usr/share/nginx/html;

    location / {
        rewrite            /(.*) /$1 break;
        proxy_redirect     off;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-Ip $remote_addr;
        proxy_set_header   X-Forwarded-For $remote_addr;

Check the URL access using curl:

# check by IP:
$ curl -sqv \
    -H 'Host: ct523-jedway1' \
    -H 'Accept: application/json' \

# check by hostname
$ curl -sqv \
    -H 'Accept: application/json' \

Example script usage:

./ --mgr ct523-jedway1 --mgr_port 80 \
   --load BLANK --action overwrite

Logging HTTP Access

The bizproxy logs should be located in /var/log/nginx. In LF 5.4.6, the GUI can send messages to syslog. Messages from the GUI would look like:

1685573102952:  ip[] sess[] GET url[/port/1/1/list]


URL Rewriting is mentioned here so the reader can understand what not to configure.

URL Rewriting

Below is an example permitting REST access to LF hosts by way of a URL prefix. For example, the URL http://bizproxy/92.11/port/1/1/list becomes the URL . This is not the best kind of proxy rewriting, but it is the easiest. Using a URL prefix is less ideal because it inherently conflicts with the LANforge python libraries provided.
Nginx config:

server {
    listen       80;
    server_name  _;
    root         /usr/share/nginx/html;

    # Load configuration files for the default server block.
    include /etc/nginx/default.d/*.conf;

    location /92.10 {
       rewrite            /92.10/(.*) /$1 break;
       proxy_redirect     off;
       proxy_set_header   Host biz_lflab5_9210;
       proxy_set_header   X-Real-Ip $remote_addr;
       proxy_set_header   X-Forwarded-For $remote_addr;
    location /92.11 {
       rewrite            /92.11/(.*) /$1 break;
       proxy_redirect     off;
       proxy_set_header   Host $host;
       proxy_set_header   X-Real-Ip $remote_addr;
       proxy_set_header   X-Forwarded-For $remote_addr;

Use curl to query the REST endpoint:

$ curl -sqv -H 'Accept: application/json' http://bizproxy/92.10/port/1/1/list

This is not compatible with the py-scripts library.

Candela  Technologies, 2417 Main Street, Suite 201, Ferndale, WA 98248, USA | | +1.360.380.1618
Facebook | LinkedIn | Blog