# Flent: The FLExible Network Tester

## Introduction

Flent is a wrapper around netperf and similar tools to run predefined tests and aggregate and plot the results. It defines several tests that can be run against one or more hosts, primarily targeted at testing for the presence of bufferbloat under various conditions.

The aggregated data is saved in (gzipped) JSON format for later processing and/or import into other tools. The JSON format is documented below.

Apart from the JSON format, the data can be output as csv values, emacs org mode tables or plots. Each test can specify several different plots, including time-series plots of the values against each other, as well as CDF plots of (e.g.) ping times.

Plots can be output to the formats supported by matplotlib by specifying the output filename with `-o` output.{png,ps,pdf,svg}. If no output file is specified, the plot is displayed using matplotlib’s interactive plot browser, which also allows saving of the output (in .png format).

## Requirements

Flent runs on Python, versions 2.7+ and 3.3+. Plotting requires a functional `matplotlib` installation (but everything else can run without `matplotlib`). For the interactive plot viewer, a graphical display (and suitably configured `matplotlib`) is required.

Most tests employ the netperf benchmarking tool to run the tests. Version 2.6 or higher is required, and netperf must be compiled with the --enable-demo option passed to ./configure. Some tests use iperf in addition to, or instead of netperf. Both tools must be available in the `PATH`.

For ICMP ping measurements, the version of ping employed must support output timestamping (the -D parameter to GNU ping). This is not supported by the BSD and OSX versions of ping. As an alternative to the regular ping command, the fping utility (see http://fping.org) can be employed. In that case fping must be version 3.5 or greater. Flent will attempt to detect the presence of fping in the `PATH` and check for support for the -D parameter. If this check is successful, fping will be employed for ping data, otherwise the system ping will be used.

The irtt tool is highly recommended for UDP measurements. See https://github.com/peteheist/irtt. Flent will automatically detect if irtt is available in the `PATH` and use it if it is detected. Note that the server component of irtt needs to be running on the target host(s) as well.

## Installing Flent

Installing Flent can be done in several ways, depending on your operating system:

- Arch Linux:

  Install Flent from the AUR.

- Debian and Ubuntu:

  >     apt install flent

- Fedora:

  >     dnf install flent

- Gentoo: (supported in pkalin overlay)

  >     eselect repository enable pkalin && eix-sync
  >     emerge net-analyzer/flent

- Nix:

  Flent is available in nixpkgs through the flent attribute.

- Ubuntu pre-18.04:

  Add the tohojo/flent PPA.

- Other Linux:

  Install from the Python Package Index:

  >     pip install flent

- FreeBSD:

  Install the package

  >     pkg install flent

  Or install the port

  >     cd /usr/ports/net/flent && make install

- macOS:

  Homebrew and Python 3 must be installed (Python 3 can be installed using Homebrew)

  Install the patched netperf package

  >     brew tap kris-anderson/netperf
  >     brew install netperf-enable-demo

  Install other dependencies

  >     brew install fping
  >     pip3 install matplotlib --user

  Install Flent using pip

  >     pip3 install flent --user

  Optional (install this if you want to use flent-gui)

  >     pip3 install pyqt5 qtpy --user

## Quick start

You must run netperf on two computers - a server and a client.

1. Server (Computer 1): Netperf needs to be started in “server mode” to listen for commands from the Client. To do this, install netperf on the Server computer, then enter:

   `netserver &`

   Note: Instead of installing netperf on a local server, you may substitute the netserver that is running on netperf.bufferbloat.net by using `-H netperf.bufferbloat.net` in the commands below.

   List of public hosts you can test against:

   - netperf.bufferbloat.net (also called netperf-east.bufferbloat.net)

   - netperf-west.bufferbloat.net

   - netperf-eu.bufferbloat.net

2. Client (Computer 2): Install netperf, then install flent on your Client computer. When you invoke flent on the Client, it will connect to the specified netserver (`-H`) and carry out the measurements. Here are some useful commands:

   - RRUL: Create the standard graphic image used by the Bufferbloat project to show the down/upload speeds plus latency in three separate charts:

         flent rrul -p all_scaled -l 60 -H address-of-netserver -t text-to-be-included-in-plot -o filename.png

   - CDF: A Cumulative Distribution Function plot showing the probability that ping times will be below a bound:

         flent rrul -p ping_cdf -l 60 -H address-of-netserver -t text-to-be-included-in-plot -o filename.png

   - TCP Upload: Displays TCP upload speed and latency in two charts:

         flent tcp_upload -p totals -l 60 -H address-of-netserver -t text-to-be-included-in-plot -o filename.png

   - TCP Download: Displays TCP download speeds and latency in two charts:

         flent tcp_download -p totals -l 60 -H address-of-netserver -t text-to-be-included-in-plot -o filename.png

The output of each of these commands is a graphic (PNG) image along with a data file in the current working directory that can be used to re-create the plot, either from the command line (see Running Flent), or by loading them into the GUI. Run flent-gui to start the GUI.