iperf3 v3.9 man page 中文译本 

Last Update: 2024-01-09

目录

译者总注

关于此译本

李守中是开源软件理念坚定的支持者,所以译本虽不是软件,但依旧仿照开源软件的协议发布:

如果读者发现作品中有错误的地方,劳请来信指出。任何提高作品质量的建议李守中都将虚心接纳。

原文档来源

本文档根据 iPerf 3.9 manpage (man iperf3) 翻译。

译者的话

对于直译后无法准确描述软件行为的句子,李守中会根据软件行为对这些句子进行意译。

对于必须添加很多内容才能实现意译的句子,李守中会尽量用直译 + 译者注 的方式来翻译。

受限于李守中的中文水平,在对句子进行意译时可能会偏离作者的本意,请读者谨慎参考。


名称

iperf3 - 测试网络吞吐性能。

摘要

iperf3 -s [ options ]

iperf3 -c server [ options ]

描述

iperf3 是一个测试网络吞吐性能的工具。它能测试 TCP, UDP 或 SCTP 流量。要使用 iperf3 用户必须建立一个服务端和一个客户端。

iperf3 可执行文件包含了服务端和客户端的功能。iperf3 服务器可以通过 -s 或者 --server 选项启动,比如:

iperf3 -s

iperf3 --server

请注意,许多 iperf3 的配置选项都有短形式 (-s) 和长形式 (--server)。在这一节中,我们将普遍地使用短形式,除非这个配置只有长形式。

默认情况下,iperf3 服务端监听本机 5201 TCP 端口,使用此端口与客户端建立连接。可以使用 -p 选项自定义服务端监听的端口:

iperf3 -s -p 5002

在服务端进程启动后会等待从客户端 (以客户端模式运行的 iperf3 进程) 发来的连接请求。以客户端模式启动需要用 -c <host> 选项指定,其中 <host> 为客户端要连接到的服务端的地址, <host> 可以是 hostname, IPv4 文本或 IPv6 文本:

iperf3 -c iperf3.example.com
iperf3 -c 192.0.2.1
iperf3 -c 2001:db8::1

如果 iperf3 服务端在启动时指定了非默认的 TCP 端口,那么指定的端口号也需要在客户端启动时显式指定:

iperf3 -c iperf3.example.com -p 5002

服务端和客户端最初建立的 TCP 连接,用于交换测试参数、控制测试的启动和停止、传输测试结果。这个连接有时也被叫做 "control connection"。实际用于测试网络吞吐性能的数据通过单独的 TCP 连接传输;如果使用 UDP 协议测试吞吐性能,则有一个独立的 UDP 数据包流用于传输测试用的数据;如果使用 SCTP 协议测试吞吐性能,则会有独立的 SCTP 连接。具体协议取决于客户端指定的协议。

通常,测试数据会从客户端发往服务端,客户端会测量上行带宽。要测量客户端的下行带宽则可以在客户端启动时指定 -R 选项,即让服务端将测试数据发往客户端。

iperf3 -c iperf3.example.com -p 5202 -R

测试结果在服务端和客户端都会显示。结果同时显示在客户端和服务器上。每个测量间隔至少有一行输出 (默认情况下,测量间隔为 1 秒,但可以通过 -i 选项更改)。每行输出至少包括自测试开始以来的时间、间隔期间传输的数据量以及该间隔期间的平均速率。请注意,每个测量间隔输出的测试结果都是从打印输出的进程的角度计算的 (换句话说,客户端上打印的输出显示的是客户端测量出的数据)。 译者注: 客户端显示的是客户端发出数据的大小和速度等。服务端显示的是服务端收到的数据的大小和速度等。但传输过程中出现丢包和延迟的话,可能让服务端和客户端显示的速率不相等。

测试结束时会打印一组统计数据,尽可能多地显示发送方和接收方都看到的测试摘要,并给相应行打上标记。回想一下,默认情况下,客户端是发送方,服务器是接收方,尽管如上所述,使用 -R 选项将反转发送方和接收方。 译者注: 就是,客户端在执行完测试之后,打印一个客户端的测试摘要,再打印一个服务端的测试摘要。服务端只打印自己的测试摘要,不打印客户端的测试摘要。

通过指定 --get-server-output 选项,可以让客户端在打印完客户端要输出的数据之后,再打印服务端要输出的所有数据。

客户端或服务器都可以在启动时指定 -J 选项让测试结果以 JSON 格式输出,这在与其他程序集成时很有用。因为 JSON 结构的内容只有在测试完成后才能完全知道,所以在测试结束之前不会有 JSON 输出。

iperf3 有非常多的命令行选项可用于设置测试过程的细节。它们在下文 /通用命令行选项/ 部分给出,并在 iperf3 的 /help/ 输出中进行了总结,可以运行 iperf3 -h 查看。

通用命令行选项

-p, --port n

要监听 (客户端要连接) 的服务端端口号。必须在服务端和客户端指定相同的端口。默认端口为 5201。

-f, --format

[kmgtKMGT] 指定速率的显示格式: Kbits / Mbits / Gbits / Tbits / Kbytes / Mbytes / Gbytes / Tbytes。

-i, --interval n

两次吞吐量报告信息输出之间间隔 n 秒。默认值 1s。值 0 表示关闭输出。

-F, --file name

发送 (客户端,发送方) 或接收 (服务端,接收方) 文件,而不仅仅发送 (客户端,发送方) 随机数据或接收后将其丢弃 (服务端,接收方)。此功能用于确定存储子系统是否是文件传输的瓶颈。但 iperf3 不是可靠的文件传输工具。收到的文件的长度、属性以及某些情况下的内容可能与原文件不同。

-A, --affinity n/n,m

设置 CPU 绑定 (仅限 Linux, FreeBSD 和 Windows)。在客户端和服务器上,都可以使用此参数的 n 形式 (n 是 CPU 各个核心的编号) 将 iperf3 进程绑定在 CPU 的某个核心上。此外,在客户端,可以使用 n,m 形式的参数覆盖本次测试中服务端的 CPU 绑定。请注意,使用此功能时,进程将仅使用绑定到自身的单个 CPU 核心,而不是使用 CPU 的多个核心。

-B, --bind host

将 iPerf 进程绑定到与地址 host 关联的特定接口。 译者注: 就是绑定到机器上的某个网卡的接口上。对于客户端来说,这个选项可以指定数据包从哪个网卡接口流出。对于服务端来说,可以指定数据包从哪个网卡接口流入。

-V, --verbose

让输出更详细。

-J, --json

以 JSON 格式输出。

--logfile file

把输出写入到日志文件中。

--forceflush

每隔一段时间强制刷新 output。用于避免发送到管道输出被缓存。

--timestamps[=format]

在每行输出的开头加上时间戳。默认情况下,时间戳的格式为 ctime(1) 输出的格式。或者,可以传递格式规范来定制时间戳,参见 strftime(3)

--d, --debug

输出调试信息。主要在开发 iPerf 的时候用。

-v, --version

显示版本信息,然后停止进程。

-h --help

显示帮助信息,然后停止进程。

服务端命令行选项

-s, --server

以服务端模式启动程序。

-D, --daemon

在后台以守护进程的方式运行。

-I, --pidfile file

将进程 ID 写入到文件中,在程序以守护进程的形式运行时最有用。

-1, --one-off

处理一个客户端的连接之后就结束进程。

--server-bitrate-limit n[KMGT]

在服务端设置限速。如果客户端指定的测试速率大于 n,或者从所有客户端流入数据的总速率大于 n,测试停止。默认值为 0,意味着没有限制。默认情况下,每 5s 计算一次这 5s 内流入数据的速率,这个时间间隔可以通过 / 后跟一个数字来指定。

--rsa-private-key-path file

用于解密客户端身份验证凭据的 RSA (不受密码保护的) 私钥路径 (如果编译的时候加入了 OpenSSL 支持的话)。

--authorized-users-path file

配置文件的路径,文件中包含了被允许执行 iperf 测试的用户的凭证 (如果编译的时候加入了 OpenSSL 支持的话)。该文件是以逗号分隔的用户名和密码哈希列表。有关文件结构的更多信息,请参见示例部分。

客户端命令行选项

-c, --client host

以客户端模式启动,连接到指定的服务端。默认情况下,测试过程中客户端是数据发送方,服务端是数据接收方,使用 -R 选项可以让发送方和接收方角色互换。

--sctp

使用 SCTP 而不是 TCP (只能在 FreeBSD 和 Linux 上用)。

-u, --udp

使用 UDP 而不是 TCP。

--connect-timeout n

设置客户端发起到服务端的 control connection 的超时时间,单位是 ms。默认的值是系统中 TCP 连接的超时时间。将其调小一些可能会加速检测 iperf3 服务端掉线情况。

译者注: control connection 是服务端和客户端连接后的第一个连接,这是个 TCP 连接,用于交换测试参数,控制测试的启动和停止,传输测试结果。

-b, --bitrate n[KMGT]

设定一个目标为 n bits/sec 的速率限制 (默认情况下,UDP 有 1 Mbit/sec 的发送速率限制,TCP / SCTP 无发送速率限制)。如果有多个输入 / 输出流 (-P 选项),限速会被否下应用到所有的流。译者注: m 个限速为 n 的流,速度上限是 m*n。可以在之后加上 / 然后跟一个数字来调用 burst mode 。它将不间断地发送给定数量的数据包,即使传输速率暂时超过了指定的吞吐量限制。译者注: 即使速度超过了限速还是一直传输数据直到占满带宽。将目标限速设为 0 将禁用限速 (对于 UDP 测试特别有用)。该吞吐量限制在 iperf3 内部实现,可用于所有平台。与 --fq-rate 标志进行比较。此选项用于替换 --bandwidth 选项 (该选项现在已被弃用,但仍有效)。 译者注: 简单理解,这个选项设置了一个 pacing 速率 (一个限速)。前面一句话需要结合 --fq-rate 配置项理解。

--pacing-timer n[KMGT]

以毫秒为单位设置每次检查发送的数据量,默认值是 1000ms,也就是 1s。这个选项控制 iperf3 中 -b / --bitrate 选项的 pacing timer。计时器按此参数设置的间隔触发。pacing timer参数的较小值可以平滑 iperf3 发出的流量,但由于更频繁的计时器处理,可能会以性能为代价。

**译者注: 这个选项主要的作用是,尽量减少发送数据间等待的时间。假设带宽 100M,限速 10M,pacing timer 是 1s,机器在 1s 中可以发送 100M 数据出去。有了限速之后 1s 只能发 10M 出去,那么机器会在 1s 开头的 100ms 把数据发完,剩下 900ms 什么都不干。这时候调小 pacing timer 为 1ms,那么每隔 1ms iperf3 都会检查数据发送情况,这时候可能每 1ms 都有 0.1M 数据被发出。**

--fq-rate n[KMGT]

设置用于基于 fair-queueing 的 socket 级别的 pacing 速率,以 bit/s 为单位。这个 pacing 是对其他 pacing 的补充,比如 -b / --bitrate ,并且它们可以同时用在同一个测试中。仅在支持 SO_MAX_PACING_RATE 这个 socket 选项的平台上可用 (当前仅限 Linux)。默认情况下,不开启基于 fair-queueing 的 pacing。

译者注: 简单理解,这个选项也设置了一个 pacing 速率 (一个限速),只不过优先级很低。--fq-rate 和 --bitrate 同时出现但取值不同时,速率限制为较小的那个,并且开启基于 fair-queueing 的 pacing。

--no-fq-socket-pacing

这个选项已经启用并将被移除。它的效果和 --fq-rate=0 相同。

-t, --time n

测试持续的时间,单位是秒。默认 10s。

-n, --bytes n[KMGT]

要传输的数据量。(是 -t 选项的替代选项)

-k, --blockcount n[KMGT]

要传输的数据包的数量。(是 -t 或 -n 选项的替代选项)

-l, --length n[KMGT]

要读取或写入的缓冲区的长度。对于 TCP 测试来说,默认值是 128KB。对于 UDP 测试来说,iperf3 会尝试根据路线上的 MTU 动态地确定一个合理的被发出的数据包的大小,如果无法确定则使用 1460 bytes 作为数据包大小。对于 SCTP 测试来说,默认值是 64KB。

--cport port

将数据流绑定到一个特定的客户端端口上。(仅限 TCP 和 UDP,默认使用随机端口) 译者注: 客户端默认使用随机端口来收发数据。这个选项可以用来指定收发数据的端口。

-P, --parallel n

指定要启动几个客户端数据流。请注意,iperf3 是单线程程序,因此,如果使用了 CPU 绑定,将不会产生更高的吞吐量。 译者注: 启动几个数据流就是启动几个线程,但如果使用 --affinity 绑定了 CPU 小核的话,不管开几个线程,能用的小核就那一个,也就没有什么性能提升了。但是这个选项在一个线程没法占满整个带宽的时候很有用。

-R, --reverse

默认情况下,客户端传输数据到服务端。这个选项可以让服务端传输数据到客户端。

--bidir

测试同时、双向的网络吞吐,客户端和服务器同时发送和接收数据。

-w, --windows n[KMGT]

设置 window size 或者 socket buffer size,这个设置也将发送到服务端,并在服务端使用同样的配置。

-M, --set-mss n

设置 TCP/SCTP mss (最大片段大小) (值为 MTU - 40 bytes)。

译者注: 主机的 MSS 的值是链路层的 MTU 减去 40 个字节 (IP 标头和 TCP 标头各 20 字节,总共为 40 字节),这时 MSS 的值为 1460。有时候还要再减去时间戳要占用的 12 字节,这时 MSS 的值为 1448。

-N, --no-delay

取消 TCP/STCP 的延迟 (set TCP/STCP no delay),关闭 Nagle 的算法。

-4, --version4

只使用 IPv4 地址。

-6, --version6

只是用 IPv6 地址。

-S, --tos n

设置 IP 服务类型。可以使用八进制和十六进制的常用前缀,即 52, 064 和 0x34 是相同的值。 译者注: 详细请查看 IP 协议的 TOS 字段。

--dscp dscp

设置 IP DSCP 位。接受数字和符号值。数值可以用十进制、八进制和十六进制指定 (格式参见 --tos)。 译者注: 详细请查看 IP 协议的 DSCP 部分。

-L, --flowlabel n

设置 IPv6 flow label。目前只支持 Linux。

-X, --xbind name

使用 sctp_bindx(3) 将 SCTP 关联绑定到特定的链接子集。如果指定了此选项,就忽略 --B 选项。通常,在建立关联时,SCTP 将包含本地主机上所有活动连接的协议地址。指定至少一个 -X 将禁用此行为。必须为要包含在关联中的每个链接指定此选项,并且 iperf 服务器和客户端都支持此选项 (客户端通过将第一个 -X 传递给 bind(2) 来支持)。主机名可以作为选项的值,并使用 getaddrinfo(3) 进行解析。如果指定了 -4-6 选项,则不被解析为指定协议族内的地址的 name 值将被忽略。

-nstreams n

设定 SCTP 流的数量。

-Z, --zerocopy

使用 "zero copy" 来发送数据,比如 sendfile(2) ,而不使用 write(2)

-O, --omit n

省略测试的前 n 秒,跳过TCP慢速启动周期。

-T, --title str

在每一行输出之前加上这个字符串。

--extra-data str

指定一个字符串,将其包含在 JSON 输出中。

-C, --congestion algo

设置拥塞控制算法 (仅限 Linux 和 FreeBSD)。旧 --linux-congestion 选项和此选项效果相同,虽然可以使用,但已被废弃。

--get-server-output

从服务端获取输出。输出格式由服务端决定 (特别是,如果使用 --json 选项启动服务器,则输出将采用 json 格式,否则采用人类可读的格式)。如果客户端使用 --json 选项启动,则服务器输出包含在客户端输出的 json 对象中;否则,服务端的输出将在人类可读的客户端输出的后面被输出。

--udp-counters-64bit

在 UDP 测试的数据包中使用 64 位计数器。使用该配置有助于在长时间或高比特率 UDP 测试期间防止计数器溢出。客户端和服务器都需要至少运行 3.1 版,此选项才能工作。在将来的某个时候,它可能会成为默认行为。

--repeating-payload

在负载中使用重复模式,而不是随机字节。iperf2 也使用了相同的负载模式 (ASCII 字符 0-9 按顺序不断重复发送)。这可能有助于测试和展现带硬件压缩功能的网络设备 (包括一些 WiFi 接入点) 中的问题,其中 iperf2 和 iperf3 的性能不同,只是基于负载熵。重新创建可能受有效负载熵(例如,压缩)影响的结果。

译者注: 李守中用 tcpdump 抓了一下使用这个配置项启动的客户端发出去的包 (iperf2 和 iperf3 都抓了)。在 wireshark 里看到,发到服务端的测试数据都是 0-9 的这 10 个数字,而且是 (01234556789){n} 这样式的。要理解第二句,得理解熵 (用于形容系统中的无序程度,熵值越高系统越无序) 的概念,媒体文件熵值高,文本文件熵值低。第二句意思是说,可以使用降低要传输的数据的熵值的方式 (就是让发出去的数据尽量有序) 来测试网络设备的功能是否正常。比如网络设备上硬件级别的数据压缩功能,数据有序程度和压缩效果成正比。先用熵值高的媒体文件测一下,再用熵值低的有序数据测一下,根据压缩效果可以判断硬件有没有问题。

--username username

用于服务端身份验证的用户名 (如果编译时候加入了 OpenSSL 支持的话)。在执行命令的时候会有交互式的密码输入提示。请注意,密码也可以通过环境变量 IPERF3_PASSWORD 来指定。如果有这个环境变量,将不会有交互式密码输入提示。

--rsa-public-key-path file

用于加密加密身份验证凭据的 RSA 公钥文件的路径。(如果编译时候加入了 OpenSSL 支持的话)

例子

认证 (authentication) - RSA 密钥对

iperf3 的认证 (authentication) 特性需要 RSA 公钥对的支持。公钥用于加密包含用户凭据的身份验证令牌,而私钥用于解密身份验证令牌。生成正确密钥对的一组 UNIX / Linux 命令的示例如下:

openssl genrsa -des3 -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
openssl rsa -in private.pem -out private_not_protected.pem -outform PEM

执行完这些命令之后,公钥会被包含在 public.pem 文件中,私钥会被包含在 private_not_protected.pem 文件中。

认证 (authentication) - 配置被授权的用户的配置文件

为了指定被授权的用户的凭据,必须向 iperf3 服务器提供一个纯文本文件。该文件内包含是用户名和相应密码哈希的逗号分隔对的简单列表。密码 hash 是字符串 {$user}$password 的 SHA256 hash 值。该文件还可以包含以 # 字符开头的注释行。下面给出了在 UNIX / Linux 系统上生成密码 hash 的命令示例:

S_USER=mario S_PASSWD=rossi
echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{ print $1 }'

密码文件 (包含上述用户名和密码 hash) 的示例如下所示:

> cat credentials.csv
# file format: username,sha256
mario,bf7a49a846d44b454a5d11e7acfaf13d138bbe0b7483aa3e050879700572709b

译者注: 用户名和密码可以自己随便写,和操作系统无关。定好用户名和密码,写在服务端配置文件里。客户端执行 iperf3 ... --username <username> ... 之后会提示输入密码。

作者

iperf3 的贡献者列表可在以下文档中找到:https://software.es.net/iperf/dev.html#authors.

也可以看这里

libiperf(3), https://software.es.net/iperf