VIRL ² API Client

Subpackages

• VIRL ² Modules and Models
  • Authentication Module
    • Context
      • Context.__init__()
      • Context.base_url
      • Context.session
      • Context.uuid
    • TokenAuth
      • TokenAuth.__init__()
      • TokenAuth.authenticate()
      • TokenAuth.handle_401_unauthorized()
  • pyATS Module
    • PyatsDeviceNotFound
    • PyatsNotInstalled
    • ClPyats
      • ClPyats.__init__()
      • ClPyats.cleanup()
      • ClPyats.run_command()
      • ClPyats.run_config_command()
      • ClPyats.sync_testbed()
  • Interface Model
    • 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 Model
    • 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
  • Link Model
    • 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 Model
    • 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()
  • Node and Image Definitions Model
    • 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()

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

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)

ClientLibrary

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