This project contains scripts to remotely control networked devices to run network experiments.
The project essentially consists of two components a generic node and a controller component, which are designed to run on the network devices and a central orchestrator, respectively.
The node is modularized so that it can support generic testbeds with different wireless hardware (e.g., regular Wi-Fi cards, or even WiGig links) and software (e.g., routing protocols, measurement tools such as iperf or ping, and special operating systems such as OpenWrt).
The code requires Python3, and a working SSH connection from the controller to the node devices.
We do not take any responsibility of what could happen to your devices by running our commands. Some configurations are known to cause damage to your hardware. It is your responsibility to get familiar with your devices and judge the risks of running TPy.
In the project root directory, simply run
makeThis will build and package the node and install the controller as a Python package. The installable node package is put in the controller package as a resource, so that the controller can deploy (see below) the package on the devices.
For a minimal working example, we need to configure (a) the controller as well as (b) the nodes, (c) start the node instances, (d) connect the controller to the nodes, and finally (e) start interacting with them.
Create a device configuration that represents your testbed (see default-devices.conf).
The most basic configuration file consists of a node name (section title) and a host:port pair under which the node will be reachable. Example:
[DEFAULT] # Default settings for all nodes, can be overridden in node-specific section
port = 42337 # Listening port of the nodes
[NODE1] # the 'name' of the first node
host = 10.0.0.1 # the node's external IP address
[NODE2] # the 'name' of the second node
host = hostname2.example.org # can also be a resolvable DNS name
Each node instance will start with its own configuration.
This is how a sample node.conf file could look like:
[TPyNode] # Section for the generic node component
logfile = /var/log/tpynode.log # Path to the log file
pidfile = /var/run/tpynode.pid # Path to the pid file
host = 0.0.0.0 # Listening interface, if set to '0.0.0.0' will listen on all network interfaces
port = 42337 # Listening port
[Ping] # a module without any configuration
module = Ping # if module 'name' is the same, this is redundant
[AdHoc1] # control an ad hoc Wi-Fi interface
module = AdHocInterface # module 'name'
interface = wlp1s0 # name of the Wi-Fi interface
ipaddress = 10.0.0.1 # IP address of the interface
channel = 1 # channel of the ad hoc network
bssid = c0:ff:ee:c0:ff:ee # fixed BSSID
ssid = erlab # SSID of the network
[AdHoc2] # a second ad hoc interface
module = AdHocInterface # module 'name'
interface = wlp5s0 # name of the Wi-Fi interface
...
Note that modules need to be explicitly configured in the node.conf.
If the configuration file is empty, no modules will be available.
The controller installs with a command line tool that allows for deploying and (re)starting the Python node instance.
tpy deploy -d devices.conf
tpy restart -d devices.confIf you are developing new modules, simply prepend a make to the above two commands.
To establish a connection from Python, run
import tpycontrol as tpy
# read the device configuration
devices = tpy.Devices('devices.conf')
# connect to the devices and initialize the controller
tc = tpy.TPyControl(devices)After initializing the controller, we can start interacting with the remote nodes. Example:
# start ad hoc interface on all nodes
for n in tc.nodes.values():
# the exported modules (e.g., AdHoc1) are accessible via properties of the remote node instance
n.AdHoc1.up()
# Access a single node
tc.node('NODE2').Ping.ping('10.0.0.1')controller/the controller componenttpycontrol/the Python codeutils/utilities that facilitiate common interaction tasks with the nodescli.pycommand line wrapper fordeploy.pydeploy.pyscripts to deploy and restart nodes via SSHdevices.pyparses adevices.conftpycontrol.pythe controllertpyremotemodule.pyproxy to a node's remote moduletpyremotenode.pyproxy to a remote node that has remote modules
node/the node componenttpynode/the Python codedata/arbitrary files that will be installed with the node componentsample.confan exemplary node configuration file
modules/specific functionality that the node will be able to provide__init.py__exports all modules (need to add new modules here!)abstractmodule.pythe superclass of all modulesping.pya wrapper for thepingtool- ...
daemon.pyrunstpynode.pyas a daemontpynode.pythe node implementation
default-devices.confan example device configurationMakefileto build/package/(un)install/... this project
This software has been released as part of Talon Tools: The Framework for Practical IEEE 802.11ad Research. Any use of it, which results in an academic publication or other publication which includes a bibliography is encouraged to appreciate this work and include a citation the Talon Tools project and any of our papers. You can find more information on the project page.
- Daniel Steinmetzer, Milan Stute, and Matthias Hollick. TPy: A Lightweight Framework for Agile Distributed Network Experiments. 12th International Workshop on Wireless Network Testbeds, Experimental evaluation & CHaracterization (WiNTECH ’18), October 2018, New Delhi, India.
Any use of the Software which results in an academic publication or other publication which includes a bibliography must include citations to our project. The project should be cited with our paper as follows:
@inproceedings{Steinmetzer2018,
author = {Steinmetzer, Daniel and Stute, Milan and Hollick, Matthias},
title = {{TPy: A Lightweight Framework for Agile Distributed Network Experiments}},
booktitle = {12th International Workshop on Wireless Network Testbeds, Experimental evaluation {\&} CHaracterization (WiNTECH '18)},
month = {10},
year = {2018}
publisher = {ACM},
address = {New Delhi, India},
}
We want to learn how people use this software and what aspects we might improve. Please report any issues or comments using the bug-tracker and do not hesitate to approach us via e-mail.
- Daniel Steinmetzer <dsteinmetzer@seemoo.tu-darmstadt.de>
- Milan Stute <mstute@seemoo.tu-darmstadt.de>
