virl2_client package

Python bindings for the Cisco VIRL 2 Network Simulation Platform

This file is part of VIRL 2

Copyright 2020 Cisco Systems Inc.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Subpackages

• virl2_client.models package
  • Interface
    • Interface.__init__()
    • Interface.as_dict()
    • Interface.bring_up()
    • Interface.degree()
    • Interface.is_connected()
    • Interface.links()
    • Interface.peer_interfaces()
    • Interface.peer_nodes()
    • Interface.remove_on_server()
    • Interface.shutdown()
    • Interface.discovered_ipv4
    • Interface.discovered_ipv6
    • Interface.discovered_mac_address
    • Interface.is_physical
    • Interface.lab_base_url
    • Interface.readbytes
    • Interface.readpackets
    • Interface.state
    • Interface.writebytes
    • Interface.writepackets
  • Lab
    • Lab.__init__()
    • Lab.add_node_local()
    • Lab.build_configurations()
    • Lab.cleanup_pyats_connections()
    • Lab.connect_two_nodes()
    • Lab.create_interface()
    • Lab.create_interface_local()
    • Lab.create_link()
    • Lab.create_link_local()
    • Lab.create_node()
    • Lab.details()
    • Lab.download()
    • Lab.find_nodes_by_tag()
    • Lab.get_link_by_interfaces()
    • Lab.get_link_by_nodes()
    • Lab.get_node_by_id()
    • Lab.get_node_by_label()
    • Lab.get_pyats_testbed()
    • Lab.has_converged()
    • Lab.import_lab()
    • Lab.interfaces()
    • Lab.is_active()
    • Lab.links()
    • Lab.need_to_wait()
    • Lab.nodes()
    • Lab.remove()
    • Lab.remove_interface()
    • Lab.remove_link()
    • Lab.remove_node()
    • Lab.remove_nodes()
    • Lab.start()
    • Lab.state()
    • Lab.stop()
    • Lab.sync()
    • Lab.sync_events()
    • Lab.sync_l3_addresses_if_outdated()
    • Lab.sync_layer3_addresses()
    • Lab.sync_pyats()
    • Lab.sync_states()
    • Lab.sync_states_if_outdated()
    • Lab.sync_statistics()
    • Lab.sync_statistics_if_outdated()
    • Lab.sync_topology_if_outdated()
    • Lab.update_lab()
    • Lab.wait_until_lab_converged()
    • Lab.wipe()
    • Lab.client_uuid
    • Lab.description
    • Lab.id
    • Lab.lab_base_url
    • Lab.notes
    • Lab.owner
    • Lab.session
    • Lab.statistics
    • Lab.title
  • Licensing
    • Licensing.__init__()
    • Licensing.cancel_reservation()
    • Licensing.complete_reservation()
    • Licensing.delete_reservation_confirmation_code()
    • Licensing.delete_reservation_return_code()
    • Licensing.deregister()
    • Licensing.disable_reservation_mode()
    • Licensing.discard_reservation()
    • Licensing.enable_reservation_mode()
    • Licensing.features()
    • Licensing.get_certificate()
    • Licensing.get_reservation_confirmation_code()
    • Licensing.get_reservation_return_code()
    • Licensing.install_certificate()
    • Licensing.register()
    • Licensing.register_renew()
    • Licensing.register_wait()
    • Licensing.release_reservation()
    • Licensing.remove_certificate()
    • Licensing.renew_authorization()
    • Licensing.request_reservation()
    • Licensing.reservation_mode()
    • Licensing.set_default_transport()
    • Licensing.set_transport()
    • Licensing.status()
    • Licensing.tech_support()
    • Licensing.update_features()
    • Licensing.wait_for_completed_authorization()
    • Licensing.wait_for_completed_registration()
    • Licensing.base_url
    • Licensing.max_wait
    • Licensing.wait_interval
  • Link
    • Link.__init__()
    • Link.as_dict()
    • Link.get_condition()
    • Link.has_converged()
    • Link.remove_condition()
    • Link.remove_on_server()
    • Link.set_condition()
    • Link.set_condition_by_name()
    • Link.start()
    • Link.stop()
    • Link.wait_until_converged()
    • Link.base_url
    • Link.interfaces
    • Link.lab_base_url
    • Link.node_a
    • Link.node_b
    • Link.nodes
    • Link.readbytes
    • Link.readpackets
    • Link.state
    • Link.writebytes
    • Link.writepackets
  • Node
    • Node.__init__()
    • Node.add_tag()
    • Node.console_key()
    • Node.create_interface()
    • Node.degree()
    • Node.extract_configuration()
    • Node.get_interface_by_label()
    • Node.get_interface_by_slot()
    • Node.has_converged()
    • Node.interfaces()
    • Node.is_active()
    • Node.is_booted()
    • Node.links()
    • Node.map_l3_addresses_to_interfaces()
    • Node.next_available_interface()
    • Node.peer_interfaces()
    • Node.peer_nodes()
    • Node.physical_interfaces()
    • Node.remove_on_server()
    • Node.remove_tag()
    • Node.run_pyats_command()
    • Node.run_pyats_config_command()
    • Node.start()
    • Node.stop()
    • Node.sync_layer3_addresses()
    • Node.tags()
    • Node.update()
    • Node.vnc_key()
    • Node.wait_until_converged()
    • Node.wipe()
    • Node.boot_disk_size
    • Node.config
    • Node.cpu_limit
    • Node.cpu_usage
    • Node.cpus
    • Node.data_volume
    • Node.disk_read
    • Node.disk_write
    • Node.image_definition
    • Node.lab_base_url
    • Node.label
    • Node.node_definition
    • Node.ram
    • Node.state
    • Node.x
    • Node.y
  • Submodules
  • virl2_client.models.authentication
    • Context
      • Context.__init__()
      • Context.base_url
      • Context.session
      • Context.uuid
    • TokenAuth
      • TokenAuth.__init__()
      • TokenAuth.authenticate()
      • TokenAuth.handle_401_unauthorized()
  • virl2_client.models.cl_pyats
    • PyatsDeviceNotFound
    • PyatsNotInstalled
    • ClPyats
      • ClPyats.__init__()
      • ClPyats.cleanup()
      • ClPyats.run_command()
      • ClPyats.run_config_command()
      • ClPyats.sync_testbed()
  • virl2_client.models.interface
    • Interface
      • Interface.__init__()
      • Interface.as_dict()
      • Interface.bring_up()
      • Interface.degree()
      • Interface.is_connected()
      • Interface.links()
      • Interface.peer_interfaces()
      • Interface.peer_nodes()
      • Interface.remove_on_server()
      • Interface.shutdown()
      • Interface.discovered_ipv4
      • Interface.discovered_ipv6
      • Interface.discovered_mac_address
      • Interface.is_physical
      • Interface.lab_base_url
      • Interface.readbytes
      • Interface.readpackets
      • Interface.state
      • Interface.writebytes
      • Interface.writepackets
  • virl2_client.models.lab
    • Lab
      • Lab.__init__()
      • Lab.add_node_local()
      • Lab.build_configurations()
      • Lab.cleanup_pyats_connections()
      • Lab.connect_two_nodes()
      • Lab.create_interface()
      • Lab.create_interface_local()
      • Lab.create_link()
      • Lab.create_link_local()
      • Lab.create_node()
      • Lab.details()
      • Lab.download()
      • Lab.find_nodes_by_tag()
      • Lab.get_link_by_interfaces()
      • Lab.get_link_by_nodes()
      • Lab.get_node_by_id()
      • Lab.get_node_by_label()
      • Lab.get_pyats_testbed()
      • Lab.has_converged()
      • Lab.import_lab()
      • Lab.interfaces()
      • Lab.is_active()
      • Lab.links()
      • Lab.need_to_wait()
      • Lab.nodes()
      • Lab.remove()
      • Lab.remove_interface()
      • Lab.remove_link()
      • Lab.remove_node()
      • Lab.remove_nodes()
      • Lab.start()
      • Lab.state()
      • Lab.stop()
      • Lab.sync()
      • Lab.sync_events()
      • Lab.sync_l3_addresses_if_outdated()
      • Lab.sync_layer3_addresses()
      • Lab.sync_pyats()
      • Lab.sync_states()
      • Lab.sync_states_if_outdated()
      • Lab.sync_statistics()
      • Lab.sync_statistics_if_outdated()
      • Lab.sync_topology_if_outdated()
      • Lab.update_lab()
      • Lab.wait_until_lab_converged()
      • Lab.wipe()
      • Lab.client_uuid
      • Lab.description
      • Lab.id
      • Lab.lab_base_url
      • Lab.notes
      • Lab.owner
      • Lab.session
      • Lab.statistics
      • Lab.title
  • virl2_client.models.licensing
    • Licensing
      • Licensing.__init__()
      • Licensing.cancel_reservation()
      • Licensing.complete_reservation()
      • Licensing.delete_reservation_confirmation_code()
      • Licensing.delete_reservation_return_code()
      • Licensing.deregister()
      • Licensing.disable_reservation_mode()
      • Licensing.discard_reservation()
      • Licensing.enable_reservation_mode()
      • Licensing.features()
      • Licensing.get_certificate()
      • Licensing.get_reservation_confirmation_code()
      • Licensing.get_reservation_return_code()
      • Licensing.install_certificate()
      • Licensing.register()
      • Licensing.register_renew()
      • Licensing.register_wait()
      • Licensing.release_reservation()
      • Licensing.remove_certificate()
      • Licensing.renew_authorization()
      • Licensing.request_reservation()
      • Licensing.reservation_mode()
      • Licensing.set_default_transport()
      • Licensing.set_transport()
      • Licensing.status()
      • Licensing.tech_support()
      • Licensing.update_features()
      • Licensing.wait_for_completed_authorization()
      • Licensing.wait_for_completed_registration()
      • Licensing.base_url
      • Licensing.max_wait
      • Licensing.wait_interval
  • virl2_client.models.link
    • Link
      • Link.__init__()
      • Link.as_dict()
      • Link.get_condition()
      • Link.has_converged()
      • Link.remove_condition()
      • Link.remove_on_server()
      • Link.set_condition()
      • Link.set_condition_by_name()
      • Link.start()
      • Link.stop()
      • Link.wait_until_converged()
      • Link.base_url
      • Link.interfaces
      • Link.lab_base_url
      • Link.node_a
      • Link.node_b
      • Link.nodes
      • Link.readbytes
      • Link.readpackets
      • Link.state
      • Link.writebytes
      • Link.writepackets
  • virl2_client.models.node
    • Node
      • Node.__init__()
      • Node.add_tag()
      • Node.console_key()
      • Node.create_interface()
      • Node.degree()
      • Node.extract_configuration()
      • Node.get_interface_by_label()
      • Node.get_interface_by_slot()
      • Node.has_converged()
      • Node.interfaces()
      • Node.is_active()
      • Node.is_booted()
      • Node.links()
      • Node.map_l3_addresses_to_interfaces()
      • Node.next_available_interface()
      • Node.peer_interfaces()
      • Node.peer_nodes()
      • Node.physical_interfaces()
      • Node.remove_on_server()
      • Node.remove_tag()
      • Node.run_pyats_command()
      • Node.run_pyats_config_command()
      • Node.start()
      • Node.stop()
      • Node.sync_layer3_addresses()
      • Node.tags()
      • Node.update()
      • Node.vnc_key()
      • Node.wait_until_converged()
      • Node.wipe()
      • Node.boot_disk_size
      • Node.config
      • Node.cpu_limit
      • Node.cpu_usage
      • Node.cpus
      • Node.data_volume
      • Node.disk_read
      • Node.disk_write
      • Node.image_definition
      • Node.lab_base_url
      • Node.label
      • Node.node_definition
      • Node.ram
      • Node.state
      • Node.x
      • Node.y
    • flatten()
  • virl2_client.models.node_image_definitions
    • NodeImageDefinitions
      • NodeImageDefinitions.__init__()
      • NodeImageDefinitions.create_image_definition()
      • NodeImageDefinitions.download_image_definition()
      • NodeImageDefinitions.download_image_file_list()
      • NodeImageDefinitions.download_node_definition()
      • NodeImageDefinitions.image_definitions()
      • NodeImageDefinitions.image_definitions_for_node_definition()
      • NodeImageDefinitions.node_definitions()
      • NodeImageDefinitions.remove_dropfolder_image()
      • NodeImageDefinitions.remove_image_definition()
      • NodeImageDefinitions.remove_node_definition()
      • NodeImageDefinitions.upload_image_definition()
      • NodeImageDefinitions.upload_image_file()
      • NodeImageDefinitions.upload_node_definition()
      • NodeImageDefinitions.session
    • read_file_as_chunks()

Submodules

virl2_client.exceptions

exception virl2_client.exceptions.InterfaceNotFound

Bases: Exception

exception virl2_client.exceptions.LabNotFound

Bases: Exception

exception virl2_client.exceptions.LinkNotFound

Bases: Exception

exception virl2_client.exceptions.NodeNotFound

Bases: Exception

virl2_client.utils

exception virl2_client.utils.TextFsmNotInstalled

Bases: Exception

class virl2_client.utils.TextFsmTemplateHelper

Bases: object

__init__()

add_line(line)

add_numeric_token(name)

add_token(name, pattern)

clear()

render()

virl2_client.utils.get_offsets_for_keywords(title)

virl2_client.utils.parse_interfaces(get_offsets_for_keywords, parse_line, result)

virl2_client.utils.parse_line(line, keys, offsets)

virl2_client.utils.parse_ping(result)

virl2_client.utils.parse_with_textfsm_template(template, cli_result)

virl2_client.utils.splice_interface_ip_into_config(config, remote, ip_address, netmask)

virl2_client.virl2_client

exception virl2_client.virl2_client.InitializationError

Bases: Exception

class virl2_client.virl2_client.ClientLibrary(url=None, username=None, password=None, ssl_verify=True, raise_for_auth_failure=False, allow_http=False)

Bases: object

Initializes a ClientLibrary instance. Note that ssl_verify can also be a string that points to a cert (see class documentation).

Parameters:

• url (str) – URL of controller. It’s also possible to pass the URL via the VIRL2_URL environment variable. If no protocol scheme is provided, “https:” is used.

• username (str) – Username of the user to authenticate

• password (str) – Password of the user to authenticate

• ssl_verify (bool) – SSL controller certificate verification

• raise_for_auth_failure (bool) – Raise an exception if unable to connect to server (use for scripting scenarios)

• allow_http (bool) – If set, a https URL will not be enforced

Raises:

InitializationError – If no URL is provided or authentication fails or host can’t be reasched

__init__(url=None, username=None, password=None, ssl_verify=True, raise_for_auth_failure=False, allow_http=False)

Constructor method

all_labs(show_all=False)

Retrieves a list of all defined labs.

Parameters:

show_all (bool) – Whether to get only labs owned by the admin or all user labs

Returns:

A list of lab objects

Return type:

list[models.Lab]

check_controller_version(controller_version=None)

Checks remote controller version against current client version (specified in self.VERSION) and against controller version blacklist (specified in self.INCOMPATIBLE_CONTROLLER_VERSIONST) and raises exception if version are incompatible or prints warning if version are not in exact match.

Return type:

None

create_lab(title=None)

Creates an empty lab with the given name. If no name is given, then the created lab ID is set as the name.

Note that the lab will be auto-syncing according to the Client Librarie’s auto-sync setting when created. The lab has a property to override this on a per-lab basis.

Example:

lab = client_library.create_lab()
print(lab.id)
lab.create_node("r1", "iosv", 50, 100)

Parameters:

title (str) – The Lab name (or title)

Returns:

A Lab instance

Return type:

models.Lab

find_labs_by_title(title)

Return a list of labs which match the given title

Parameters:

title (str) – The title to search for

Returns:

A list of lab objects which match the title specified

Return type:

list[models.Lab]

get_diagnostics()

Returns the controller diagnostic data as JSON

Returns:

diagnostic data

Return type:

str

get_host()

Returns the hostname of the session to the controller.

Returns:

A hostname

Return type:

str

get_lab_list(show_all=False)

Returns list of all lab IDs.

Parameters:

show_all (bool) – Whether to get only labs owned by the admin or all user labs

Returns:

a list of Lab IDs

Return type:

list[str]

get_local_lab(lab_id)

import_lab(topology, title, offline=False)

Imports an existing topology from a string.

Parameters:

• topology (str) – Topology representation as a string

• title (str) – Title of the lab

• offline (bool) – whether the ClientLibrary should import the lab locally. The topology parameter has to be a JSON string in this case. This can not be XML or YAML representation of the lab. Compatible JSON from GET /labs/{lab_id}/topology.

Returns:

A Lab instance

Return type:

models.Lab

Raises:

• ValueError – if there’s no lab ID in the API response

• requests.exceptions.HTTPError – if there was a transport error

import_lab_from_path(topology, title=None)

Imports an existing topology from a file / path.

Parameters:

• topology (str) – Topology filename / path

• title (str) – Title of the lab

Returns:

A Lab instance

Return type:

models.Lab

import_sample_lab(title)

Imports a built-in sample lab (this will be going away in the future).

Parameters:

title (str) – Sample lab name with extension

Returns:

A Lab instance

Return type:

models.Lab

is_system_ready(wait=False, max_wait=60, sleep=5)

is_system_ready reports whether the system is ready or not.

Parameters:

• wait (int) – if this is true, the call will block until it’s ready

• max_wait – wait for a maximum of ‘max_wait’ seconds

• sleep – wait for ‘sleep’ seconds between tries

Returns:

ready state

Return type:

bool

join_existing_lab(lab_id, sync_lab=True)

Creates a new ClientLibrary lab instance that is retrieved from the controller.

If sync_lab is set to true, then synchronize current lab by applying the changes that were done in UI or in another ClientLibrary session.

Join preexisting lab:

lab = client_library.join_existing_lab("2e6a18")

Parameters:

• lab_id (str) – The lab ID to be removed.

• sync_lab (bool) – Syncronize changes.

Returns:

A Lab instance

Return type:

models.Lab

local_labs()

remove_lab(lab_id)

Use carefully, it removes a given lab:

client_library.remove_lab("1f6cd7")

Parameters:

lab_id (str) – The lab ID to be removed.

system_info()

Get information about the system where the application runs. Can be called without authentication.

Returns:

system information json

Return type:

dict

wait_for_lld_connected()

Waits until the controller has a compute node connected. (Deprecated)

INCOMPATIBLE_CONTROLLER_VERSIONS = []

VERSION = 2.1.0

property session

Returns the used Requests session object

Returns:

The Requests session object

Return type:

Requests.Session

class virl2_client.virl2_client.Version(version_str)

Bases: object

__init__(version_str)

major_differs(other)

minor_differs(other)

minor_or_patch_differs(other)

patch_differs(other)

major

minor

patch

version_str