1 # Copyright (c) 2019 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 """Python API executor library.
26 from pprint import pformat
27 from robot.api import logger
29 from resources.libraries.python.Constants import Constants
30 from resources.libraries.python.LocalExecution import run
31 from resources.libraries.python.FilteredLogger import FilteredLogger
32 from resources.libraries.python.PythonThree import raise_from
33 from resources.libraries.python.PapiHistory import PapiHistory
34 from resources.libraries.python.ssh import (
35 SSH, SSHTimeout, exec_cmd_no_error, scp_node)
36 from resources.libraries.python.VppApiCrc import VppApiCrcChecker
39 __all__ = ["PapiExecutor", "PapiSocketExecutor"]
43 """A helper method, to make namedtuple-like object accessible as dict.
45 If the object is namedtuple-like, its _asdict() form is returned,
46 but in the returned object __getitem__ method is wrapped
47 to dictize also any items returned.
48 If the object does not have _asdict, it will be returned without any change.
49 Integer keys still access the object as tuple.
51 A more useful version would be to keep obj mostly as a namedtuple,
52 just add getitem for string keys. Unfortunately, namedtuple inherits
53 from tuple, including its read-only __getitem__ attribute,
54 so we cannot monkey-patch it.
56 TODO: Create a proxy for namedtuple to allow that.
58 :param obj: Arbitrary object to dictize.
60 :returns: Dictized object.
61 :rtype: same as obj type or collections.OrderedDict
63 if not hasattr(obj, "_asdict"):
66 old_get = ret.__getitem__
67 new_get = lambda self, key: dictize(old_get(self, key))
68 ret.__getitem__ = new_get
72 class PapiSocketExecutor(object):
73 """Methods for executing VPP Python API commands on forwarded socket.
75 The current implementation connects for the duration of resource manager.
76 Delay for accepting connection is 10s, and disconnect is explicit.
77 TODO: Decrease 10s to value that is long enough for creating connection
78 and short enough to not affect performance.
80 The current implementation downloads and parses .api.json files only once
81 and stores a VPPApiClient instance (disconnected) as a class variable.
82 Accessing multiple nodes with different APIs is therefore not supported.
84 The current implementation seems to run into read error occasionally.
85 Not sure if the error is in Python code on Robot side, ssh forwarding,
86 or socket handling at VPP side. Anyway, reconnect after some sleep
87 seems to help, hoping repeated command execution does not lead to surprises.
88 The reconnection is logged at WARN level, so it is prominently shown
89 in log.html, so we can see how frequently it happens.
91 TODO: Support sockets in NFs somehow.
92 TODO: Support handling of retval!=0 without try/except in caller.
94 Note: Use only with "with" statement, e.g.:
96 with PapiSocketExecutor(node) as papi_exec:
97 reply = papi_exec.add('show_version').get_reply(err_msg)
99 This class processes two classes of VPP PAPI methods:
100 1. Simple request / reply: method='request'.
101 2. Dump functions: method='dump'.
103 Note that access to VPP stats over socket is not supported yet.
105 The recommended ways of use are (examples):
107 1. Simple request / reply
109 a. One request with no arguments:
111 with PapiSocketExecutor(node) as papi_exec:
112 reply = papi_exec.add('show_version').get_reply(err_msg)
114 b. Three requests with arguments, the second and the third ones are the same
115 but with different arguments.
117 with PapiSocketExecutor(node) as papi_exec:
118 replies = papi_exec.add(cmd1, **args1).add(cmd2, **args2).\
119 add(cmd2, **args3).get_replies(err_msg)
123 cmd = 'sw_interface_rx_placement_dump'
124 with PapiSocketExecutor(node) as papi_exec:
125 details = papi_exec.add(cmd, sw_if_index=ifc['vpp_sw_index']).\
129 # Class cache for reuse between instances.
130 cached_vpp_instance = None
131 api_json_directory = None
132 crc_checker_instance = None
134 def __init__(self, node, remote_vpp_socket="/run/vpp-api.sock"):
135 """Store the given arguments, declare managed variables.
137 :param node: Node to connect to and forward unix domain socket from.
138 :param remote_vpp_socket: Path to remote socket to tunnel to.
140 :type remote_vpp_socket: str
143 self._remote_vpp_socket = remote_vpp_socket
144 # The list of PAPI commands to be executed on the node.
145 self._api_command_list = list()
146 # The following values are set on enter, reset on exit.
147 self._temp_dir = None
148 self._ssh_control_socket = None
149 self._local_vpp_socket = None
151 def create_crc_checker(self):
152 """Return the cached instance or create new one from directory.
154 It is assumed self.api_json_directory is set, as a class variable.
156 :returns: Cached or newly created instance aware of .api.json content.
157 :rtype: VppApiCrc.VppApiCrcChecker
160 if cls.crc_checker_instance is None:
161 cls.crc_checker_instance = VppApiCrcChecker(cls.api_json_directory)
162 return cls.crc_checker_instance
165 def vpp_instance(self):
166 """Return VPP instance with bindings to all API calls.
168 The returned instance is initialized for unix domain socket access,
169 it has initialized all the bindings, but it is not connected
170 (to local socket) yet.
172 First invocation downloads .api.json files from self._node
173 into a temporary directory.
175 After first invocation, the result is cached, so other calls are quick.
176 Class variable is used as the cache, but this property is defined as
177 an instance method, so that _node (for api files) is known.
179 :returns: Initialized but not connected VPP instance.
180 :rtype: vpp_papi.VPPApiClient
183 if cls.cached_vpp_instance is not None:
184 return cls.cached_vpp_instance
185 tmp_dir = tempfile.mkdtemp(dir="/tmp")
186 package_path = "Not set yet."
188 # Pack, copy and unpack Python part of VPP installation from _node.
189 # TODO: Use rsync or recursive version of ssh.scp_node instead?
191 exec_cmd_no_error(node, ["rm", "-rf", "/tmp/papi.txz"])
192 # Papi python version depends on OS (and time).
193 # Python 2.7 or 3.4, site-packages or dist-packages.
194 installed_papi_glob = "/usr/lib/python*/*-packages/vpp_papi"
195 # We need to wrap this command in bash, in order to expand globs,
196 # and as ssh does join, the inner command has to be quoted.
197 inner_cmd = " ".join([
198 "tar", "cJf", "/tmp/papi.txz", "--exclude=*.pyc",
199 installed_papi_glob, "/usr/share/vpp/api"])
200 exec_cmd_no_error(node, ["bash", "-c", "'" + inner_cmd + "'"])
201 scp_node(node, tmp_dir + "/papi.txz", "/tmp/papi.txz", get=True)
202 run(["tar", "xf", tmp_dir + "/papi.txz", "-C", tmp_dir])
203 cls.api_json_directory = tmp_dir + "/usr/share/vpp/api"
204 # Perform initial checks before .api.json files are gone,
205 # by accessing the property (which also creates its instance).
206 self.create_crc_checker()
207 # When present locally, we finally can find the installation path.
208 package_path = glob.glob(tmp_dir + installed_papi_glob)[0]
209 # Package path has to be one level above the vpp_papi directory.
210 package_path = package_path.rsplit('/', 1)[0]
211 sys.path.append(package_path)
212 from vpp_papi.vpp_papi import VPPApiClient as vpp_class
213 vpp_class.apidir = cls.api_json_directory
214 # We need to create instance before removing from sys.path.
215 cls.cached_vpp_instance = vpp_class(
216 use_socket=True, server_address="TBD", async_thread=False,
217 read_timeout=14, logger=FilteredLogger(logger, "INFO"))
218 # Cannot use loglevel parameter, robot.api.logger lacks support.
219 # TODO: Stop overriding read_timeout when VPP-1722 is fixed.
221 shutil.rmtree(tmp_dir)
222 if sys.path[-1] == package_path:
224 return cls.cached_vpp_instance
227 """Create a tunnel, connect VPP instance.
229 Only at this point a local socket names are created
230 in a temporary directory, because VIRL runs 3 pybots at once,
231 so harcoding local filenames does not work.
234 :rtype: PapiSocketExecutor
236 # Parsing takes longer than connecting, prepare instance before tunnel.
237 vpp_instance = self.vpp_instance
239 self._temp_dir = tempfile.mkdtemp(dir="/tmp")
240 self._local_vpp_socket = self._temp_dir + "/vpp-api.sock"
241 self._ssh_control_socket = self._temp_dir + "/ssh.sock"
242 ssh_socket = self._ssh_control_socket
243 # Cleanup possibilities.
244 ret_code, _ = run(["ls", ssh_socket], check=False)
246 # This branch never seems to be hit in CI,
247 # but may be useful when testing manually.
248 run(["ssh", "-S", ssh_socket, "-O", "exit", "0.0.0.0"],
249 check=False, log=True)
250 # TODO: Is any sleep necessary? How to prove if not?
251 run(["sleep", "0.1"])
252 run(["rm", "-vrf", ssh_socket])
253 # Even if ssh can perhaps reuse this file,
254 # we need to remove it for readiness detection to work correctly.
255 run(["rm", "-rvf", self._local_vpp_socket])
256 # On VIRL, the ssh user is not added to "vpp" group,
257 # so we need to change remote socket file access rights.
259 node, "chmod o+rwx " + self._remote_vpp_socket, sudo=True)
260 # We use sleep command. The ssh command will exit in 10 second,
261 # unless a local socket connection is established,
262 # in which case the ssh command will exit only when
263 # the ssh connection is closed again (via control socket).
264 # The log level is to supress "Warning: Permanently added" messages.
266 "ssh", "-S", ssh_socket, "-M",
267 "-o", "LogLevel=ERROR", "-o", "UserKnownHostsFile=/dev/null",
268 "-o", "StrictHostKeyChecking=no", "-o", "ExitOnForwardFailure=yes",
269 "-L", self._local_vpp_socket + ':' + self._remote_vpp_socket,
270 "-p", str(node['port']), node['username'] + "@" + node['host'],
272 priv_key = node.get("priv_key")
274 # This is tricky. We need a file to pass the value to ssh command.
275 # And we need ssh command, because paramiko does not suport sockets
276 # (neither ssh_socket, nor _remote_vpp_socket).
277 key_file = tempfile.NamedTemporaryFile()
278 key_file.write(priv_key)
279 # Make sure the content is written, but do not close yet.
281 ssh_cmd[1:1] = ["-i", key_file.name]
282 password = node.get("password")
284 # Prepend sshpass command to set password.
285 ssh_cmd[:0] = ["sshpass", "-p", password]
286 time_stop = time.time() + 10.0
287 # subprocess.Popen seems to be the best way to run commands
288 # on background. Other ways (shell=True with "&" and ssh with -f)
289 # seem to be too dependent on shell behavior.
290 # In particular, -f does NOT return values for run().
291 subprocess.Popen(ssh_cmd)
292 # Check socket presence on local side.
293 while time.time() < time_stop:
294 # It can take a moment for ssh to create the socket file.
295 ret_code, _ = run(["ls", "-l", self._local_vpp_socket], check=False)
300 raise RuntimeError("Local side socket has not appeared.")
302 # Socket up means the key has been read. Delete file by closing it.
304 # Everything is ready, set the local socket address and connect.
305 vpp_instance.transport.server_address = self._local_vpp_socket
306 # It seems we can get read error even if every preceding check passed.
307 # Single retry seems to help.
310 vpp_instance.connect_sync("csit_socket")
311 except IOError as err:
312 logger.warn("Got initial connect error {err!r}".format(err=err))
313 vpp_instance.disconnect()
317 raise RuntimeError("Failed to connect to VPP over a socket.")
320 def __exit__(self, exc_type, exc_val, exc_tb):
321 """Disconnect the vpp instance, tear down the SHH tunnel.
323 Also remove the local sockets by deleting the temporary directory.
324 Arguments related to possible exception are entirely ignored.
326 self.vpp_instance.disconnect()
327 run(["ssh", "-S", self._ssh_control_socket, "-O", "exit", "0.0.0.0"],
329 shutil.rmtree(self._temp_dir)
332 def add(self, csit_papi_command, history=True, **kwargs):
333 """Add next command to internal command list; return self.
335 The argument name 'csit_papi_command' must be unique enough as it cannot
336 be repeated in kwargs.
337 Unless disabled, new entry to papi history is also added at this point.
339 Any pending conflicts from .api.json processing are raised.
340 Then the command name is checked for known CRCs.
341 Unsupported commands raise an exception, as CSIT change
342 should not start using messages without making sure which CRCs
344 Each CRC issue is raised only once, so subsequent tests
345 can raise other issues.
347 :param csit_papi_command: VPP API command.
348 :param history: Enable/disable adding command to PAPI command history.
349 :param kwargs: Optional key-value arguments.
350 :type csit_papi_command: str
353 :returns: self, so that method chaining is possible.
354 :rtype: PapiSocketExecutor
355 :raises RuntimeError: If unverified or conflicting CRC is encountered.
358 PapiHistory.add_to_papi_history(
359 self._node, csit_papi_command, **kwargs)
360 self._api_command_list.append(
361 dict(api_name=csit_papi_command, api_args=kwargs))
364 def get_replies(self, err_msg="Failed to get replies."):
365 """Get replies from VPP Python API.
367 The replies are parsed into dict-like objects,
368 "retval" field is guaranteed to be zero on success.
370 :param err_msg: The message used if the PAPI command(s) execution fails.
372 :returns: Responses, dict objects with fields due to API and "retval".
374 :raises RuntimeError: If retval is nonzero, parsing or ssh error.
376 return self._execute(err_msg=err_msg)
378 def get_reply(self, err_msg="Failed to get reply."):
379 """Get reply from VPP Python API.
381 The reply is parsed into dict-like object,
382 "retval" field is guaranteed to be zero on success.
384 TODO: Discuss exception types to raise, unify with inner methods.
386 :param err_msg: The message used if the PAPI command(s) execution fails.
388 :returns: Response, dict object with fields due to API and "retval".
390 :raises AssertionError: If retval is nonzero, parsing or ssh error.
392 replies = self.get_replies(err_msg=err_msg)
393 if len(replies) != 1:
394 raise RuntimeError("Expected single reply, got {replies!r}".format(
398 def get_sw_if_index(self, err_msg="Failed to get reply."):
399 """Get sw_if_index from reply from VPP Python API.
401 Frequently, the caller is only interested in sw_if_index field
402 of the reply, this wrapper makes such call sites shorter.
404 TODO: Discuss exception types to raise, unify with inner methods.
406 :param err_msg: The message used if the PAPI command(s) execution fails.
408 :returns: Response, sw_if_index value of the reply.
410 :raises AssertionError: If retval is nonzero, parsing or ssh error.
412 reply = self.get_reply(err_msg=err_msg)
413 logger.info("Getting index from {reply!r}".format(reply=reply))
414 return reply["sw_if_index"]
416 def get_details(self, err_msg="Failed to get dump details."):
417 """Get dump details from VPP Python API.
419 The details are parsed into dict-like objects.
420 The number of details per single dump command can vary,
421 and all association between details and dumps is lost,
422 so if you care about the association (as opposed to
423 logging everything at once for debugging purposes),
424 it is recommended to call get_details for each dump (type) separately.
426 :param err_msg: The message used if the PAPI command(s) execution fails.
428 :returns: Details, dict objects with fields due to API without "retval".
431 return self._execute(err_msg)
434 def run_cli_cmd(node, cmd, log=True):
435 """Run a CLI command as cli_inband, return the "reply" field of reply.
437 Optionally, log the field value.
439 :param node: Node to run command on.
440 :param cmd: The CLI command to be run on the node.
441 :param log: If True, the response is logged.
445 :returns: CLI output.
450 err_msg = "Failed to run 'cli_inband {cmd}' PAPI command on host " \
451 "{host}".format(host=node['host'], cmd=cmd)
452 with PapiSocketExecutor(node) as papi_exec:
453 reply = papi_exec.add(cli, **args).get_reply(err_msg)["reply"]
455 logger.info("{cmd}:\n{reply}".format(cmd=cmd, reply=reply))
459 def dump_and_log(node, cmds):
460 """Dump and log requested information, return None.
462 :param node: DUT node.
463 :param cmds: Dump commands to be executed.
465 :type cmds: list of str
467 with PapiSocketExecutor(node) as papi_exec:
469 dump = papi_exec.add(cmd).get_details()
470 logger.debug("{cmd}:\n{data}".format(
471 cmd=cmd, data=pformat(dump)))
473 def _execute(self, err_msg="Undefined error message"):
474 """Turn internal command list into data and execute; return replies.
476 This method also clears the internal command list.
479 Do not use this method in L1 keywords. Use:
485 :param err_msg: The message used if the PAPI command(s) execution fails.
487 :returns: Papi responses parsed into a dict-like object,
488 with fields due to API (possibly including retval).
490 :raises RuntimeError: If the replies are not all correct.
492 vpp_instance = self.vpp_instance
493 local_list = self._api_command_list
494 # Clear first as execution may fail.
495 self._api_command_list = list()
497 for command in local_list:
498 api_name = command["api_name"]
499 papi_fn = getattr(vpp_instance.api, api_name)
502 reply = papi_fn(**command["api_args"])
503 except IOError as err:
504 # Ocassionally an error happens, try reconnect.
505 logger.warn("Reconnect after error: {err!r}".format(
507 self.vpp_instance.disconnect()
508 # Testing showes immediate reconnect fails.
510 self.vpp_instance.connect_sync("csit_socket")
511 logger.trace("Reconnected.")
512 reply = papi_fn(**command["api_args"])
513 except (AttributeError, IOError) as err:
514 raise_from(AssertionError(err_msg), err, level="INFO")
515 # *_dump commands return list of objects, convert, ordinary reply.
516 if not isinstance(reply, list):
519 dict_item = dictize(item)
520 if "retval" in dict_item.keys():
521 # *_details messages do not contain retval.
522 retval = dict_item["retval"]
524 # TODO: What exactly to log and raise here?
525 err = AssertionError("Retval {rv!r}".format(rv=retval))
526 # Lowering log level, some retval!=0 calls are expected.
527 # TODO: Expose level argument so callers can decide?
528 raise_from(AssertionError(err_msg), err, level="DEBUG")
529 replies.append(dict_item)
533 class PapiExecutor(object):
534 """Contains methods for executing VPP Python API commands on DUTs.
536 TODO: Remove .add step, make get_stats accept paths directly.
538 This class processes only one type of VPP PAPI methods: vpp-stats.
540 The recommended ways of use are (examples):
542 path = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
543 with PapiExecutor(node) as papi_exec:
544 stats = papi_exec.add(api_name='vpp-stats', path=path).get_stats()
546 print('RX interface core 0, sw_if_index 0:\n{0}'.\
547 format(stats[0]['/if/rx'][0][0]))
552 path_2 = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
553 with PapiExecutor(node) as papi_exec:
554 stats = papi_exec.add('vpp-stats', path=path_1).\
555 add('vpp-stats', path=path_2).get_stats()
557 print('RX interface core 0, sw_if_index 0:\n{0}'.\
558 format(stats[1]['/if/rx'][0][0]))
560 Note: In this case, when PapiExecutor method 'add' is used:
561 - its parameter 'csit_papi_command' is used only to keep information
562 that vpp-stats are requested. It is not further processed but it is
563 included in the PAPI history this way:
564 vpp-stats(path=['^/if', '/err/ip4-input', '/sys/node/ip4-input'])
565 Always use csit_papi_command="vpp-stats" if the VPP PAPI method
567 - the second parameter must be 'path' as it is used by PapiExecutor
571 def __init__(self, node):
574 :param node: Node to run command(s) on.
578 # Node to run command(s) on.
581 # The list of PAPI commands to be executed on the node.
582 self._api_command_list = list()
588 self._ssh.connect(self._node)
590 raise RuntimeError("Cannot open SSH connection to host {host} to "
591 "execute PAPI command(s)".
592 format(host=self._node["host"]))
595 def __exit__(self, exc_type, exc_val, exc_tb):
596 self._ssh.disconnect(self._node)
598 def add(self, csit_papi_command="vpp-stats", history=True, **kwargs):
599 """Add next command to internal command list; return self.
601 The argument name 'csit_papi_command' must be unique enough as it cannot
602 be repeated in kwargs.
604 :param csit_papi_command: VPP API command.
605 :param history: Enable/disable adding command to PAPI command history.
606 :param kwargs: Optional key-value arguments.
607 :type csit_papi_command: str
610 :returns: self, so that method chaining is possible.
614 PapiHistory.add_to_papi_history(
615 self._node, csit_papi_command, **kwargs)
616 self._api_command_list.append(dict(api_name=csit_papi_command,
620 def get_stats(self, err_msg="Failed to get statistics.", timeout=120):
621 """Get VPP Stats from VPP Python API.
623 :param err_msg: The message used if the PAPI command(s) execution fails.
624 :param timeout: Timeout in seconds.
627 :returns: Requested VPP statistics.
631 paths = [cmd['api_args']['path'] for cmd in self._api_command_list]
632 self._api_command_list = list()
634 stdout = self._execute_papi(
635 paths, method='stats', err_msg=err_msg, timeout=timeout)
637 return json.loads(stdout)
640 def _process_api_data(api_d):
641 """Process API data for smooth converting to JSON string.
643 Apply binascii.hexlify() method for string values.
645 :param api_d: List of APIs with their arguments.
647 :returns: List of APIs with arguments pre-processed for JSON.
651 def process_value(val):
654 :param val: Value to be processed.
656 :returns: Processed value.
657 :rtype: dict or str or int
659 if isinstance(val, dict):
660 for val_k, val_v in val.iteritems():
661 val[str(val_k)] = process_value(val_v)
663 elif isinstance(val, list):
664 for idx, val_l in enumerate(val):
665 val[idx] = process_value(val_l)
668 return binascii.hexlify(val) if isinstance(val, str) else val
670 api_data_processed = list()
672 api_args_processed = dict()
673 for a_k, a_v in api["api_args"].iteritems():
674 api_args_processed[str(a_k)] = process_value(a_v)
675 api_data_processed.append(dict(api_name=api["api_name"],
676 api_args=api_args_processed))
677 return api_data_processed
679 def _execute_papi(self, api_data, method='request', err_msg="",
681 """Execute PAPI command(s) on remote node and store the result.
683 :param api_data: List of APIs with their arguments.
684 :param method: VPP Python API method. Supported methods are: 'request',
686 :param err_msg: The message used if the PAPI command(s) execution fails.
687 :param timeout: Timeout in seconds.
692 :returns: Stdout from remote python utility, to be parsed by caller.
694 :raises SSHTimeout: If PAPI command(s) execution has timed out.
695 :raises RuntimeError: If PAPI executor failed due to another reason.
696 :raises AssertionError: If PAPI command(s) execution has failed.
700 raise RuntimeError("No API data provided.")
702 json_data = json.dumps(api_data) \
703 if method in ("stats", "stats_request") \
704 else json.dumps(self._process_api_data(api_data))
706 cmd = "{fw_dir}/{papi_provider} --method {method} --data '{json}'".\
708 fw_dir=Constants.REMOTE_FW_DIR, method=method, json=json_data,
709 papi_provider=Constants.RESOURCES_PAPI_PROVIDER)
711 ret_code, stdout, _ = self._ssh.exec_command_sudo(
712 cmd=cmd, timeout=timeout, log_stdout_err=False)
713 # TODO: Fail on non-empty stderr?
715 logger.error("PAPI command(s) execution timeout on host {host}:"
716 "\n{apis}".format(host=self._node["host"],
719 except Exception as exc:
720 raise_from(RuntimeError(
721 "PAPI command(s) execution on host {host} "
722 "failed: {apis}".format(
723 host=self._node["host"], apis=api_data)), exc)
725 raise AssertionError(err_msg)