virl2_client.models package

Submodules

virl2_client.models.authentication

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

Bases: object

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

Bases: AuthBase

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

__init__(client_library)
authenticate()
handle_401_unauthorized(resp, **kwargs)
logout(clear_all_sessions=False)

virl2_client.models.cl_pyats

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, hostname=None)

Bases: object

__init__(lab, hostname=None)

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 \n no shut.

Parameters:

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

  • hostname (str) – Force hostname/ip and port for console terminal server

Raises:
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 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

virl2_client.models.groups

virl2_client.models.interface

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

Bases: object

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

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) – the type of the interface, defaults to “physical”

as_dict()
bring_up()
degree()

Returns the link between this interface and another.

Parameters:

other_interface (models.Interface) – the other interface

Returns:

A Link

Return type:

models.Link

is_connected()
peer_interfaces()
peer_nodes()
remove_on_server()
shutdown()
property connected

Whether the interface is connected to a link.

property discovered_ipv4
property discovered_ipv6
property discovered_mac_address
property is_physical
property lab_base_url

Is link if connected, otherwise None.

property peer_interface
property peer_node
property physical

Whether the interface is physical.

property readbytes
property readpackets
property state
property writebytes
property writepackets

virl2_client.models.lab

class virl2_client.models.lab.Lab(title, lab_id, context, username, password, auto_sync=True, auto_sync_interval=1.0, wait=True, wait_max_iterations=500, wait_time=5, hostname=None)

Bases: object

__init__(title, lab_id, context, username, password, auto_sync=True, auto_sync_interval=1.0, wait=True, wait_max_iterations=500, wait_time=5, hostname=None)

A VIRL2 lab network topology. Contains nodes, links and interfaces.

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

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

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

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

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

  • wait (bool) – Wait for convergence on backend

  • wait_max_iterations (int) – Maximum number of tries or calls for convergence

  • wait_time (int) – Time to sleep between calls for convergence on backend

  • hostname (str) – Force hostname/ip and port for pyATS console terminal server

add_node_local(node_id, label, node_definition, image_definition, config, x, y, ram=0, cpus=0, cpu_limit=100, 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:

  • node1 (models.Node) – the first node object

  • node2 (models.Node) – the second node object

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, **kwargs)

Creates a node in the lab with the given parameters.

Parameters:

  • label (str) – Label

  • node_definition – Node definition to use

  • x (int) – x coordinate

  • y (int) – y coordinate

  • 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 nodes identified by the given tag.

Parameters:

tag (str) – tag of the nodes to be returned

Returns:

a list of nodes

Return type:

List[Node]

get_interface_by_id(interface_id)

Returns the interface identified by the ID.

Parameters:

interface_id (str) – ID of the interface to be returned

Returns:

An Interface object

Return type:

models.Interface

Raises:

InterfaceNotFound – If interface not found

Returns the link identified by the ID.

Parameters:

link_id (str) – ID of the interface to be returned

Returns:

A Link object

Return type:

models.Link

Raises:

LinkNotFound – If interface not found

DEPRECATED

Returns the link identified by two interface objects.

Deprecated. Use Interface.get_link_to to get link.

Parameters:

  • iface1 (models.Interface) – the first interface

  • iface2 (models.Interface) – the second interface

Returns:

the link between the interfaces

Return type:

models.Link

Raises:

LinkNotFound – If no such link exists

DEPRECATED

Returns ONE of the links identified by two node objects.

Deprecated. Use Node.get_link_to to get one link or Node.get_links_to to get all links.

Parameters:

  • node1 (models.Node) – the first node

  • node2 (models.Node) – the second node

Returns:

one of links between the nodes

Return type:

models.Link

Raises:

LinkNotFound – If no such link exists

get_node_by_id(node_id)

Returns the node identified by the ID.

Parameters:

node_id (str) – ID of the node to be returned

Returns:

A Node object

Return type:

models.Node

Raises:

NodeNotFound – If node not found

get_node_by_label(label)

Returns the node identified by the label.

Parameters:

label (str) – label of the node to be returned

Returns:

A Node object

Return type:

models.Node

Raises:

NodeNotFound – If node not found

get_pyats_testbed(hostname=None)

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)
Parameters:

hostname (str) – Force hostname/ip and port for console terminal server

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[Interface]

is_active()

Returns whether the lab is started.

Returns:

Whether the lab is started

Return type:

bool

Returns the list of links in the lab.

Returns:

A list of Link objects

Return type:

List[Link]

need_to_wait(local_wait)
nodes()

Returns the list of nodes in the lab.

Returns:

A list of Node objects

Return type:

List[Node]

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 (Interface) – the interface

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

Removes a link from the lab.

Parameters:

  • link (Link) – the link

  • 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 (Node) – the node

  • 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=None, exclude_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) – DEPRECATED, does the opposite of what is expected: disables syncing node configuration when True

  • exclude_configurations (bool) – disable syncing node configuration

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)
update_lab_groups(group_list)

Modifies lab / group association

Parameters:

group_list – list of objects consisting of group id and permission

Return type:

group_list: List[Dict[str, str]]

Returns:

updated objects consisting of group id and permission

Return type:

List[Dict[str, str]]

wait_until_lab_converged(max_iterations=None, wait_time=None)

Wait until lab converge.

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 description

Returns the description of the lab.

Returns:

The lab name

Return type:

str

property groups

Returns the groups this lab is associated with.

Returns:

associated groups

Return type:

List[Dict[str, 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 owner

Returns the owner of the lab.

Returns:

A username

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

virl2_client.models.licensing

class virl2_client.models.licensing.Licensing(context)

Bases: object

__init__(context)
cancel_reservation()

Cancel reservation request without completing it.

complete_reservation(authorization_code)

Complete reservation by installing authorization code from SSMS.

delete_reservation_confirmation_code()

Remove the confirmation code.

delete_reservation_return_code()

Remove the return code.

deregister()

Request deregistration from the current SSMS.

disable_reservation_mode()

Disable reservation mode in unregistered agent.

discard_reservation(data)

Discard a reservation authorization code for an already cancelled reservation request.

enable_reservation_mode()

Enable reservation mode in unregistered agent.

features()

Get current licensing features.

get_certificate()

Get the currently installed licensing public certificate.

get_reservation_confirmation_code()

Get the confirmation code.

get_reservation_return_code()

Get the return code.

install_certificate(cert)

Setup a licensing public certificate for internal deployment of an unregistered product instance.

register(token, reregister=False)

Setup licensing registration.

register_renew()

Request a renewal of licensing registration against current SSMS.

register_wait(token, reregister=False)

Setup licensing registrations and wait for registration status to be COMPLETED and authorization status to be IN_COMPLIANCE.

release_reservation()

Return a completed reservation.

remove_certificate()

Clear any licensing public certificate for internal deployment of an unregistered product instance.

renew_authorization()

Renew licensing authorization with the backend.

request_reservation()

Initiate reservation by generating request code and message to the user.

reservation_mode(data)

Enable or disable reservation mode in unregistered agent.

set_default_transport()

Setup licensing transport configuration to default values.

set_product_license(product_license)

Setup a product license.

set_transport(ssms, proxy_server=None, proxy_port=None)

Setup licensing transport configuration.

status()

Get current licensing configuration and status.

tech_support()

Get current licensing tech support.

update_features(features)

Update licensing feature’s explicit count in reservation mode.

wait_for_status(what, *target_status)

Repeatedly check licensing registration or authorization status, until status matches one of the expected statuses or timeout is reached. :param what: “registration”, “authorization” or other status in licensing API. :param target_status: One or more expected statuses. :type what: str :type target_status: str :raises RuntimeError: When timeout is reached.

property base_url
max_wait = 30
wait_interval = 1.5

virl2_client.models.node

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

Bases: object

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

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)

  • cpu_limit (int) – CPU limit (default at 100%)

  • 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[str, str]) – List of tags

add_tag(tag)
console_key()
console_logs(console_id, lines=None)
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)

Returns one link between this node and another.

Parameters:

other_node (models.Node) – the other node

Returns:

a link

Return type:

models.Link

Returns all links between this node and another.

Parameters:

other_node (models.Node) – the other node

Returns:

a list of links

Return type:

list[models.Link]

has_converged()
interfaces()
is_active()
is_booted()
Returns:

list of links

Return type:

list[models.Link]

map_l3_addresses_to_interfaces(mapping)
next_available_interface()

Returns the next available physical interface on this node.

Note: On XR 9000v, the first two physical interfaces are marked as “do not use”… Only the third physical interface can be used to connect to other nodes!

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 from 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)
vnc_key()
wait_until_converged(max_iterations=None, wait_time=None)
wipe(wait=False)
property boot_disk_size
property compute_id
property config
property cpu_limit
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_image_definitions

virl2_client.models.system

virl2_client.models.users