dsatest is a Linux user space network testing framework for Ethernet switches driven by the kernel space DSA framework. It provides an extensive list of test cases, a command line to access the test bench and run the tests, as well as a Python API. It supports many Ethernet switch chips and target machines.

Getting started

These instructions will get you a copy of the project up and running on your local test bench.

Prerequisites

The framework depends on python, python-setuptools, and python-paramiko. dsatest might be compatible with your installation of Python 2.7 with python-configparser as additional dependency.

Installing

To get the source code of the dsatest framework, follow these steps:

git clone git@github.com:netdsa/dsatest.git
cd dsatest/

Ensure that the framework is functional by listing the tests and running the sanity tests:

./dsatest -l -f bench.cfg.example
./dsatest --dry-run -t sanity -f bench.cfg.example

Configuring

Configuration files are usually found in the conf/ directory provided with the dsatest package.

One can use out-of-tree configuration files by using the -C or --conf-dir flags from the command line. The specified directory must have the same layout as the default conf/ directory. Files found in this alternate directory will have precedence over the default ones.

All configuration files use the INI format. Three kind of files need to be populated in order to run tests on the bench. From a bottom-up approach:

switch

Describe a switch and how its kernel driver exposes some information. This file can be shared and used in several test benches. They are located in the switch/ configuration directory.

target

Describe the machine being tested, the switches that are on it, and the interfaces that the test bench will be able to use. This file can also be shared. They are located in the target/ configuration directory.

bench

Describe how the host machine and the target machine are connected to one another. This file is specific to each bench.

Switch configuration file

Switch configuration files are located in the switch/ subdirectory of the configuration directory.

Note
 Switch configuration files have no properties for the moment.

Target configuration file

Target configuration files are located in the target/ subdirectory of the configuration directory. They describe the hardware of the machine being tested.

It must have one section per switch chip. Each indexed switch section must describe the switch model and its enabled links.

A target featuring two interconnected switch chips is described as follow:

router.cfg
[switch0] ; (1)
name = "foo-etherswitch" ; (2)
port0 = link0
port1 = link1
port2 = link2
port3 = link3

[switch1]
name = "foo-etherswitch"
port0 = link4
port1 = link5 ; (3)
port2 = link6

  1. Switch section indexed from 0

  2. Refers to a foo-etherswitch.cfg switch configuration file

  3. Local switch port to global link mapping

Bench configuration file

A bench configuration file describes the test bench, i.e. how the controlling machine (aka host), running dsatest, is connected to the target machine.

It must have one section describing the host machine and one section describing the target machine.

The purpose of this configuration file is to describe the names of the host and target interfaces connected on both ends of links.

An optional control key is used to describe how to access a machine in the form of an URI. Several control protocols are available.

A bench running tests on a target machine via SSH is described as follow:

bench.cfg
[host] ; (1)
link0 = eth1
link1 = eth2
link2 = eth3 ; (2)
link3 = eth4

[target] ; (3)
name = router ; (4)
control = "ssh://target" ; (5)
;username = foo
;password = bar ; (6)
link0 = lan0
link1 = lan1
link2 = lan2 ; (7)
link3 = lan3

  1. Host machine section

  2. Interface name of a link on host side

  3. Target machine section

  4. Refers to a router.cfg target configuration file

  5. Control to access the target machine

  6. Control specific keys

  7. Interface name of a link on target side

Local control

Run command on the local machine. No configuration key is necessary. This is the control used by the host machine, which runs the framework.

SSH control

Connects to the target machine via SSH.

This control requires the ssh:// scheme, followed by a hostname and an optional port number. There is no mandatory key. Optional username, password, keyfile and system_host_keys keys can be used.

Here’s a portion of a target section using the SSH control:

control = "ssh://localhost"
username = bob ; (1)
password = Secr3t ; (2)
keyfile = /home/bob/.ssh/id_rsa ; (3)
system_host_keys = /dev/null ; Don't use system host keys (4)

  1. Optional username, defaults to "root"

  2. Optional password, defaults to empty

  3. Optional alternative key file to use

  4. Optional alternative host keys file to use

Telnet control

Connects to the target machine via Telnet.

This control requires the telnet:// scheme, followed by a hostname and an optional port number. There is no mandatory key. Optional username, password, and prompt keys can be used.

Here’s a portion of a target section using the Telnet control:

control = "telnet://localhost"
username = admin ; (1)
prompt = "#" ; (2)

  1. Optional username to use

  2. Optional prompt to use

Note
 Take a look at the example for a complete test bench.

Copy the example bench configuration file and describe your links and how to control your target. You may have to provide configuration files for your target and switch(es) if they don’t exist yet.

cp bench.cfg.example bench.cfg
# edit bench.cfg...

Running the tests

Important
 You need the NET_CAP_ADMIN capability in order to configure network interfaces.

Test cases are usually found in the tests/ directory provided with the dsatest package.

One can use out-of-tree test files by using the -T or --test-dir flags from the command line. The specified directory must have the same layout as the default tests/ directory. Files found in this alternate directory will have precedence over the default ones.

From the command line

By default, the dsatest command runs all the tests found in the test directory. Run all tests whose method names are prefixed with test_port_ping:

./dsatest -t port_ping

For details about command line options, see the help message:

./dsatest -h

From the Python API

Tests are written using unittest, and must respect rules defined by this module. They can access the test bench instance through the following import:

from dsatest.bench import bench

API is self-documented in the sanity.py test file.

Authors

dsatest was written by Damien Riegel and other contributors. It was inspired by dsa-tests, written by Andrew Lunn.

Resources