1 # Copyright (c) 2023 Cisco and/or its affiliates.
2 # Licensed under the Apache License, Version 2.0 (the "License");
3 # you may not use this file except in compliance with the License.
4 # You may obtain a copy of the License at:
6 # http://www.apache.org/licenses/LICENSE-2.0
8 # Unless required by applicable law or agreed to in writing, software
9 # distributed under the License is distributed on an "AS IS" BASIS,
10 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 # See the License for the specific language governing permissions and
12 # limitations under the License.
14 """iPerf3 utilities library."""
18 from resources.libraries.python.Constants import Constants
19 from resources.libraries.python.CpuUtils import CpuUtils
20 from resources.libraries.python.IPUtil import IPUtil
21 from resources.libraries.python.Namespaces import Namespaces
22 from resources.libraries.python.OptionString import OptionString
23 from resources.libraries.python.ssh import exec_cmd, exec_cmd_no_error
27 """iPerf3 traffic generator utilities."""
30 """Initialize iPerf3 class."""
31 # Computed affinity for iPerf server.
32 self._s_affinity = None
33 # Computed affinity for iPerf client.
34 self._c_affinity = None
38 """Log and return the installed traffic generator type.
40 :returns: Traffic generator type string.
46 def get_iperf_version(node):
47 """Log and return the installed traffic generator version.
49 :param node: Node from topology file.
51 :returns: Traffic generator version string.
54 command = f"iperf3 --version | head -1"
55 message = u"Get iPerf version failed!"
56 stdout, _ = exec_cmd_no_error(node, command, message=message)
59 def initialize_iperf_server(
60 self, node, pf_key, interface, bind, bind_gw, bind_mask,
61 namespace=None, cpu_skip_cnt=0, cpu_cnt=1, instances=1):
62 """iPerf3 initialization.
64 :param node: Topology node running iPerf3 server.
65 :param pf_key: First TG's interface (To compute numa location).
66 :param interface: Name of TG bind interface.
67 :param bind: Bind to host, one of node's addresses.
68 :param bind_gw: Bind gateway (required for default route).
69 :param bind_mask: Bind address mask.
70 :param namespace: Name of TG namespace to execute.
71 :param cpu_skip_cnt: Amount of CPU cores to skip.
72 :param cpu_cnt: iPerf3 main thread count.
73 :param instances: Number of simultaneous iPerf3 instances.
81 :type cpu_skip_cnt: int
85 if Iperf3.is_iperf_running(node):
86 Iperf3.teardown_iperf(node)
89 IPUtil.set_linux_interface_ip(
90 node, interface=interface, ip_addr=bind, prefix=bind_mask,
92 IPUtil.set_linux_interface_up(
93 node, interface=interface, namespace=namespace)
94 Namespaces.add_default_route_to_namespace(
95 node, namespace=namespace, default_route=bind_gw)
97 # Compute affinity for iPerf server.
98 self._s_affinity = CpuUtils.get_affinity_iperf(
99 node, pf_key, cpu_skip_cnt=cpu_skip_cnt,
100 cpu_cnt=cpu_cnt * instances)
101 # Compute affinity for iPerf client.
102 self._c_affinity = CpuUtils.get_affinity_iperf(
103 node, pf_key, cpu_skip_cnt=cpu_skip_cnt + cpu_cnt * instances,
104 cpu_cnt=cpu_cnt * instances)
106 for i in range(0, instances):
107 Iperf3.start_iperf_server(
108 node, namespace=namespace, port=5201 + i,
109 affinity=self._s_affinity)
112 def start_iperf_server(
113 node, namespace=None, port=5201, affinity=None):
114 """Start iPerf3 server instance as a deamon.
116 :param node: Topology node running iPerf3 server.
117 :param namespace: Name of TG namespace to execute.
118 :param port: The server port for the server to listen on.
119 :param affinity: iPerf3 server affinity.
125 cmd = IPerf3Server.iperf3_cmdline(
126 namespace=namespace, port=port, affinity=affinity)
128 node, cmd, sudo=True, message=u"Failed to start iPerf3 server!")
131 def is_iperf_running(node):
132 """Check if iPerf3 is running using pgrep.
134 :param node: Topology node running iPerf3.
136 :returns: True if iPerf3 is running otherwise False.
139 ret, _, _ = exec_cmd(node, u"pgrep iperf3", sudo=True)
140 return bool(int(ret) == 0)
143 def teardown_iperf(node):
146 :param node: Topology node running iPerf3.
149 pidfile = u"/tmp/iperf3_server.pid"
150 logfile = u"/tmp/iperf3.log"
154 f"sh -c 'if [ -f {pidfile} ]; then "
159 sudo=True, message=u"iPerf3 kill failed!")
161 def iperf_client_start_remote_exec(
162 self, node, duration, rate, frame_size, async_call=False,
163 warmup_time=0, traffic_directions=1, namespace=None, udp=False,
164 host=None, bind=None, affinity=None):
165 """Execute iPerf3 client script on remote node over ssh to start running
168 :param node: Topology node running iPerf3.
169 :param duration: Time expressed in seconds for how long to send traffic.
170 :param rate: Traffic rate.
171 :param frame_size: L2 frame size to send (without padding and IPG).
172 :param async_call: If enabled then don't wait for all incoming traffic.
173 :param warmup_time: Warmup time period.
174 :param traffic_directions: Traffic is bi- (2) or uni- (1) directional.
176 :param namespace: Namespace to execute iPerf3 client on.
177 :param udp: UDP traffic.
178 :param host: Client connecting to an iPerf server running on host.
179 :param bind: Client bind IP address.
180 :param affinity: iPerf3 client affinity.
182 :type duration: float
184 :type frame_size: str
185 :type async_call: bool
186 :type warmup_time: float
187 :type traffic_directions: int
193 :returns: List of iPerf3 PIDs.
196 if not isinstance(duration, (float, int)):
197 duration = float(duration)
198 if not isinstance(warmup_time, (float, int)):
199 warmup_time = float(warmup_time)
201 affinity = self._c_affinity
205 kwargs[u"namespace"] = namespace
206 kwargs[u"host"] = host
207 kwargs[u"bind"] = bind
210 kwargs[u"affinity"] = affinity
211 kwargs[u"duration"] = duration
212 kwargs[u"rate"] = rate
213 kwargs[u"frame_size"] = frame_size
214 kwargs[u"warmup_time"] = warmup_time
215 kwargs[u"traffic_directions"] = traffic_directions
216 kwargs[u"async_call"] = async_call
218 cmd = IPerf3Client.iperf3_cmdline(**kwargs)
220 stdout, _ = exec_cmd_no_error(
221 node, cmd, timeout=int(duration) + 30,
222 message=u"iPerf3 runtime error!")
225 return stdout.split()
226 return json.loads(stdout)
229 def iperf_client_stop_remote_exec(node, pids):
230 """Stop iPerf3 client execution.
232 :param pids: PID or List of PIDs of iPerf3 client.
233 :type pids: str or list
235 if not isinstance(pids, list):
240 node, f"kill {pid}", sudo=True, message=u"Kill iPerf3 failed!")
244 """iPerf3 server utilities."""
247 def iperf3_cmdline(**kwargs):
248 """Get iPerf3 server command line.
250 :param kwargs: List of iPerf3 server parameters.
252 :returns: iPerf3 server command line.
256 if kwargs['namespace']:
257 cmd.add(f"ip netns exec {kwargs['namespace']}")
260 cmd_options = OptionString(prefix=u"--")
261 # Run iPerf in server mode. (This will only allow one iperf connection
266 # Run the server in background as a daemon.
267 cmd_options.add_if_from_dict(
268 u"daemon", u"daemon", kwargs, True)
270 # Write a file with the process ID, most useful when running as a
272 cmd_options.add_with_value_from_dict(
273 u"pidfile", u"pidfile", kwargs, f"/tmp/iperf3_server.pid")
275 # Send output to a log file.
276 cmd_options.add_with_value_from_dict(
277 u"logfile", u"logfile", kwargs, f"/tmp/iperf3.log")
279 # The server port for the server to listen on and the client to
280 # connect to. This should be the same in both client and server.
282 cmd_options.add_with_value_from_dict(
283 u"port", u"port", kwargs, 5201)
285 # Set the CPU affinity, if possible (Linux and FreeBSD only).
286 cmd_options.add_with_value_from_dict(
287 u"affinity", u"affinity", kwargs)
289 # Output in JSON format.
290 cmd_options.add_if_from_dict(
291 u"json", u"json", kwargs, True)
293 # Give more detailed output.
294 cmd_options.add_if_from_dict(
295 u"verbose", u"verbose", kwargs, True)
297 return cmd.extend(cmd_options)
301 """iPerf3 client utilities."""
304 def iperf3_cmdline(**kwargs):
305 """Get iperf_client driver command line.
307 :param kwargs: List of iperf_client driver parameters.
309 :returns: iperf_client driver command line.
314 dirname = f"{Constants.REMOTE_FW_DIR}/resources/tools/iperf"
315 cmd.add(f"'{dirname}/iperf_client.py'")
317 cmd_options = OptionString(prefix=u"--")
318 # Namespace to execute iPerf3 client on.
319 cmd_options.add_with_value_from_dict(
320 u"namespace", u"namespace", kwargs)
322 # Client connecting to an iPerf3 server running on host.
323 cmd_options.add_with_value_from_dict(
324 u"host", u"host", kwargs)
326 # Client bind IP address.
327 cmd_options.add_with_value_from_dict(
328 u"bind", u"bind", kwargs)
330 # Use UDP rather than TCP.
331 cmd_options.add_if_from_dict(
332 u"udp", u"udp", kwargs, False)
334 # Set the CPU affinity, if possible.
335 cmd_options.add_with_value_from_dict(
336 u"affinity", u"affinity", kwargs)
338 # Time expressed in seconds for how long to send traffic.
339 cmd_options.add_with_value_from_dict(
340 u"duration", u"duration", kwargs)
342 # Send bi- (2) or uni- (1) directional traffic.
343 cmd_options.add_with_value_from_dict(
344 u"traffic_directions", u"traffic_directions", kwargs, 1)
346 # Traffic warm-up time in seconds, (0=disable).
347 cmd_options.add_with_value_from_dict(
348 u"warmup_time", u"warmup_time", kwargs, 5.0)
350 # L2 frame size to send (without padding and IPG).
351 cmd_options.add_with_value_from_dict(
352 u"frame_size", u"frame_size", kwargs)
354 # Traffic rate expressed with units.
355 cmd_options.add_with_value_from_dict(
356 u"rate", u"rate", kwargs)
358 # If enabled then don't wait for all incoming traffic.
359 cmd_options.add_if_from_dict(
360 u"async_start", u"async_call", kwargs, False)
362 # Number of iPerf3 client parallel instances.
363 cmd_options.add_with_value_from_dict(
364 u"instances", u"instances", kwargs, 1)
366 # Number of iPerf3 client parallel flows.
367 cmd_options.add_with_value_from_dict(
368 u"parallel", u"parallel", kwargs, 8)
370 return cmd.extend(cmd_options)