Configuring Iperf3 Check

1. Make Sure Iperf3 is Installed on the Device 

Register your device to OpenWISP and make sure the iperf3 openwrt package is installed on the device, e.g.:

opkg install iperf3  # if using without authentication
opkg install iperf3-ssl  # if using with authentication (read below for more info)

2. Ensure SSH Access from OpenWISP is Enabled on your Devices 

Follow the steps in "Configuring Push Operations" section of the documentation to allow SSH access to you device from OpenWISP.

Important

Make sure device connection is enabled & working with right update strategy i.e. OpenWrt SSH.

Enable ssh access from openwisp to device

3. Set Up and Configure Iperf3 Server Settings 

Note

If you're unsure about what "Django settings" are, you can refer to How to Edit Django Settings in OpenWISP for guidance.

After having deployed your Iperf3 servers, you need to configure the iperf3 settings on the Django side of OpenWISP, see the test project settings for reference.

The host can be specified by hostname, IPv4 literal, or IPv6 literal. Example:

OPENWISP_MONITORING_IPERF3_CHECK_CONFIG = {
    # 'org_pk' : {'host' : [], 'client_options' : {}}
    "a9734710-db30-46b0-a2fc-01f01046fe4f": {
        # Some public iperf3 servers
        # https://iperf.fr/iperf-servers.php#public-servers
        "host": ["iperf3.openwisp.io", "2001:db8::1", "192.168.5.2"],
        "client_options": {
            "port": 5209,
            "udp": {"bitrate": "30M"},
            "tcp": {"bitrate": "0"},
        },
    },
    # another org
    "b9734710-db30-46b0-a2fc-01f01046fe4f": {
        # available iperf3 servers
        "host": ["iperf3.openwisp2.io", "192.168.5.3"],
        "client_options": {
            "port": 5207,
            "udp": {"bitrate": "50M"},
            "tcp": {"bitrate": "20M"},
        },
    },
}

Note

If an organization has more than one iperf3 server configured, then it enables the iperf3 checks to run concurrently on different devices. If all of the available servers are busy, then it will add the check back in the queue.

The celery-beat configuration for the iperf3 check needs to be added too:

from celery.schedules import crontab

# Celery TIME_ZONE should be equal to Django TIME_ZONE
# In order to schedule run_iperf3_checks on the correct time intervals
CELERY_TIMEZONE = TIME_ZONE
CELERY_BEAT_SCHEDULE.update(
    {
        # Other celery beat configurations
        # Celery beat configuration for iperf3 check
        "run_iperf3_checks": {
            "task": "openwisp_monitoring.check.tasks.run_checks",
            # https://docs.celeryq.dev/en/latest/userguide/periodic-tasks.html#crontab-schedules
            # Executes check every 5 mins from 00:00 AM to 6:00 AM (night)
            "schedule": crontab(minute="*/5", hour="0-6"),
            # Iperf3 check path
            "args": (["openwisp_monitoring.check.classes.Iperf3"],),
            "relative": True,
        }
    }
)

Once the changes are saved, you will need to restart all the processes.

Note

We recommended to configure this check to run in non peak traffic times to not interfere with standard traffic.

4. Run the Check 

This should happen automatically if you have celery-beat correctly configured and running in the background. For testing purposes, you can run this check manually using the run_checks command.

After that, you should see the iperf3 network measurements charts.

Iperf3 Check Parameters 

Currently, iperf3 check supports the following parameters:

Parameter	Type	Default Value
`host`	`list`	`[]`
`username`	`str`	`''`
`password`	`str`	`''`
`rsa_public_key`	`str`	`''`
`client_options`	`dict`	Refer the Iperf3 Client Options table below for available parameters

Iperf3 Client Options 

Parameters	Type	Default Value
`port`	`int`	`5201`
`time`	`int`	`10`
`bytes`	`str`	`''`
`blockcount`	`str`	`''`
`window`	`str`	`0`
`parallel`	`int`	`1`
`reverse`	`bool`	`False`
`bidirectional`	`bool`	`False`
`connect_timeout`	`int`	`1000`
`tcp`	`dict`	Refer the Iperf3 Client's TCP Options table below for available parameters
`udp`	`dict`	Refer the Iperf3 Client's UDP Options table below for available parameters

Iperf3 Client's TCP Options

Parameters	Type	Default Value
`bitrate`	`str`	`0`
`length`	`str`	`128K`

Iperf3 Client's UDP Options

Parameters	Type	Default Value
`bitrate`	`str`	`30M`
`length`	`str`	`0`

To learn how to use these parameters, please see the iperf3 check configuration example.

Visit the official documentation to learn more about the iperf3 parameters.

Iperf3 Authentication 

By default iperf3 check runs without any kind of authentication, in this section we will explain how to configure RSA authentication between the client and the server to restrict connections to authenticated clients.

Server Side 

1. Generate RSA Key Pair

openssl genrsa -des3 -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public_key.pem
openssl rsa -in private.pem -out private_key.pem -outform PEM

After running the commands mentioned above, the public key will be stored in public_key.pem which will be used in rsa_public_key parameter in OPENWISP_MONITORING_IPERF3_CHECK_CONFIG and the private key will be contained in the file private_key.pem which will be used with --rsa-private-key-path command option when starting the iperf3 server.

2. Create User Credentials

USER=iperfuser PASSWD=iperfpass
echo -n "{$USER}$PASSWD" | sha256sum | awk '{ print $1 }'
----
ee17a7f98cc87a6424fb52682396b2b6c058e9ab70e946188faa0714905771d7 #This is the hash of "iperfuser"

Add the above hash with username in credentials.csv

# file format: username,sha256
iperfuser,ee17a7f98cc87a6424fb52682396b2b6c058e9ab70e946188faa0714905771d7

3. Now Start the Iperf3 Server with Authentication Options

iperf3 -s --rsa-private-key-path ./private_key.pem --authorized-users-path ./credentials.csv

Client Side (OpenWrt Device)

1. Install iperf3-ssl

Install the iperf3-ssl openwrt package instead of the normal iperf3 openwrt package because the latter comes without support for authentication.

You may also check your installed iperf3 openwrt package features:

root@vm-openwrt:- iperf3 -v
iperf 3.7 (cJSON 1.5.2)
Linux vm-openwrt 4.14.171 #0 SMP Thu Feb 27 21:05:12 2020 x86_64
Optional features available: CPU affinity setting, IPv6 flow label, TCP congestion algorithm setting,
sendfile / zerocopy, socket pacing, authentication # contains 'authentication'

2. Configure Iperf3 Check Authentication Parameters

Now, add the following iperf3 authentication parameters to OPENWISP_MONITORING_IPERF3_CHECK_CONFIG in the Django settings:

OPENWISP_MONITORING_IPERF3_CHECK_CONFIG = {
    "a9734710-db30-46b0-a2fc-01f01046fe4f": {
        "host": [
            "iperf1.openwisp.io",
            "iperf2.openwisp.io",
            "192.168.5.2",
        ],
        # All three parameters (username, password, rsa_publc_key)
        # are required for iperf3 authentication
        "username": "iperfuser",
        "password": "iperfpass",
        # Add RSA public key without any headers
        # ie. -----BEGIN PUBLIC KEY-----, -----BEGIN END KEY-----
        "rsa_public_key": (
            """
            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwuEm+iYrfSWJOupy6X3N
            dxZvUCxvmoL3uoGAs0O0Y32unUQrwcTIxudy38JSuCccD+k2Rf8S4WuZSiTxaoea
            6Du99YQGVZeY67uJ21SWFqWU+w6ONUj3TrNNWoICN7BXGLE2BbSBz9YaXefE3aqw
            GhEjQz364Itwm425vHn2MntSp0weWb4hUCjQUyyooRXPrFUGBOuY+VvAvMyAG4Uk
            msapnWnBSxXt7Tbb++A5XbOMdM2mwNYDEtkD5ksC/x3EVBrI9FvENsH9+u/8J9Mf
            2oPl4MnlCMY86MQypkeUn7eVWfDnseNky7TyC0/IgCXve/iaydCCFdkjyo1MTAA4
            BQIDAQAB
            """
        ),
        "client_options": {
            "port": 5209,
            "udp": {"bitrate": "20M"},
            "tcp": {"bitrate": "0"},
        },
    }
}

Configuring Iperf3 Check

Iperf3 Client's TCP Options

Iperf3 Client's UDP Options

1. Generate RSA Key Pair

2. Create User Credentials

3. Now Start the Iperf3 Server with Authentication Options

1. Install iperf3-ssl

2. Configure Iperf3 Check Authentication Parameters

Version