How to install iperf3 in my NAS?

Applicable Products

• All QNAP NAS models running QTS or QuTS hero system
• QTS 4.3.6 (or later), including QTS 5.x and QTS 6.x
• QuTS hero 4.5.0 (or later), including QuTS hero 5.x and QuTS hero 6.x

Overview

iPerf3 is an open-source network performance testing tool that measures TCP/UDP bandwidth, latency, and packet loss between two devices.

Installing iPerf3 on a QNAP NAS allows the NAS to act directly as a test endpoint (server or client), which is useful in the following scenarios:

• Verify network throughput: Confirm whether the actual transfer
  speed between the NAS and a computer, switch, or other device meets
  expectations (e.g., 1GbE, 10GbE).
• Diagnose network performance issues: When NAS access speed is
  unexpectedly slow, use iPerf3 to determine whether the bottleneck
  is at the network layer or the storage layer.
• Evaluate the impact of network configuration changes: Compare
  actual bandwidth before and after adjusting settings such as MTU,
  Jumbo Frames, port bonding, or VLANs.
• Isolate hardware or cabling issues: Use point-to-point testing
  to verify whether a network adapter, cable, or switch is functioning
  correctly.

iPerf3 is not built into QTS or QuTS hero by default and must be installed separately.

Solution

iPerf3 can be installed on a QNAP NAS in either of two ways: as a container in Container Station, or using an Entware QPKG file.

Method 1: Run iPerf3 in Container Station

1. Open the App Center, then search for and install Container Station.

2. On first launch, complete the setup wizard and specify the storage location for container data.

3. In Container Station, select Create > Create Application, then enter the following Docker Compose configuration:

   services:
     iperf3:
       image: loganmarchione/docker-iperf3
       container_name: iperf3
       restart: unless-stopped
       ports:
         - "5201:5201/tcp"
         - "5201:5201/udp"
   

   Refer to the documentation for the loganmarchione/docker-iperf3 image for its supported environment variables and parameters. To have the NAS act as the iPerf3 client rather than the server, or to use host network mode for more accurate results, adjust the configuration accordingly.

4. Click Validate to verify the correctness of the yaml code.
   

5. Click Create and wait for the image to be pulled and the container to start.

6. Confirm the container status is Running.
   

7. iPerf3 is now ready to use on your NAS.

   If a firewall or security policy blocks port 5201, clients will report a refused connection. Confirm the port is not blocked under Control Panel > System > Security.

Method 2: Install iPerf3 using an Entware QPKG file

1. Download Entware_1.02std.qpkg from QNAP's download portal.

2. Install the QPKG file:

   • Open the App Center
   • Select Install Manually
   • Click Browse and locate the downloaded QPKG file
   • Click Install
     
   • Accept the risk acknowledgment checkbox and confirm installation
   • Verify that Entware-std 1.02 appears in the App Center

3. Access the NAS command line via an SSH connection.

4. Navigate to the Entware installation directory:

   # cd /share/CACHEDEV1_DATA/.qpkg/Entware/bin
   

   The volume name in this path varies by model and storage configuration, and differs on QuTS hero systems. If the directory does not exist, locate it with:

   # ls -d /share/*/.qpkg/Entware/bin
   

5. Execute the package installation command:

   # ./opkg install iperf3
   

6. iPerf3 is now ready to use on your NAS.