Modules¶
iperf3¶
Python wrapper for the iperf3 libiperf.so.0 library. The module consists of two
classes, Client
and Server
, that inherit from the base class
IPerf3
. They provide a nice (if i say so myself) and pythonic way to
interact with the iperf3 utility.
At the moment the module redirects stdout and stderr to a pipe and returns the
received data back after each client.run()
or server.run()
call. In
later releases there will be an option to toggle this on or off.
A user should never have to utilise the IPerf3
class directly, this
class provides common settings for the Client
and Server
classes.
To get started quickly see the Examples page.
Client¶
-
class
iperf3.
Client
(*args, **kwargs)[source]¶ An iperf3 client connection.
This opens up a connection to a running iperf3 server
Basic Usage:
>>> import iperf3 >>> client = iperf3.Client() >>> client.duration = 1 >>> client.server_hostname = '127.0.0.1' >>> client.port = 5201 >>> client.run() {'intervals': [{'sum': {...
-
bandwidth
¶ Target bandwidth in bits/sec
-
blksize
¶ The test blksize.
-
bulksize
¶ The test bulksize.
Deprecated argument, use blksize instead to ensure consistency with iperf3 C libary
-
duration
¶ The test duration in seconds.
-
num_streams
¶ The number of streams to use.
-
protocol
¶ The iperf3 instance protocol
valid protocols are ‘tcp’ and ‘udp’
Return type: str
-
reverse
¶ Toggles direction of test
Return type: bool
-
run
()[source]¶ Run the current test client.
Return type: instance of TestResult
-
server_hostname
¶ The server hostname to connect to.
Accepts DNS entries or IP addresses.
Return type: string
-
zerocopy
¶ Toggle zerocopy.
Use the sendfile() system call for “Zero Copy” mode. This uses much less CPU. This is not supported on all systems.
Note there isn’t a hook in the libiperf library for getting the current configured value. Relying on zerocopy.setter function
Return type: bool
-
Server¶
-
class
iperf3.
Server
(*args, **kwargs)[source]¶ An iperf3 server connection.
This starts an iperf3 server session. The server terminates after each succesful client connection so it might be useful to run Server.run() in a loop.
The C function iperf_run_server is called in a seperate thread to make sure KeyboardInterrupt(aka ctrl+c) can still be captured
Basic Usage:
>>> import iperf3 >>> server = iperf3.Server() >>> server.run() {'start': {...
-
run
()[source]¶ Run the iperf3 server instance.
Return type: instance of TestResult
-
TestResult¶
-
class
iperf3.
TestResult
(result)[source]¶ Class containing iperf3 test results.
Parameters: - text – The raw result from libiperf as text
- json – The raw result from libiperf asjson/dict
- error – Error captured during test, None if all ok
- time – Start time
- timesecs – Start time in seconds
- system_info – System info
- version – Iperf Version
- local_host – Local host ip
- local_port – Local port number
- remote_host – Remote host ip
- remote_port – Remote port number
- reverse – Test ran in reverse direction
- protocol – ‘TCP’ or ‘UDP’
- num_streams – Number of test streams
- blksize –
- omit –
- duration – Test duration in seconds
- local_cpu_total – The local total CPU load
- local_cpu_user – The local user CPU load
- local_cpu_system – The local system CPU load
- remote_cpu_total – The remote total CPU load
- remote_cpu_user – The remote user CPU load
- remote_cpu_system – The remote system CPU load
TCP test specific
Parameters: - tcp_mss_default –
- retransmits – amount of retransmits (Only returned from client)
- sent_bytes – Sent bytes
- sent_bps – Sent bits per second
- sent_kbps – sent kilobits per second
- sent_Mbps – Sent Megabits per second
- sent_kB_s – Sent kiloBytes per second
- sent_MB_s – Sent MegaBytes per second
- received_bytes – Received bytes
- received_bps – Received bits per second
- received_kbps – Received kilobits per second
- received_Mbps – Received Megabits per second
- received_kB_s – Received kiloBytes per second
- received_MB_s – Received MegaBytes per second
UDP test specific
Parameters: - bytes –
- bps –
- jitter_ms –
- kbps –
- Mbps –
- kB_s –
- MB_s –
- packets –
- lost_packets –
- lost_percent –
- seconds –
IPerf3¶
-
class
iperf3.
IPerf3
(role, verbose=True, lib_name=None)[source]¶ The base class used by both the iperf3
Server
andClient
Note
You should not use this class directly
-
bind_address
¶ The bind address the iperf3 instance will listen on
use * to listen on all available IPs :rtype: string
-
iperf_version
¶ Returns the version of the libiperf library
Return type: string
-
json_output
¶ Toggles json output of libiperf
Turning this off will output the iperf3 instance results to stdout/stderr
Return type: bool
-
port
¶ The port the iperf3 server is listening on
-
role
¶ The iperf3 instance role
valid roles are ‘c’=client and ‘s’=server
Return type: ‘c’ or ‘s’
-
run
()[source]¶ Runs the iperf3 instance.
This function has to be instantiated by the Client and Server instances
Return type: NotImplementedError
-
verbose
¶ Toggles verbose output for the iperf3 instance
Return type: bool
-