Iperf3 Sensor


The iperf3 sensor component allows you to measure network bandwidth performance against a private or public Iperf3 server.

Enabling this component will automatically create the Iperf3 sensors for the monitored conditions (below). By default, it will run every hour. The user can change the update frequency in the config by defining the scan_interval for a Iperf3 test to run.

Setup

This component requires the iperf3 command to be installed on your OS. Please, refer to the official Iperf3 documentation for installation instructions.

Configuration

To add the iperf3 sensor to your installation, add the following to your configuration.yaml file:

Once per hour, on the hour (default):

# Example configuration.yaml entry
iperf3:
  hosts:
    - host: iperf.he.net

Configuration Variables

monitored_conditions

(list)(Optional)Sensors to display in the frontend.

download

The download speed (Mbit/s).

upload

The upload speed (Mbit/s).

hosts

(list)(Required)A list of Iperf3 servers to perform the test against.

scan_interval

(time)(Optional)Minimum time interval between updates. Supported formats: scan_interval: 'HH:MM:SS', scan_interval: 'HH:MM' and Time period dictionary (see example below).

Default value: 60 minutes

manual

(boolean)(Optional)true or false to turn manual mode on or off. Manual mode will disable scheduled tests.

Default value: false

Configuration variables (host):

Configuration Variables

host

(string)(Required)Server name/IP address running Iperf3 to test against.

port

(integer)(Optional)Port that Iperf3 is running on.

Default value: 5201

duration

(integer)(Optional)Specify the test duration in seconds. Default is 10 and the valid range is from 5 to 10.

Default value: 10

parallel

(integer)Specify the number of concurrent streams to connect to the server. Default is 1 and the valid range is from 1 to 20.

Default value: 1

protocol

(string)(Optional)Specify the protocol to be used on the test. Default is TCP and the valid values are TCP or UDP. If your Iperf3 server is located in the Internet, consider to use TCP instead of UDP. If the protocol is set to use UDP, the sensor may not get updated due to package retransmission issues due to its nature.

Default value: tcp

Time period dictionary example

scan_interval:
  # At least one of these must be specified:
  days: 0
  hours: 0
  minutes: 3
  seconds: 30
  milliseconds: 0

You can find a list of public Iperf3 servers here. You can also start your own Iperf3 server using the mlabbe/iperf3’s docker image or just refer to your iperf3 command’s man page.

The frequency when the test will be automatically triggered can be adjusted by setting the value scan_interval in seconds.

Parallel streams can help in some situations. As TCP attempts to be fair and conservative, you may consider increasing the parallel attribute. Use this value with careful and refer to Iperf3 man page for more information.

You can use the service sensor.iperf3_update to trigger a manual speed test for all sensors. Iperf3 has its own service call that allow to perform a speed test on a particular entity.

Service

Once loaded, the iperf3 component will expose a service (iperf3.speedtest) that can be called to run a speed test on demand. This can be useful if you have enabled manual mode.

Service data attribute Description
host String that point at a configured host from configuration.yaml. Otherwise, tests will be run against all configured hosts.

Example Service data:

{"host": "192.168.0.121"}

Notes

  • When running on Raspberry Pi, just note that the maximum speed is limited by its 100 Mbit/s LAN adapter.