Setting Up the iperf3 Server
============================

Before running the full certification test or any test run that involves
network tests, you should ensure that your ``iperf3`` Target is properly
configured. To do so, follow these steps:

#. On the ``iperf3`` Target, install the ``certification-tools`` package
   from the certification PPA. (This package should be installed by default
   when you install ``maas-cert-server`` version 0.3.7 or later; but you
   may need to install it manually if you're using another computer as your
   ``iperf3`` Target.)

#. On the ``iperf3`` Target, ensure that jumbo frames are configured on
   high-speed network interfaces (25 Gbps and faster). You can do this
   either temporarily or permanently:

   - To make a temporary change, type ``sudo ip link set ens1f1 mtu 9000``,
     changing ``ens1f1`` to your high-speed network interface's name.

   - With recent versions of Ubuntu, a permanent change is done by editing
     the configuration file in ``/etc/netplan`` (such as
     ``/etc/netplan/01-netcfg.yaml``, although the exact name may differ).
     Locate the section for the high-speed network interface and add the
     line ``mtu: 9000``. The result might look something like this,
     although several options may be different depending on your network
     configuration::

      ens1f1:
        match:
          macaddress: 24:8a:07:a3:18:fc
        addresses: [ 172.24.124.1/22 ]
        dhcp4: false
        mtu: 9000
        optional: true

   - Note that setting jumbo frames is not normally necessary on low-speed
     network interfaces, and in some cases jumbo frames can cause problems.
     Specifically, some EFI-based computers can't PXE-boot from a MAAS
     server's interface that's configured to use jumbo frames, and switches
     that don't support jumbo frames can cause problems, too, as described
     shortly. Thus, you should restrict this procedure to interfaces from
     which servers do *not* PXE-boot, if possible. If this is not possible
     and if you have problems PXE-booting computers, you may need to enable
     jumbo frames manually only when performing network tests that require
     this feature.

   - It's possible to configure the MAAS server to enable jumbo frames
     automatically on all nodes deployed on a particular network. :doc:`../Environment_Setup_Guide/appendix-b-network-test-options` describes how to configure MAAS in this way.

#. If ``iperf3`` is already running on the ``iperf3`` server, kill it.

#. On the ``iperf3`` server, type ``start-iperf3 -a 172.24.124.1 -n 20``,
   changing the IP address to the interface you want to bring up on the
   ``iperf3`` Target system
   and setting the ``-n`` option to the number of ``iperf3``
   instances you want to run. The ``network`` test in Checkbox defaults to
   using one instance for every 10 Gbps of network throughput being tested,
   but it may use up to twice that number if conditions warrant,
   so you'll need at least ``-n 8`` to test a 40 Gbps NIC and ``-n 20`` to
   test a 100 Gbps NIC. You may find you'll need another value, though, as
   described in :doc:`appendix-d-network-performance-tuning`. If in doubt,
   run more ``iperf3`` instances than you
   think you'll need; the cost of running too many instances is very low.
   You can configure ``iperf3`` to start automatically by editing a startup
   script, such as ``/etc/rc.local``. (The generic ``/etc/rc.local``
   startup script is not enabled by default in recent versions of Ubuntu.
   Numerous online tutorials, such as `this blog post
   <https://marsown.com/wordpress/how-to-enable-etc-rc-local-with-systemd-on-ubuntu-20-04/>`_,
   describe how to enable it.)

#. Repeat the preceding step for every other network interface that may be
   receiving ``iperf3`` connections.

#. You may need to enable jumbo frames on any switch(es) between the
   ``iperf3`` Target and the SUT. How to do this varies from one switch to
   another, so you must consult the switch's documentation. If a switch
   drops jumbo-frame traffic, the result can be a complete failure of
   communication between two computers configured to use jumbo frames.

#. If the SUT has high-speed network cards (faster than 10 Gbps), repeat
   steps 1 and 2 on the SUT.

You don't need to run all of these steps prior to each test run. Once an
``iperf3`` Target is properly configured, it should remain configured at
least until it's rebooted; and if you set an MTU of 9000 in the NetPlan
configuration and set the computer to automatically launch ``iperf3`` on
reboot, then everything should come up properly after a reboot.

In some cases, additional network configuration steps may be required to
further optimize performance. :doc:`appendix-d-network-performance-tuning`
describes these steps. If you run your tests and your network ports all
pass, though, there's no need to consult this Appendix.