1 # Copyright (c) 2022 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 """NAT utilities library."""
16 from math import log2, modf
17 from pprint import pformat
18 from enum import IntEnum
20 from ipaddress import IPv4Address
21 from robot.api import logger
23 from resources.libraries.python.Constants import Constants
24 from resources.libraries.python.InterfaceUtil import InterfaceUtil
25 from resources.libraries.python.topology import Topology
26 from resources.libraries.python.PapiExecutor import PapiSocketExecutor
29 class NatConfigFlags(IntEnum):
30 """NAT plugin configuration flags"""
32 NAT_IS_TWICE_NAT = 0x01
33 NAT_IS_SELF_TWICE_NAT = 0x02
34 NAT_IS_OUT2IN_ONLY = 0x04
35 NAT_IS_ADDR_ONLY = 0x08
39 NAT_IS_EXT_HOST_VALID = 0x80
42 class Nat44ConfigFlags(IntEnum):
43 """NAT44 configuration flags"""
44 NAT44_IS_ENDPOINT_INDEPENDENT = 0x00
45 NAT44_IS_ENDPOINT_DEPENDENT = 0x01
46 NAT44_IS_STATIC_MAPPING_ONLY = 0x02
47 NAT44_IS_CONNECTION_TRACKING = 0x04
48 NAT44_IS_OUT2IN_DPO = 0x08
51 class NatAddrPortAllocAlg(IntEnum):
52 """NAT Address and port assignment algorithms."""
53 NAT_ALLOC_ALG_DEFAULT = 0
54 NAT_ALLOC_ALG_MAP_E = 1
55 NAT_ALLOC_ALG_PORT_RANGE = 2
59 """This class defines the methods to set NAT."""
65 def enable_nat44_ed_plugin(
66 node, inside_vrf=0, outside_vrf=0, sessions=0, session_memory=0,
68 """Enable NAT44 plugin.
70 :param node: DUT node.
71 :param inside_vrf: Inside VRF ID.
72 :param outside_vrf: Outside VRF ID.
73 :param sessions: Maximum number of sessions.
74 :param session_memory: Session memory size - overwrite auto calculated
75 hash allocation parameter if non-zero.
76 :param mode: NAT44 mode. Valid values:
77 - endpoint-independent
83 :type inside_vrf: str or int
84 :type outside_vrf: str or int
85 :type sessions: str or int
86 :type session_memory: str or int
89 cmd = u"nat44_ed_plugin_enable_disable"
90 err_msg = f"Failed to enable NAT44 plugin on the host {node[u'host']}!"
93 inside_vrf=int(inside_vrf),
94 outside_vrf=int(outside_vrf),
95 sessions=int(sessions),
96 session_memory=int(session_memory),
99 f"NAT44_IS_{mode.replace(u'-', u'_').upper()}"
103 with PapiSocketExecutor(node) as papi_exec:
104 papi_exec.add(cmd, **args_in).get_reply(err_msg)
107 def set_nat44_interface(node, interface, flag):
108 """Set inside and outside interfaces for NAT44.
110 :param node: DUT node.
111 :param interface: NAT44 interface.
112 :param flag: Interface NAT configuration flag name.
117 cmd = u"nat44_interface_add_del_feature"
119 err_msg = f"Failed to set {flag} interface {interface} for NAT44 " \
120 f"on host {node[u'host']}"
122 sw_if_index=InterfaceUtil.get_sw_if_index(node, interface),
124 flags=getattr(NatConfigFlags, flag).value
127 with PapiSocketExecutor(node) as papi_exec:
128 papi_exec.add(cmd, **args_in).get_reply(err_msg)
131 def set_nat44_interfaces(node, int_in, int_out):
132 """Set inside and outside interfaces for NAT44.
134 :param node: DUT node.
135 :param int_in: Inside interface.
136 :param int_out: Outside interface.
141 NATUtil.set_nat44_interface(node, int_in, u"NAT_IS_INSIDE")
142 NATUtil.set_nat44_interface(node, int_out, u"NAT_IS_OUTSIDE")
145 def set_nat44_address_range(
146 node, start_ip, end_ip, vrf_id=Constants.BITWISE_NON_ZERO,
147 flag=u"NAT_IS_NONE"):
148 """Set NAT44 address range.
150 The return value is a callable (zero argument Python function)
151 which can be used to reset NAT state, so repeated trial measurements
152 hit the same slow path.
154 :param node: DUT node.
155 :param start_ip: IP range start.
156 :param end_ip: IP range end.
157 :param vrf_id: VRF index (Optional).
158 :param flag: NAT flag name.
164 :returns: Resetter of the NAT state.
165 :rtype: Callable[[], None]
167 cmd = u"nat44_add_del_address_range"
168 err_msg = f"Failed to set NAT44 address range on host {node[u'host']}"
171 first_ip_address=IPv4Address(str(start_ip)).packed,
172 last_ip_address=IPv4Address(str(end_ip)).packed,
174 flags=getattr(NatConfigFlags, flag).value
177 with PapiSocketExecutor(node) as papi_exec:
178 papi_exec.add(cmd, **args_in).get_reply(err_msg)
180 # A closure, accessing the variables above.
182 """Delete and re-add the NAT range setting."""
183 with PapiSocketExecutor(node) as papi_exec:
184 args_in[u"is_add"] = False
185 papi_exec.add(cmd, **args_in)
186 args_in[u"is_add"] = True
187 papi_exec.add(cmd, **args_in)
188 papi_exec.get_replies(err_msg)
193 def show_nat44_config(node):
194 """Show the NAT44 plugin running configuration.
196 :param node: DUT node.
199 cmd = u"nat44_show_running_config"
200 err_msg = f"Failed to get NAT44 configuration on host {node[u'host']}"
202 with PapiSocketExecutor(node) as papi_exec:
203 reply = papi_exec.add(cmd).get_reply(err_msg)
205 logger.debug(f"NAT44 Configuration:\n{pformat(reply)}")
208 def show_nat44_summary(node):
209 """Show NAT44 summary on the specified topology node.
211 :param node: Topology node.
213 :returns: NAT44 summary data.
216 return PapiSocketExecutor.run_cli_cmd(node, u"show nat44 summary")
219 def show_nat_base_data(node):
220 """Show the NAT base data.
225 nat44_interface_addr_dump
227 nat44_static_mapping_dump
230 :param node: DUT node.
235 u"nat44_interface_addr_dump",
236 u"nat44_address_dump",
237 u"nat44_static_mapping_dump",
238 u"nat44_interface_dump",
240 PapiSocketExecutor.dump_and_log(node, cmds)
243 def show_nat_user_data(node):
244 """Show the NAT user data.
249 nat44_user_session_dump
251 :param node: DUT node.
256 u"nat44_user_session_dump",
258 PapiSocketExecutor.dump_and_log(node, cmds)
261 def compute_max_translations_per_thread(sessions, threads):
262 """Compute value of max_translations_per_thread NAT44 parameter based on
263 total number of worker threads.
265 :param sessions: Required number of NAT44 sessions.
266 :param threads: Number of worker threads.
269 :returns: Value of max_translations_per_thread NAT44 parameter.
272 # vpp-device tests have not dedicated physical core so
273 # ${dp_count_int} == 0 but we need to use one thread
274 threads = 1 if not int(threads) else int(threads)
275 rest, mult = modf(log2(sessions/(10*threads)))
276 return 2 ** (int(mult) + (1 if rest else 0)) * 10
279 def get_nat44_sessions_number(node, proto):
280 """Get number of expected NAT44 sessions from NAT44 mapping data.
282 This keyword uses output from a CLI command,
283 so it can start failing when VPP changes the output format.
284 TODO: Switch to API (or stat segment) when available.
286 The current implementation supports both 2202 and post-2202 format.
287 (The Gerrit number changing the output format is 34877.)
289 For TCP proto, the expected state after rampup is
290 some number of sessions in transitory state (VPP has seen the FINs),
291 and some number of sessions in established state (meaning
292 some FINs were lost in the last trial).
293 While the two states may need slightly different number of cycles
294 to process next packet, the current implementation considers
295 both of them the "fast path", so they are both counted as expected.
297 As the tests should fail if a session is timed-out,
298 the logic substracts timed out sessions for the returned value
299 (only available for post-2202 format).
301 TODO: Investigate if it is worth to insert additional rampup trials
302 in TPUT tests to ensure all sessions are transitory before next
305 :param node: DUT node.
306 :param proto: Required protocol - TCP/UDP/ICMP.
309 :returns: Number of active established NAT44 sessions.
311 :raises ValueError: If not supported protocol.
312 :raises RuntimeError: If output is not formatted as expected.
314 proto_l = proto.strip().lower()
315 if proto_l not in [u"udp", u"tcp", u"icmp"]:
316 raise ValueError(f"Unsupported protocol: {proto}!")
317 summary_text = NATUtil.show_nat44_summary(node)
318 summary_lines = summary_text.splitlines()
319 # Output from VPP v22.02 and before, delete when no longer needed.
320 pattern_2202 = f"total {proto_l} sessions:"
321 if pattern_2202 in summary_text:
322 for line in summary_lines:
323 if pattern_2202 not in line:
325 return int(line.split(u":", 1)[1].strip())
326 # Post-2202, the proto info and session info are not on the same line.
328 for line in summary_lines:
330 if f"{proto_l} sessions:" in line:
333 # Proto is found, find the line we are interested in.
334 if u"total" not in line:
335 raise RuntimeError(f"show nat summary: no {proto} total.")
336 # We have the line with relevant numbers.
337 total_part, timed_out_part = line.split(u"(", 1)
338 timed_out_part = timed_out_part.split(u")", 1)[0]
339 total_count = int(total_part.split(u":", 1)[1].strip())
340 timed_out_count = int(timed_out_part.split(u":", 1)[1].strip())
341 active_count = total_count - timed_out_count
343 raise RuntimeError(u"Unknown format of show nat44 summary")
346 # DET44 means deterministic mode of NAT44
348 def enable_det44_plugin(node, inside_vrf=0, outside_vrf=0):
349 """Enable DET44 plugin.
351 :param node: DUT node.
352 :param inside_vrf: Inside VRF ID.
353 :param outside_vrf: Outside VRF ID.
355 :type inside_vrf: str or int
356 :type outside_vrf: str or int
358 cmd = u"det44_plugin_enable_disable"
359 err_msg = f"Failed to enable DET44 plugin on the host {node[u'host']}!"
362 inside_vrf=int(inside_vrf),
363 outside_vrf=int(outside_vrf)
366 with PapiSocketExecutor(node) as papi_exec:
367 papi_exec.add(cmd, **args_in).get_reply(err_msg)
370 def set_det44_interface(node, if_key, is_inside):
371 """Enable DET44 feature on the interface.
373 :param node: DUT node.
374 :param if_key: Interface key from topology file of interface
375 to enable DET44 feature on.
376 :param is_inside: True if interface is inside, False if outside.
379 :type is_inside: bool
381 cmd = u"det44_interface_add_del_feature"
382 err_msg = f"Failed to enable DET44 feature on the interface {if_key} " \
383 f"on the host {node[u'host']}!"
387 sw_if_index=Topology.get_interface_sw_index(node, if_key)
390 with PapiSocketExecutor(node) as papi_exec:
391 papi_exec.add(cmd, **args_in).get_reply(err_msg)
394 def set_det44_mapping(node, ip_in, subnet_in, ip_out, subnet_out):
395 """Set DET44 mapping.
397 The return value is a callable (zero argument Python function)
398 which can be used to reset NAT state, so repeated trial measurements
399 hit the same slow path.
401 :param node: DUT node.
402 :param ip_in: Inside IP.
403 :param subnet_in: Inside IP subnet.
404 :param ip_out: Outside IP.
405 :param subnet_out: Outside IP subnet.
408 :type subnet_in: str or int
410 :type subnet_out: str or int
412 cmd = u"det44_add_del_map"
413 err_msg = f"Failed to set DET44 mapping on the host {node[u'host']}!"
416 in_addr=IPv4Address(str(ip_in)).packed,
417 in_plen=int(subnet_in),
418 out_addr=IPv4Address(str(ip_out)).packed,
419 out_plen=int(subnet_out)
422 with PapiSocketExecutor(node) as papi_exec:
423 papi_exec.add(cmd, **args_in).get_reply(err_msg)
425 # A closure, accessing the variables above.
427 """Delete and re-add the deterministic NAT mapping."""
428 with PapiSocketExecutor(node) as papi_exec:
429 args_in[u"is_add"] = False
430 papi_exec.add(cmd, **args_in)
431 args_in[u"is_add"] = True
432 papi_exec.add(cmd, **args_in)
433 papi_exec.get_replies(err_msg)
438 def get_det44_mapping(node):
439 """Get DET44 mapping data.
441 :param node: DUT node.
443 :returns: Dictionary of DET44 mapping data.
446 cmd = u"det44_map_dump"
447 err_msg = f"Failed to get DET44 mapping data on the host " \
450 with PapiSocketExecutor(node) as papi_exec:
451 details = papi_exec.add(cmd, **args_in).get_reply(err_msg)
456 def get_det44_sessions_number(node):
457 """Get number of established DET44 sessions from actual DET44 mapping
459 :param node: DUT node.
461 :returns: Number of established DET44 sessions.
464 det44_data = NATUtil.get_det44_mapping(node)
465 return det44_data.get(u"ses_num", 0)
468 def show_det44(node):
477 :param node: DUT node.
481 u"det44_interface_dump",
483 u"det44_session_dump",
485 PapiSocketExecutor.dump_and_log(node, cmds)