antler

README

Antler

Antler is an open-source network testing tool intended for congestion control and related work. The name stands for Active Network Tester of Load Et Response. :)

Introduction

Antler grew out of testing needs that arose during work on SCE, and related congestion control projects in the IETF. It can be used to set up and tear down test environments, coordinate traffic flows across multiple nodes, gather data using external tools like tcpdump, and generate reports and plots from the results.

Features

• support for tests using stream-oriented and packet-oriented protocols (for now, TCP and UDP)
• auto-installed test nodes that run either locally or via ssh, and optionally in Linux network namespaces
• configurable hierarchy of "runners", that may execute in serial or parallel across nodes
• runner scheduling with arbitrary timing (e.g. TCP flow introductions on an exponential distribution with lognormal lengths)
• configurable UDP packet release times and lengths, supporting from isochronous to VBR or bursty traffic, or combinations in one flow
• system runner for system commands, e.g. for setup, teardown, data collection, and mid-test config changes
• parallel test execution, with nested serial and parallel runs
• result streaming during test (may be enabled, disabled or configured to deliver only some results, e.g. just logs)
• plots/reports using Go templates, with included templates for time series and FCT plots using Google Charts
• configuration using CUE, to support test parameter combinations, config schema definition, data validation and config reuse

Examples

Example	Plot
fct	fct
ratedrop	timeseries
sceaqm	cake / cnq_cobalt / codel / pfifo / pie / cobalt / deltic
tcpstream	timeseries
vbrudp	timeseries

To run the examples yourself, e.g.:

cd examples/tcpstream
sudo antler run

Root access is required to create network namespaces.

The antler binary must be in your PATH, or the full path must be specified. Typically, you add ~/go/bin to your PATH so you can run binaries installed by Go. Note: if using sudo and the secure_path option is set in /etc/sudoers, either this must be removed, or additional configuration is required.

All configuration is in the .cue file. After running the examples, you'll typically have gob files, pcaps and an HTML plot.

Installation

Using go install

1. Install Go.
2. go install github.com/heistp/antler@latest
3. make (builds node binaries, installs antler command)

Using git clone

1. Install Go.
2. cd
3. mkdir -p go/src/github.com/heistp
4. cd go/src/github.com/heistp
5. git clone https://github.com/heistp/antler
6. cd antler
7. make (builds node binaries, installs antler command)

Documentation

At present, Antler is documented through the examples, and the comments in config.cue. Antler is configured using CUE, so it helps to get familiar with the language at a basic level, though for simple tests it may be sufficient to just follow the examples.

Status

As of version 0.3.0-beta, the node is working, along with some basic tests and visualizations. The Roadmap lists what should be completed before upcoming releases.

Long term, more work is needed on functionality of the tests themselves, stabilizing the config and data formats, and supporting platforms other than Linux.

Roadmap

Version 0.3.0

• record packet replies and calculate RTT for packet flows
• detect lost and late (out-of-order) packets in packet flows, and flag with altered symbology in time series plot
• ChartsTimeSeries: automatically add one or both Y axes based on the data series present in the Test
• add vet command to check CUE syntax
• rename EmitLog reporter to Log, and add sorting by time for saved log files
• test the SSH launcher and add an example of its use
• add sudo support to the SSH launcher, instead of requiring root for netns
• verify CUE disjunctions are used properly for union types
• handle node data properly both with and without node-synchronized time

Future, Maybe

Features

• add an HTML index of tests and results
• auto-detect node platforms
• add report type with standard output for each test:
  • node logs and system information
  • descriptive details for test
  • time series and FCT plots, with navigation instructions
  • tables of standard flow metrics: goodput, FCT, RTT distributions, etc
• add support for sampling Linux socket stats via netlink (like cgmon)
• add support for setting arbitary sockopts
• add configuration to simulate conversational stream protocols
• implement flagForward optimization, and maybe invert it to flagProcess
• protect public servers with three-way handshake for packet protocols and simple authentication for stream protocols
• add compression support for System runner FileData output
• add more plotting templates, e.g. for plotly, Gnuplot and xplot
• implement traffic generators in C, for performance
• write full documentation
• support MacOS
• support FreeBSD

Bugs

• improve poor error messages from CUE for syntax errors under disjunctions
• return errors immediately on failed sets of CCA / sockopts, instead of waiting until the end of the test
• figure out why packets from tcpdump may be lost without a one-second post-test sleep (maybe buffering, but shouldn't SIGINT flush that? is this a result of the network namespaces teardown issue below?)
• network namespaces may be deleted before runners have completed, for example if a middlebox is canceled and terminated before the endpoints have completed- possibly add an additional node state during cancellation to handle this

Architecture

• find a better way than unions to create interface implementations from CUE
• handle timeouts consistently, both for runners and the node control connection
• add antler init command to save config schema and defaults?
• share more CUE code in examples, especially for netns rig setups
• design some way to implement incremental test runs, perhaps using hard links

Thanks

Thanks to sponsors, and Jonathan Morton and Rodney Grimes for advice and patience.

RIPE NCC

Documentation

Index

• Constants
• func Run(cmd Command) error
• type ChartsFCT
• type ChartsTimeSeries
• type Command
• type Config
  • func LoadConfig(cuecfg *load.Config) (cfg *Config, err error)
• type EmitLog
• type ExecuteTemplate
• type FlowSeries
  • func (s *FlowSeries) Compile() (err error)
  • func (s *FlowSeries) Match(flow node.Flow) (matches bool)
• type ID
• type Parallel
• type Report
• type ReportCommand
• type RunCommand
• type SaveFiles
• type Serial
• type Test
• type TestRun

Constants

const DataFile = "data.gob"

DataFile is the fixed name of the gob-encoded data file containing all the results.

const Version = "0.3.0-beta"

Version represents the Antler version.

Functions

func Run

func Run(cmd Command) error

Run runs an Antler Command, e.g. RunCommand and ReportCommand.

Types

type ChartsFCT

type ChartsFCT struct {
	// To lists the names of files to execute the template to. A file of "-"
	// emits to stdout.
	To []string

	// Series matches Flows to series.
	Series []FlowSeries

	// Options is an arbitrary structure of Charts options, with defaults
	// defined in config.cue.
	// https://developers.google.com/chart/interactive/docs/gallery/scatterchart#configuration-options
	Options map[string]interface{}
}

ChartsFCT is a reporter that makes time series plots using Google Charts.

type ChartsTimeSeries

type ChartsTimeSeries struct {
	// FlowLabel sets custom labels for Flows.
	FlowLabel map[node.Flow]string

	// To lists the names of files to execute the template to. A file of "-"
	// emits to stdout.
	To []string

	// Options is an arbitrary structure of Charts options, with defaults
	// defined in config.cue.
	// https://developers.google.com/chart/interactive/docs/gallery/linechart#configuration-options
	Options map[string]interface{}
}

ChartsTimeSeries is a reporter that makes time series plots using Google Charts.

type Command

type Command interface {
	// contains filtered or unexported methods
}

A Command is an Antler command.

type Config

type Config struct {
	// Run is the top-level TestRun instance.
	Run TestRun
}

Config is the Antler configuration, loaded from CUE.

func LoadConfig

func LoadConfig(cuecfg *load.Config) (cfg *Config, err error)

LoadConfig first executes templates in any .ant files to create the corresponding .cue files, then uses the CUE API to load and return the Antler Config.

type EmitLog

type EmitLog struct {
	// To lists the destinations to send output to. "-" sends output to stdout,
	// and everything else sends output to the named file. If To is empty,
	// output is emitted to stdout.
	To []string
}

EmitLog is a reporter that emits LogEntry's to files and/or stdout.

type ExecuteTemplate

type ExecuteTemplate struct {
	// Name is the name of the template.
	Name string

	// From is the names of files to parse the template from
	// (template.ParseFiles).
	From []string

	// Text is the body of the template, to be parsed by Template.Parse.
	Text string

	// To is the name of a file to execute the template to, or "-" for stdout.
	To string
}

ExecuteTemplate is a reporter that executes a Go template and saves the results to a file.

type FlowSeries

type FlowSeries struct {
	Name    string
	Pattern string
	// contains filtered or unexported fields
}

FlowSeries groups flows into series by matching the Flow ID with a Regex.

func (*FlowSeries) Compile

func (s *FlowSeries) Compile() (err error)

Compile compiles Pattern to a Regexp.

func (*FlowSeries) Match

func (s *FlowSeries) Match(flow node.Flow) (matches bool)

Match returns true if Flow matches Regex.

type ID

type ID map[string]string

ID represents a compound Test identifier consisting of key/value pairs.

type Parallel

type Parallel []TestRun

Parallel is a list of TestRun's executed concurrently.

type Report

type Report struct {
	// contains filtered or unexported fields
}

Report represents the report configuration.

type ReportCommand

type ReportCommand struct {
}

ReportCommand runs reports.

type RunCommand

type RunCommand struct {
	// Control is used to send node control signals.
	Control node.Control

	// Force re-runs the test and overwrites any existing data.
	Force bool
}

RunCommand runs tests and reports.

type SaveFiles

type SaveFiles struct {
}

SaveFiles is a reporter that saves FileData.

type Serial

type Serial []TestRun

Serial is a list of TestRun's executed sequentially.

type Test

type Test struct {
	// OutPath is the base path for test output files, relative to the output
	// directory. Paths ending in '/' are a directory, and '/' is appended
	// automatically if the path is a directory. The default is "./".
	OutPath string

	// Run is the top-level Run instance.
	node.Run
}

Test is an Antler test.

type TestRun

type TestRun struct {
	// Test is the Test to run (non-nil on leaf TestRun's).
	Test *Test

	// Report lists Reports to be run on this TestRun and any below it in the
	// TestRun tree.
	Report reports

	// Serial lists TestRun's to be executed sequentially.
	Serial Serial

	// Parallel lists TestRun's to be executed concurrently.
	Parallel Parallel
}

TestRun contains the information needed to orchestrate the execution of Tests and Reports. A TestRun may have a Test, or nested TestRun's listed in the Serial or Parallel fields, which are executed sequentially or concurrently, respectively. TestRun's may thus be arranged in a tree to coordinate the serial and parallel execution of Tests.