# iperf **Repository Path**: mirrors_cloudharmony/iperf ## Basic Information - **Project Name**: iperf - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-01-12 - **Last Updated**: 2026-05-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README Iperf Benchmark This repository provides an execution wrapper for the Iperf network benchmark utilities. NOTE: When cloning this repository, please use the --recurse-submodules option to also pull the https://github.com/cloudharmony/benchmark submodule. RUNTIME PARAMETERS The following runtime parameters and environment metadata may be specified (using run.sh arguments): * collectd_rrd If set, collectd rrd stats will be captured from --collectd_rrd_dir. To do so, when testing starts, existing directories in --collectd_rrd_dir will be renamed to .bak, and upon test completion any directories not ending in .bak will be zipped and saved along with other test artifacts (as collectd-rrd.zip). User MUST have sudo privileges to use this option * collectd_rrd_dir Location where collectd rrd files are stored - default is /var/lib/collectd/rrd * drop_final If set, this number of final bandwidth/jitter/loss measurements will be removed from each set of results * font_size The base font size pt to use in reports and graphs. All text will be relative to this size (i.e. smaller, larger). Default is 9. Graphs use this value + 4 (i.e. default 13). Open Sans is included with this software. To change this, simply replace the reports/font.ttf file with your desired font * ignore_uplink If set, uplink results will be ignored. May be used in conjunction with the --iperf_reverse flag and Iperf version 1-2 to ignore the initial client to server (uplink) test results * iperf_bandwidth Set target bandwidth to n bits/sec (default 1 Mb/s for UDP, unlimited for TCP). If there are multiple streams (--iperf_parallel), the bandwidth limit is applied separately to each stream. You can also add a '/' and a number to the bandwidth specifier. This is called "burst mode". It will send the given number of packets without pausing, even if that temporarily exceeds the specified bandwidth limit. Setting the target bandwidth to 0 will disable bandwidth limits (particularly useful for UDP tests). Value may be a numeric value (bits), or numeric value followed by K (kilobits) or M (megabits). Optionally, this parameter may designate a percentage of bandwidth achieved during prior TCP Iperf testing for a given server. To designate such, set this parameter is a numeric value followed by % (e.g --iperf_bandwidth 80%). To use this method of designating bandwidth, the --tcp_bw_file parameter must be used during a prior Iperf TCP test for the same servers. If multiple TCP result metrics exist in --tcp_bw_file for a given server (e.g. uplink and downlink) downlink metrics will be used (if present), otherwise, uplink. If multiple metrics exist of those types, the mean of all will be calculated and used. A third option is to specific both percentage based and fixed bandwidth parameters each separated by a / (percentage first). If this format is used, the fixed value will be used IF a bandwidth metric is not present in --tcp_bw_file for a given server (e.g. --iperf_bandwidth "25%/100M") * iperf_interval The frequency (seconds) to take bandwidth measurements - default is 1 * iperf_len The length of buffers to read or write. Iperf works by writing an array of iperf_len bytes a number of times. Default is 8 KB for TCP, 1470 bytes for UDP. See also the --iperf_num and --iperf_time options. Value may be a numeric value (bytes), or numeric value followed by K (kilobytes) or M (megabytes) * iperf_listen When --iperf_reverse is used, the client will open an port for the server to connect to for reverse/downlink tests. By default, the test harness will use a random port number between 49152 and 65535. Use this parameter to set an explicit port number for server => client tests. This parameter is not used for Iperf3 * iperf_mss Attempt to set the TCP maximum segment size (MSS) via the TCP_MAXSEG option. The MSS is usually the MTU - 40 bytes for the TCP/IP header. For ethernet, the MSS is 1460 bytes (1500 byte MTU) * iperf_nodelay Set the TCP no delay option, disabling Nagle's algorithm. Normally this is only disabled for interactive applications like telnet * iperf_num The number of buffers to transmit. Normally, Iperf sends for 10 seconds. The --iperf_num option overrides this and sends an array of --iperf_len bytes num times, no matter how long that takes. See also the --iperf_len and --iperf_time options * iperf_parallel The number of simultaneous connections to make to the server. Default is 1. Requires thread support on both the client and server. May contain [cpus] which will be automatically replaced with the number of CPU cores. May also contain an equation which will be automatically evaluated (e.g. --iperf_parallel "[cpus]*2") * iperf_reverse This argument has different meanings depending on Iperf version. For versions 1-2, setting this flag will cause Iperf to execute in tradeoff mode, meaning after the client tests connectivity to the server (uplink), the server will do the same to the client (downlink). For Iperf 3, setting this flag will result in testing from client to server being skipped - thus only generating downlink results * iperf_server IP address or hostname for the Iperf server(s) to test. If a server uses a non-default port (5001 for Iperf v1-2 and 5201 for Iperf v3), the port may be appended preceded by a colon (e.g. 192.168.0.233:5999). This parameter may be repeated to test multiple servers. In networks with high bandwidth capacity (> 15 Gb/s), a single Iperf server process may be insufficient to reach max achievable bandwidth. As a workaround, multiple Iperf server processes may be started each listening on different ports. An server listening on multiple ports can be designated using the format --iperf_server [ip]:[port1]:[port2]:[portN] When designated, multiple concurrent Iperf clients will be started each with the same parameters but different server ports. Test results will then be aggregated from all clients * iperf_server_instance_id The compute instance type identifier for the compute service corresponding to --iperf_server. If --iperf_server is repeated, this parameter may also be repeated (in the same order), or designated only once (same for all --iperf_server). If not set --meta_instance_id will be assumed * iperf_server_os The operating system of the server corresponding to --iperf_server. If --iperf_server is repeated, this parameter may also be repeated (in the same order), or designated only once (same for all --iperf_server). If not set --meta_os will be assumed * iperf_server_provider The name of the cloud provider corresponding to --iperf_server. If --iperf_server is repeated, this parameter may also be repeated (in the same order), or designated only once (same for all --iperf_server). If not set --meta_provider will be assumed * iperf_server_provider_id The id of the cloud provider corresponding to --iperf_server. If --iperf_server is repeated, this parameter may also be repeated (in the same order), or designated only once (same for all --iperf_server). If not set --meta_provider_id will be assumed * iperf_server_region The region identifier for the compute service corresponding to --iperf_server. If --iperf_server is repeated, this parameter may also be repeated (in the same order), or designated only once (same for all --iperf_server). If not set --meta_region will be assumed * iperf_server_service The name of the compute service corresponding to --iperf_server. If --iperf_server is repeated, this parameter may also be repeated (in the same order), or designated only once (same for all --iperf_server). If not set --meta_compute_service will be assumed * iperf_server_service_id The id of the compute service corresponding to --iperf_server. If --iperf_server is repeated, this parameter may also be repeated (in the same order), or designated only once (same for all --iperf_server). If not set --meta_compute_service_id will be assumed * iperf_time The time in seconds to transmit for. Iperf normally works by repeatedly sending an array of --iperf_len bytes for time seconds. Default is 10 seconds. See also the --iperf_len and --iperf_num options * iperf_tos The type-of-service for outgoing packets. (Many routers ignore the TOS field.) You may specify the value in hex with a '0x' prefix, in octal with a '0' prefix, or in decimal. For example, '0x10' hex = '020' octal = '16' decimal. The TOS numbers specified in RFC 1349 are: IPTOS_LOWDELAY minimize delay 0x10 IPTOS_THROUGHPUT maximize throughput 0x08 IPTOS_RELIABILITY maximize reliability 0x04 IPTOS_LOWCOST minimize cost 0x02 * iperf_udp If set, testing will use UDP instead of TCP. When used, jitter and loss result values will also be reported (these are not reported for TCP) * iperf_warmup Number of initial seconds of testing to ignore for result calculations. Default is 0 * iperf_window Sets the socket buffer sizes to the specified value. For TCP, this sets the TCP window size. For UDP it is just the buffer which datagrams are received in, and so limits the largest receivable datagram size * iperf_zerocopy Use a "zero copy" method of sending data, such as sendfile, instead of the usual write. Requires Iperf 3 * meta_compute_service The name of the compute service the testing is performed on. May also be specified using the environment variable bm_compute_service * meta_compute_service_id The id of the compute service the testing is performed on. Added to saved results. May also be specified using the environment variable bm_compute_service_id * meta_cpu CPU descriptor - if not specified, it will be set using the 'model name' attribute in /proc/cpuinfo * meta_instance_id The compute service instance type the testing is performed on (e.g. c3.xlarge). May also be specified using the environment variable bm_instance_id * meta_memory Memory descriptor - if not specified, the system memory size will be used * meta_os Operating system descriptor - if not specified, it will be taken from the first line of /etc/issue * meta_provider The name of the cloud provider this test pertains to. May also be specified using the environment variable bm_provider * meta_provider_id The id of the cloud provider this test pertains to. May also be specified using the environment variable bm_provider_id * meta_region The service region this test pertains to. May also be specified using the environment variable bm_region * meta_resource_id An optional benchmark resource identifiers. May also be specified using the environment variable bm_resource_id * meta_run_id An optional benchmark run identifier. May also be specified using the environment variable bm_run_id * meta_run_group_id An optional benchmark group run identifier. May also be specified using the environment variable bm_run_group_id * meta_test_id Identifier for the test. May also be specified using the environment variable bm_test_id * nopdfreport Don't generate PDF version of test report - report.pdf. (wkhtmltopdf dependency removed if specified) * noreport Don't generate html or PDF test reports - report.zip and report.pdf (gnuplot, wkhtmltopdf and zip dependencies removed if specified) * output The output directory to use for writing test data (logs and artifacts). If not specified, the current working directory will be used * skip_bandwidth_graphs If set along with --iperf_reverse, bandwidth graphs will be skipped in the report * tcp_bw_file Optional path to a file where TCP bandwidth results for every tested server should be saved. This is required for use of a percentage in the --iperf_bandwidth parameter (see above) * tcp_bw_file_purge Delete the tcp_bw_file if it already exists * verbose Show verbose output * wkhtml_xvfb If set, wkhtmlto* commands will be prefixed with xvfb-run (which is added as a dependency). This is useful when the wkhtml installation does not support running in headless mode DEPENDENCIES This benchmark has the following dependencies: gnuplot Generates report graphs (required unless --noreport set) iperf or iperf3 iperf3 will be used if present, otherwise iperf php Test automation scripts (/usr/bin/php) wkhtmltopdf Generates PDF version of report - download from http://wkhtmltopdf.org (required unless --nopdfreport set) xvfb-run Allows wkhtmltopdf to be run in headless mode (required if --nopdfreport is not set and --wkhtml_xvfb is set) zip Used to compress test artifacts (collectd-rrd.zip and report.zip) TEST ARTIFACTS This benchmark generates the following artifacts: collectd-rrd.zip collectd RRD files (see --collectd_rrd) report.zip HTML test report (open index.html) including graphs. Graphs are rendered in svg format report.pdf PDF version of the test report (wkhtmltopdf used to generate this version of the report) SAVE SCHEMA The following columns are included in CSV files/tables generated by save.sh. Indexed MySQL/PostgreSQL columns are identified by *. Columns without descriptions are documented as runtime parameters above. Data types and indexing is documented in schema/iperf.json. Columns can be removed using the save.sh --remove parameter. Multiple result rows may be present if multiple --iperf_server arguments are designated COLUMNS bandwidth_direction: up for uplink, down for downlink bandwidth_max: max bandwidth from 1 second samples bandwidth_mean: mean bandwidth from 1 second samples bandwidth_median: median bandwidth from 1 second samples bandwidth_min: minimum bandwidth from 1 second samples bandwidth_p10: 10th percentile bandwidth from 1 second samples bandwidth_p25: 25th percentile bandwidth from 1 second samples bandwidth_p75: 75th percentile bandwidth from 1 second samples bandwidth_p90: 90th percentile bandwidth from 1 second samples bandwidth_stdev: Bandwidth standard deviation from 1 second samples benchmark_version: [benchmark version] collectd_rrd: [URL to zip file containing collectd rrd files (if --store option used)] cpu_client: average total CPU utilization on the client (Iperf3 only) cpu_server: average total CPU utilization on the server (Iperf3 only) iperf_bandwidth iperf_cmd: iperf command used iperf_concurrency: number of concurrent Iperf server processes (see --iperf_server parameter documentation above) iperf_interval iperf_len iperf_mss iperf_nodelay iperf_num iperf_parallel iperf_server iperf_server_instance_id iperf_server_os iperf_server_provider iperf_server_provider_id iperf_server_region iperf_server_service iperf_server_service_id iperf_time iperf_tos iperf_udp iperf_version: Iperf version number iperf_warmup iperf_window iperf_zerocopy iteration*: [iteration number (used with incremental result directories)] # NOTE: jitter_* and loss_* result metrics are only available for UDP tests # If --iperf_reverse is not set, jitter and loss are limited to a single # metrics reported by the server (thus max, mean, median, p10, etc. will all # be the same). If --iperf_reverse is set, jitter_* and loss_* metrics for the # second result row (bandwidth_direction=down) will be based on metrics from 1 # second samples jitter_max: max jitter from 1 second samples jitter_mean: mean jitter from 1 second samples jitter_median: median jitter from 1 second samples jitter_min: minimum jitter from 1 second samples jitter_p10: 10th percentile jitter from 1 second samples jitter_p25: 25th percentile jitter from 1 second samples jitter_p75: 75th percentile jitter from 1 second samples jitter_p90: 90th percentile jitter from 1 second samples jitter_stdev: Jitter standard deviation from 1 second samples loss_max: max datagram loss (latency variation percentage) from 1 second samples loss_mean: mean datagram loss from 1 second samples loss_median: median datagram loss from 1 second samples loss_min: minimum datagram loss from 1 second samples loss_p10: 10th percentile datagram loss from 1 second samples loss_p25: 25th percentile datagram loss from 1 second samples loss_p75: 75th percentile datagram loss from 1 second samples loss_p90: 90th percentile datagram loss from 1 second samples loss_stdev: Datagram loss standard deviation from 1 second samples meta_compute_service meta_compute_service_id* meta_cpu: [CPU model info] meta_cpu_cache: [CPU cache] meta_cpu_cores: [# of CPU cores] meta_cpu_speed: [CPU clock speed (MHz)] meta_instance_id* meta_hostname: [system under test (SUT) hostname] meta_memory meta_memory_gb: [memory in gigabytes] meta_memory_mb: [memory in megabytes] meta_os meta_provider meta_provider_id* meta_region* meta_resource_id meta_run_id meta_run_group_id meta_test_id* report_pdf: [URL to report PDF file (if --store option used)] report_zip: [URL to report ZIP file (if --store option used)] same_instance_id: true if same_service and iperf_server_instance_id == meta_instance_id same_os: true if iperf_server_os == meta_os same_provider: true if iperf_server_provider_id == meta_provider_id same_region: true if same_service and iperf_server_region == meta_region same_service: true if iperf_server_service_id == meta_service_id test_started: [when the test started] test_stopped: [when the test ended] transfer: total network transfer (megabytes) USAGE # run 1 test iteration against server 10.0.1.1 ./run.sh --iperf_server 10.0.1.1 # run 1 test iteration against server 10.0.1.1 on port 80 ./run.sh --iperf_server 10.0.1.1:80 # run 1 test iteration with some metadata ./run.sh --iperf_server 10.0.1.1 --meta_compute_service_id aws:ec2 --meta_instance_id c3.xlarge --meta_region us-east-1 --meta_test_id aws-0415 # save.sh saves results to CSV, MySQL, PostgreSQL, BigQuery or via HTTP # callback. It can also save artifacts (HTML, JSON and text results) to S3, # Azure Blob Storage or Google Cloud Storage # save results to CSV files ./save.sh # save results from 3 iterations text example above ./save.sh ~/iperf-testing # save results to a PostgreSQL database ./save --db postgresql --db_user dbuser --db_pswd dbpass --db_host db.mydomain.com --db_name benchmarks # save results to BigQuery and artifacts to S3 ./save --db bigquery --db_name benchmark_dataset --store s3 --store_key THISIH5TPISAEZIJFAKE --store_secret thisNoat1VCITCGggisOaJl3pxKmGu2HMKxxfake --store_container benchmarks1234