VIRL 2 Modules and Models

Authentication Module

class virl2_client.models.authentication.Context(base_url, requests_session=None, client_uuid=None)

Bases: object

__init__(base_url, requests_session=None, client_uuid=None)
property base_url
property session
property uuid
class virl2_client.models.authentication.TokenAuth(client_library)

Bases: AuthBase

Inspired by: http://docs.python-requests.org/en/v2.9.1/user/authentication/?highlight=AuthBase#new-forms-of-authentication

__init__(client_library)
authenticate()
handle_401_unauthorized(resp, **kwargs)

pyATS Module

exception virl2_client.models.cl_pyats.PyatsDeviceNotFound

Bases: Exception

exception virl2_client.models.cl_pyats.PyatsNotInstalled

Bases: Exception

class virl2_client.models.cl_pyats.ClPyats(lab)

Bases: object

Creates a pyATS object that can be used to run commands against a device either in exec mode show version or in configuration mode interface gi0/0\\nno shut.

Parameters:

lab (models.Lab) – The lab which should be used with pyATS

Raises:
__init__(lab)

Constructor method

cleanup()

cleans up the pyATS connections

run_command(node_label, command)

Run a command on the device in exec mode

Parameters:

  • node_label (str) – the label / title of the device

  • command (str) – the command to be run in exec mode

Returns:

The output from the device

Return type:

str

run_config_command(node_label, command)

Run a command on the device in configure mode. pyATS handles the change into configure mode automatically.

Parameters:

  • node_label (str) – the label / title of the device

  • command (str) – the command to be run in exec mode

Returns:

The output from the device

Return type:

str

sync_testbed(username, password)

Syncs the the testbed from the server. Note that this will always fetch the latest topology data from the server.

Parameters:

  • username (str) – the username that will be inserted into the testbed data

  • password (str) – the password that will be inserted into the testbed data

Interface Model

class virl2_client.models.interface.Interface(iid, node, label, slot, iface_type='physical')

Bases: object

A VIRL2 network interface, part of a node.

Parameters:

  • iid (str) – interface ID

  • node (models.Node) – node object

  • label (str) – the label of the interface

  • slot (int) – the slot of the interface

  • iface_type (str, optional) – the type of the interface, defaults to “physical”

__init__(iid, node, label, slot, iface_type='physical')

Constructor method

as_dict()
bring_up()
degree()
is_connected()
peer_interfaces()
peer_nodes()
remove_on_server()
shutdown()
property discovered_ipv4
property discovered_ipv6
property discovered_mac_address
property is_physical
property lab_base_url
property readbytes
property readpackets
property state
property writebytes
property writepackets

Lab Model

class virl2_client.models.lab.Lab(title, lab_id, context, username, password, auto_sync=True, auto_sync_interval=1.0, wait=True)

Bases: object

A VIRL2 lab network topology. Contains nodes, links and interfaces. Initializes a Lab instance.

Parameters:

  • title (str) – Name / title of the lab

  • lab_id (str) – A lab ID

  • context (Context) – The context of the ClientLibrary that holds the connection data to the server

  • auto_sync (bool) – Should local changes sync to the server automatically

  • auto_sync_interval (int) – Interval to auto sync in seconds

  • wait – Wait for convergence on backend

__init__(title, lab_id, context, username, password, auto_sync=True, auto_sync_interval=1.0, wait=True)

Constructor method

add_node_local(node_id, label, node_definition, image_definition, config, x, y, ram=0, cpus=0, data_volume=0, boot_disk_size=0, tags=None)

Helper function to add a node to the client library.

build_configurations()

Build basic configurations for all nodes in the lab which do not already have a configuration and also do support configuration building.

cleanup_pyats_connections()

Closes and cleans up connection that pyATS might still hold.

connect_two_nodes(node1, node2)

Convenience method to connect two nodes within a lab.

Parameters:
Returns:

the created link

Return type:

models.Link

create_interface(node, slot=None, wait=None)

Create an interface in the specified slot or, if no slot is given, in the next available slot.

Parameters:

  • node (models.Node) – The node on which the interface is created

  • slot (int) – (optional)

  • wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

Returns:

The newly created interface

Return type:

models.Interface

create_interface_local(iface_id, label, node, slot, iface_type='physical')

Helper function to create an interface in the client library.

Creates a link between two interfaces

Parameters:

  • i1 (models.Interface) – the first interface object

  • i2 (models.Interface) – the second interface object

  • wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

Returns:

the created link

Return type:

models.Link

Helper function to create a link in the client library.

create_node(label, node_definition, x=0, y=0, wait=None, populate_interfaces=False)

Creates a node in the lab with the given parameters.

Parameters:

  • label (str) – Label

  • node_definition – Node definition to use

  • x (int) – x co-ordinate

  • y (int) – y co-ordinate

  • wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

  • populate_interfaces – automatically create pre-defined number of interfaces on node creation

Returns:

a Node object

Return type:

models.Node

details()

Returns the lab details (including state) of the lab.

Returns:

The detailed lab state

Return type:

dict

download()

Download the lab from the server in YAML format.

Returns:

The lab in YAML format

Return type:

str

find_nodes_by_tag(tag)

Returns the node identified by the given tag.

Parameters:

tag (str) –

Returns:

a list of tags

Return type:

list

Returns the link identified by two interfaces.

Parameters:

  • iface1 (str) – node id of first node

  • iface2 (str) – node id of second node

Returns:

A Link object

Return type:

models.Link

Raises:

LinkNotFound – if link not found

Returns the link identified by two nodes.

Parameters:

  • node1 (str) – node id of first node

  • node2 (str) – node id of second node

Returns:

A Link object

Return type:

models.Link

Raises:

LinkNotFound – if link not found

get_node_by_id(node_id)

Returns the node identified by the node_id.

Parameters:

node_id (str) –

Returns:

A Node object

Return type:

models.Node

Raises:

KeyError – if node not found

get_node_by_label(label)

Returns the node identified by the label.

Parameters:

label (str) –

Returns:

A Node object

Return type:

models.Node

Raises:

NodeNotFound – if node not found

get_pyats_testbed()

Return lab’s pyATS YAML testbed. Example usage:

from pyats.topology import loader

lab = client_library.join_existing_lab("lab_1")
testbed_yaml = lab.get_pyats_testbed()

testbed = loader.load(io.StringIO(testbed_yaml))

# wait for lab to be ready
lab.wait_until_lab_converged()

aetest.main(testbed=testbed)
Returns:

The pyATS testbed for the lab in YAML format

Return type:

str

has_converged()
import_lab(topology)
interfaces()

Returns the list of interfaces in the lab.

Returns:

A list of Interface objects

Return type:

list

is_active()

Returns if the lab is running.

Returns the list of links in the lab.

Returns:

A list of Link objects

Return type:

list

need_to_wait(local_wait)
nodes()

Returns the list of nodes in the lab.

Returns:

A list of Node objects

Return type:

list

remove()

Removes the lab from the server. The lab has to be stopped and wiped for this to work.

Use carefully, it removes current lab:

lab.remove()
remove_interface(iface, wait=None)

Removes an interface from the lab.

Parameters:

  • iface (str) – the interface ID

  • wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

Removes a link from the lab.

Parameters:

  • link (str) – the link ID

  • wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

remove_node(node, wait=None)

Removes a node from the lab.

Parameters:

  • node (str) – the node id

  • wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

remove_nodes(wait=None)

Remove all nodes from the lab.

Parameters:

wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

start(wait=None)

Start all the nodes and links in the lab.

Parameters:

wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

state()

Returns the state of the lab.

Returns:

The state as text

Return type:

str

stop(wait=None)

Stops all the nodes and links in the lab.

Parameters:

wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

sync(topology_only=True, with_node_configurations=False)

Synchronize current lab applying the changes that were done in UI or in another ClientLibrary session:

lab.sync()
Parameters:

  • topology_only (bool) – do not sync statistics and IP addresses

  • with_node_configurations (bool) – also sync the configuration of the nodes itself

sync_events()
sync_l3_addresses_if_outdated()
sync_layer3_addresses()

Syncs all layer 3 IP addresses from the backend server.

sync_pyats()
sync_states()

Sync all the states of the various elements with the back end server.

sync_states_if_outdated()
sync_statistics()

Retrieve the simulation statistic data from the back end server.

sync_statistics_if_outdated()
sync_topology_if_outdated()
update_lab(topology, exclude_configurations)
wait_until_lab_converged(max_iterations=500)

Wait until all the lab nodes have booted.

wipe(wait=None)

Wipe all the nodes and links in the lab.

Parameters:

wait (bool) – Wait for convergence (if left at default, the lab wait property takes precedence)

property client_uuid

Returns the client UUID This random ID identifies a client session.

Returns:

A UUID4

Return type:

str

property description

Returns the description of the lab.

Returns:

The lab name

Return type:

str

property id

Returns the ID of the lab (a 6 digit hex string).

Returns:

The Lab ID

Return type:

str

property lab_base_url
property notes

Returns the notes of the lab.

Returns:

The lab name

Return type:

str

property session

Returns the Requests session from the given context.

Returns:

A Session

Return type:

Requests.Session

property statistics

Returns some statistics about the lab.

Returns:

A dictionary with stats of the lab

Return type:

dict

property title

Returns the title of the lab.

Returns:

The lab name

Return type:

str

Node Model

class virl2_client.models.node.Node(lab, nid, label, node_definition, image_definition, config, x, y, ram, cpus, data_volume, boot_disk_size, tags)

Bases: object

A VIRL2 Node object. Typically a virtual machine representing a router, switch or server.

Parameters:

  • lab (models.Lab) – the Lab this nodes belongs to

  • nid (str) – the Node ID

  • node_definition (str) – The node definition of this node

  • image_definition (str) – The image definition of this node

  • config (str) – The day0 configuration of this node

  • x (int) – X coordinate on topology canvas

  • y (int) – Y coordinate on topology canvas

  • ram (int) – memory of node in MiB (if applicable)

  • cpus (int) – Amount of CPUs in this node (if applicable)

  • data_volume (int) – Size in GiB of 2nd HDD (if > 0)

  • boot_disk_size (int) – Size in GiB of boot disk (will expand to this size)

  • tags (list) – List of tags List[str, str]

__init__(lab, nid, label, node_definition, image_definition, config, x, y, ram, cpus, data_volume, boot_disk_size, tags)

Constructor method

add_tag(tag)
create_interface(slot=None, wait=False)

Create an interface in the specified slot or, if no slot is given, in the next available slot.

Parameters:

  • slot (int) – (optional)

  • wait (bool) – Wait for the creation

Returns:

The newly created interface

Return type:

models.Interface

degree()
extract_configuration()
get_interface_by_label(label)
get_interface_by_slot(slot)
has_converged()
interfaces()
is_active()
is_booted()
map_l3_addresses_to_interfaces(mapping)
next_available_interface()

Returns the next available interface on this node.

Returns:

an interface or None, if all existing ones are connected

Return type:

models.interface

peer_interfaces()
peer_nodes()
physical_interfaces()
remove_on_server()
remove_tag(tag)
run_pyats_command(command)

Run a pyATS command in exec mode.

Parameters:

command (str) – the command (like “show version”)

Returns:

the output from the device

Return type:

str

run_pyats_config_command(command)

Run a pyATS command in config mode.

Parameters:

command (str) – the command (like “interface gi0”)

Returns:

the output from the device

Return type:

str

start(wait=False)
stop(wait=False)
sync_layer3_addresses()

Acquire all L3 addresses form the controller. For this to work, the device has to be attached to the external network in bridge mode and must run DHCP to acquire an IP address.

tags()

Returns the tags set on this node

update(node_data, exclude_configurations)
wait_until_converged(max_iterations=500)
wipe(wait=False)
property boot_disk_size
property config
property cpu_usage
property cpus
property data_volume
property disk_read
property disk_write
property image_definition
property lab_base_url
property label
property node_definition
property ram
property state
property x
property y
virl2_client.models.node.flatten(iterable, /)

Alternative chain() constructor taking a single iterable argument that evaluates lazily.

Node and Image Definitions Model

class virl2_client.models.node_image_definitions.NodeImageDefinitions(context)

Bases: object

VIRL2 Definition classes to specify a node VM and associated disk images.

Parameters:

context (authentication.Context) – the authentication context to use

__init__(context)

Constructor method

create_image_definition(image_id, node_definition_id, label, disk_image)

Creates a new image definition.

Example:

client_library.definitions.create_image_definition("test-1", "iosv", "test", "test.img")
Parameters:

  • image_id (str) – the ID of the new image definition

  • node_definition_id (str) – the node definition ID for this image definition

  • label (str) – the label of the new image definition

  • disk_image (str) – the name of the .qcow2 disk image (must exist on server)

download_image_definition(definition_id)

Example:

client_library.definitions.download_image_definition("iosv-158-3")
Parameters:

definition_id (str) – the node definition ID

Returns:

the image definition as JSON

Return type:

str

download_image_file_list()
download_node_definition(definition_id)

Returns the node definition for a given definition ID

Example:

client_library.definitions.download_node_definition("iosv")
Parameters:

definition_id (str) –

Returns:

the node definition as JSON

Return type:

str

image_definitions()
image_definitions_for_node_definition(definition_id)

Returns the image definition for a given node definition

example:

client_library.definitions.image_definitions_for_node_definition("iosv")
Parameters:

definition_id –

Returns:

the image definition as JSON

Return type:

str

node_definitions()
remove_dropfolder_image(filename)
remove_image_definition(definition_id)

Removes the image definition with the given ID.

Example:

client_library.definitions.remove_image_definition("iosv-158-3-custom")
Parameters:

definition_id (str) – the image definition ID to remove

remove_node_definition(definition_id)

Removes the node definition with the given ID.

Example:

client_library.definitions.remove_node_definition("iosv-custom")
Parameters:

definition_id (str) – the definition ID to delete

upload_image_definition(definition_id, body)
upload_image_file(filename, rename=None, chunk_size_mb=10)
Parameters:

  • filename (str) – the path of the image to upload

  • rename (str) – Optional filename to rename to

  • chunk_size_mb (int) – Optional size of upload chunk (mb)

upload_node_definition(definition_id, body)
property session

Returns the used Requests session object.

Returns:

The Requests session object

Return type:

Requests.Session

virl2_client.models.node_image_definitions.read_file_as_chunks(file_object, total_size=None, chunk_size_mb=10)