Appendix D - Network Performance Tuning
=======================================

Network devices can pose problems for testing because of improper
configuration. A few steps can help work around such problems. In
particular, care must be paid to the configuration of high-speed network
devices. In some rare cases, disabling Energy Efficient Ethernet settings
may have beneficial effects, too.

Improving High-Speed Network Performance
----------------------------------------

Ubuntu's default network configuration works fine for most 1 Gbps and 10
Gbps network devices; however, most servers require a little tweaking of
settings to perform adequately at higher speeds. The ``iperf3`` Target
setup procedure described earlier, in :doc:`setup-iperf3-server`,
configures most of the relevant options; however, in some cases you may
need to further tweak the network settings.

The procedure outlined in :doc:`setup-iperf3-server` configures
the ``iperf3`` Target system to run multiple ``iperf3`` instances.
The reason for doing this is that a single
``iperf3`` thread tends to max out the CPU at some level of throughput --
somewhere between 10 Gbps and 20 Gbps using the servers in our test lab. This
value may be different on other hardware, though. If either an ``iperf3``
server or a SUT has less-powerful CPUs, more ``iperf3`` instances may be
required; and fewer may be optimal if a CPU is more powerful. If you
suspect your network tests are failing for this reason, you can adjust the
``-n`` value in your ``start-iperf3`` command and then run the ``network``
script manually on the SUT, specifying the number of ``iperf3`` instances
it launches via the ``--num-threads`` option, as in::

 sudo /usr/lib/checkbox-provider-base/bin/network.py test -i ens1f1 \
  -t iperf --iperf3 --scan-timeout 3600 --fail-threshold 80 \
  --cpu-load-fail-threshold 90 --runtime 900 --num_runs 4 --num-threads 20 \
  --target 172.24.124.1

This example sets the number of ``iperf3`` instances to 20. You must adjust
the ``-i`` option for the SUT's interface and the ``--target`` value to
point to the ``iperf3`` Target. Of course, the ``iperf3`` Target must also
be running at least the specified number of instances. If this procedure
produces acceptable results, you will need to append the *exact* command
you used and the output of the run to the test result submission in a note.

If you can't get adequate performance by setting jumbo frames and using
multiple ``iperf3`` instances, you may need to tweak additional network
settings. This can be done with the ``optimize-network`` script, which is
provided by the ``certification-tools`` package. This script takes the name
of the network interface as a required argument, using ``-i`` or
``--interfaces``, as in::

 sudo optimize-network -i ens1f1

You may need to run this script on the ``iperf3`` Target, on the SUT, or
both. Be sure you do *not* reboot between running the script and running
your network tests, since the configuration changes will not survive a
reboot.

In extreme cases, additional configuration tweaks may be required. The full
procedure is documented at
https://certification.canonical.com/cert-notes/network-tuning/.

Disabling Energy Efficient Ethernet Settings
--------------------------------------------

The Energy Efficient Ethernet (EEE; sometimes also called Green Ethernet)
option is intended to save power in various ways. This feature can be
present on network devices of any speed. Usually, it works fine; however,
in some rare cases, enabling EEE can cause dropped packets and other
problems. You can check a network device's EEE settings with the following
command (adjusting the network device name as appropriate)::

  ethtool --show-eee eno1
  EEE settings for eno1:
          EEE status: enabled - active
          Tx LPI: disabled
          Supported EEE link modes:  100baseT/Full
                                     1000baseT/Full
          Advertised EEE link modes:  100baseT/Full
                                      1000baseT/Full
          Link partner advertised EEE link modes:  100baseT/Full
                                                   1000baseT/Full


This example shows that EEE is enabled and active on ``eno1``, as shown on
the second line of output. Other possible configurations include enabled
but inactive (which happens when Ubuntu has enabled the feature but the
switch doesn't support it); disabled (when it's disabled on the SUT); and
unsupported (when the device doesn't support EEE).

If you suspect that EEE is causing network test failures, you should first
check to be sure it's enabled and active. If so, you can disable it with
the following command (adjusting the device name, of course)::

  sudo ethtool --set-eee eno1 eee off

If it's successful, the command will produce no output. You can verify its
success by re-issuing the ``ethtool --show-eee eno1`` command.

Problems caused by EEE are extremely rare, so it's unlikely you'll need to
resort to these procedures.