virl2_client.models package

This package contains the VIRL2 client library models for labs, nodes, interfaces and links. It also contains classes for node and image definition and helper classes for automation and authentication.

class virl2_client.models.Annotation(lab: Lab, annotation_id: str, annotation_type: AnnotationTypeString)

Bases: object

__init__(lab: Lab, annotation_id: str, annotation_type: AnnotationTypeString) → None

A VIRL2 lab annotation.

Parameters:

  • lab – The lab object to which the annotation belongs.

  • annotation_id – The ID of the annotation.

  • annotation_type – annotation type (text, line, ellipse, rectangle)

as_dict() → dict[str, Any]

Convert the annotation object to a dictionary representation.

Returns:

A dictionary representation of the annotation object.

classmethod get_default_property_values(annotation_type: str) → dict[str, Any]

Return a list of all valid properties set to default values for the selected annotation type.

classmethod is_valid_property(annotation_type: AnnotationTypeString, _property: str) → bool

Check if the given property is recognized by the selected annotation type.

remove() → None

Remove annotation from the lab.

update(annotation_data: dict[str, Any], push_to_server=None) → None

Update annotation properties.

Parameters:

  • annotation_data – JSON dict with new annotation property:value pairs.

  • push_to_server – DEPRECATED: Was only used by internal methods and should otherwise always be True.

property border_color: str

#FF00FF00).

Type:

Border color (example

property border_style: str

‘’ (solid), ‘2,2’ (dotted), ‘4,2’ (dashed).

Type:

Border style; valid values

property color: str

#00AAFF).

Type:

Annotation color (example

property id: str

Return ID of the annotation.

property thickness: int

Annotation border thickness.

property type: str

Return type of the annotation.

property x1: int

X1 coordinate.

property y1: int

Y1 coordinate.

property z_index: int

Z layer (depth) of an annotation.

class virl2_client.models.AuthManagement(session: Client, auto_sync=True, auto_sync_interval=1.0)

Bases: object

__init__(session: Client, auto_sync=True, auto_sync_interval=1.0)

Manage authentication settings and synchronization.

Parameters:

  • session – The httpx-based HTTP client for this session with the server.

  • auto_sync – Whether to automatically synchronize resource pools.

  • auto_sync_interval – How often to synchronize resource pools in seconds.

get_ldap_groups(search_filter=None)

Get CNs of groups available on the LDAP server, optionally filtered by supplied filter.

Parameters:

search_filter – An optional filter applied to the search.

Returns:

A list of CNs of found groups.

get_settings() → dict

Get a dictionary of the settings of the current authentication method.

Returns:

A dictionary of the settings of the current authentication method.

refresh_ldap_groups()

Refresh the members of LDAP groups. Removes any users from the group that are not LDAP users or not a part of said group on LDAP, and adds any users that are LDAP users and are a part of said group on LDAP.

sync() → None

Synchronize the authentication settings with the server.

sync_if_outdated() → None

Synchronize local data with the server if the auto sync interval has elapsed since the last synchronization.

test_auth(config: dict, username: str | None = None, password: str | None = None, group_name: str | None = None) → dict

Test a set of credentials and/or group against the specified authentication configuration.

Parameters:

  • config – A dictionary of authentication settings to test against (including manager password).

  • username – The username to test.

  • password – The password to test.

  • group_name – The group name to test.

Returns:

Results of the test.

test_current_auth(manager_password: str, username: str | None = None, password: str | None = None, group_name: str | None = None) → dict

Test a set of credentials and/or group against the currently applied authentication configuration.

Parameters:

  • manager_password – The manager password to allow testing.

  • username – The username to test.

  • password – The password to test.

  • group_name – The group name to test.

Returns:

Results of the test.

update_settings(settings_dict: dict | None = None, **kwargs) → None

Update multiple authentication settings at once.

This method is more efficient in batches than setting manager properties.

If passed a dictionary, it reads the dictionary for settings. If passed multiple keyword arguments, each is taken as a setting. Can mix and match; keywords take precedence.

Examples::

am = client.auth_management am.update_settings({“method”: “ldap”, “verify_tls”: False}) am.update_settings(method=”ldap”, verify_tls=False) # “verify_tls” key in dictionary overridden by keyword argument into False am.update_settings({“method”: “ldap”, “verify_tls”: True}, verify_tls=False)

Parameters:

  • settings_dict – A dictionary of settings.

  • kwargs – Setting keywords.

property manager: AuthMethodManager

Return the property manager for the current authentication method.

property method: str

Return the current authentication method.

class virl2_client.models.GroupManagement(session: httpx.Client)

Bases: object

Manage groups.

__init__(session: httpx.Client) → None
associations(group_id: str) → list[dict[str, list[str]]]

Get a list of lab associations for a group.

Parameters:

group_id – The UUID4 of the group.

Returns:

A list of lab associations for this group.

create_group(name: str, **kwargs: Any) → dict

Create a group.

Parameters:

  • name – The name of the group.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • description: The description of the group.

  • members: The members of the group.

  • associations: The lab associations for the group.

  • labs: DEPRECATED: replaced by ‘associations’.

    The labs associated with the group.

Returns:

The created group object.

delete_group(group_id: str) → None

Delete a group.

Parameters:

group_id – The UUID4 of the group.

get_group(group_id: str) → dict

Get information for the specified group.

Parameters:

group_id – The UUID4 of the group.

Returns:

A group object.

group_id(group_name: str) → str

Get the unique UUID4 of a group.

Parameters:

group_name – The name of the group.

Returns:

The unique identifier of the group.

group_labs(group_id: str) → list[str]

DEPRECATED: Use .associations() instead. (Reason: adapted to the new format of lab associations)

Get a list of labs associated with a group.

Parameters:

group_id – The UUID4 of the group.

Returns:

A list of labs associated with this group.

group_members(group_id: str) → list[str]

Get the members of a group.

Parameters:

group_id – The UUID4 of the group.

Returns:

A list of users associated with this group.

groups() → list

Get the list of available groups.

Returns:

A list of group objects.

update_associations(group_id: str, associations: list[dict[str, list[str]]]) → dict

Update the lab associations for a group.

Parameters:

  • group_id – The UUID4 of the group.

  • associations – The new list of lab associations.

Returns:

The updated group object.

update_group(group_id: str, **kwargs: Any) → dict

Update a group.

Parameters:

  • group_id – The UUID4 of the group.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • name: The name of the group.

  • description: The description of the group.

  • members: The members of the group.

  • associations: The lab associations for the group.

  • labs: DEPRECATED: replaced by ‘associations’.

    The labs associated with the group.

Returns:

The updated group object.

class virl2_client.models.Interface(iid: str, node: Node, label: str, slot: int | None, iface_type: str = 'physical', mac_address: str | None = None)

Bases: object

__init__(iid: str, node: Node, label: str, slot: int | None, iface_type: str = 'physical', mac_address: str | None = None) → None

A CML 2 network interface, part of a node.

Parameters:

  • iid – The interface ID.

  • node – The node object.

  • label – The label of the interface.

  • slot – The slot of the interface.

  • iface_type – The type of the interface.

  • mac_address – The MAC address of the interface.

as_dict() → dict[str, str | dict]

Convert the interface to a dictionary representation.

bring_up() → None

Bring up the interface.

Return the link between this interface and another.

Parameters:

other_interface – The other interface.

Returns:

A Link object if a link exists between the interfaces, None otherwise.

remove() → None

Remove the interface from the node.

shutdown() → None

Shutdown the interface.

property connected: bool

Check if the interface is connected to a link.

property deployed_mac_address: str | None

Return the deployed MAC address of the interface.

property discovered_ipv4: list[str] | None

Return the discovered IPv4 addresses of the interface.

property discovered_ipv6: list[str] | None

Return the discovered IPv6 addresses of the interface.

property discovered_mac_address: str | None

Return the discovered MAC address of the interface.

property id: str

Return the ID of the interface.

property ip_snooped_info: dict[str, list[str] | str | None]

Return the discovered MAC, IPv4 and IPv6 addresses of the interface in a dictionary.

property label: str

Return the label of the interface.

Get the link if the interface is connected, otherwise None.

property mac_address: str | None

Return the MAC address set to the interface. This is the address that will be used when the device is started.

property node: Node

Return the node object to which the interface belongs.

property operational: dict[str, Any]

Return the operational data for this interface.

property peer_interface: Interface | None

Return the peer interface connected to the interface.

property peer_node: Node | None

Return the node to which the peer interface belongs.

property physical: bool

Check if the interface is physical.

property readbytes: int

Return the number of bytes read by the interface.

property readpackets: int

Return the number of packets read by the interface.

property slot: int | None

Return the slot of the interface.

property state: str | None

Return the state of the interface.

property type: str

Return the type of the interface.

property writebytes: int

Return the number of bytes written by the interface.

property writepackets: int

Return the number of packets written by the interface.

class virl2_client.models.Lab(title: str | None, lab_id: str, session: httpx.Client, username: str, password: str, auto_sync: bool = True, auto_sync_interval: float = 1.0, wait: bool = True, wait_max_iterations: int = 500, wait_time: int | float = 5, hostname: str | None = None, resource_pool_manager: ResourcePoolManagement | None = None, user_management: UserManagement | None = None)

Bases: object

__init__(title: str | None, lab_id: str, session: httpx.Client, username: str, password: str, auto_sync: bool = True, auto_sync_interval: float = 1.0, wait: bool = True, wait_max_iterations: int = 500, wait_time: int | float = 5, hostname: str | None = None, resource_pool_manager: ResourcePoolManagement | None = None, user_management: UserManagement | None = None) → None

A VIRL2 lab network topology.

Parameters:

  • title – Name or title of the lab.

  • lab_id – Lab ID.

  • session – The httpx-based HTTP client for this session with the server.

  • username – Username of the user to authenticate.

  • password – Password of the user to authenticate.

  • auto_sync – A flag indicating whether local changes should be automatically synced to the server.

  • auto_sync_interval – Interval in seconds for automatic syncing.

  • wait – A flag indicating whether to wait for convergence on the backend.

  • wait_max_iterations – Maximum number of iterations for convergence.

  • wait_time – Time in seconds to sleep between convergence calls on the backend.

  • hostname – Hostname/IP and port for pyATS console terminal server.

  • resource_pool_manager – ResourcePoolManagement object shared with parent ClientLibrary.

  • user_management – UserManagement object shared with parent ClientLibrary for resolving user IDs to usernames.

Raises:

VirlException – If the lab object is created without a resource pool manager.

annotations() → list[AnnotationType]

Return the list of annotations in the lab.

Returns:

A list of Annotation objects.

build_configurations() → None

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

cleanup_pyats_connections() → None

Close and clean up connection that pyATS might still hold.

clear_discovered_addresses() → None

Clear all discovered L3 addresses for all nodes in this lab from snooper.

connect_two_nodes(node1: Node, node2: Node, index: int = 0) → Link

Connect two nodes within a lab.

Parameters:

  • node1 – The first node object.

  • node2 – The second node object.

  • index – An optional starting interface index (default: 0).

Returns:

The created link.

create_annotation(annotation_type: str, **kwargs) → AnnotationType

Create a lab annotation.

Parameters:

  • annotation_type – Type of the annotation (rectangle, ellipse, line or text).

  • kwargs – Keyword arguments with annotation property values.

Returns:

The created annotation.

create_interface(node: Node | str, slot: int | None = None, wait: bool | None = None) → Interface

Create an interface in the next available slot, or, if a slot is specified, in all available slots up to and including the specified slot.

Parameters:

  • node – The node on which the interface is created.

  • slot – The slot number to create the interface in.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

Returns:

The newly created interface.

Create a link between two interfaces.

Parameters:

  • i1 – The first interface object or ID.

  • i2 – The second interface object or ID.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

Returns:

The created link.

create_node(label: str, node_definition: str, x: int = 0, y: int = 0, wait: bool | None = None, populate_interfaces: bool = False, **kwargs) → Node

Create a node in the lab with the given parameters.

Parameters:

  • label – Label.

  • node_definition – Node definition.

  • x – The X coordinate.

  • y – The Y coordinate.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

  • populate_interfaces – Automatically create a pre-defined number of interfaces on node creation.

  • kwargs – Optional parameters. See below.

Returns:

A Node object.

Keyword Arguments:

  • image_definition: The definition of the image used by this node.

  • configuration: The initial configuration of this node.

  • ram: The memory of the node in MiB (if applicable).

  • cpus: The number of CPUs in this node (if applicable).

  • cpu_limit: The CPU limit of the node (default is 100%).

  • data_volume: The size in GiB of the second HDD (if > 0).

  • boot_disk_size: The size in GiB of the boot disk

    (will expand to this size).

  • hide_links: A flag indicating whether the node’s links should be hidden

    in UI visualization.

  • tags: A list of tags associated with the node.

  • resource_pool: The ID of the resource pool if the node is part

    of a resource pool.

  • pinned_compute_id: The ID of the compute this node is pinned to.

    The node will not run on any other compute.

  • priority: The launch priority of the node (0-10000, or None).

    The higher the priority, the sooner the node will be started.

create_smart_annotation(tag: str, nodes: list[str | Node], **kwargs) → SmartAnnotation

Create a smart annotation in the lab. Smart annotations are automatically created when adding a new tag to a node, so this is simply a convenience function to add the tag to all listed nodes, retrieve the new smart annotation and update it with the given properties.

Parameters:

  • tag – Tag which the smart annotation will be bound to.

  • nodes – Nodes to which to add the tag and smart annotation.

  • kwargs – Keyword arguments with annotation property values. See models.SmartAnnotation for available properties.

Returns:

The created annotation.

details() → dict[str, str | list | int]

Retrieve the details of the lab, including its state.

Returns:

A dictionary containing the detailed lab state

download() → str

Download the lab from the server in YAML format.

Returns:

The lab in YAML format.

find_nodes_by_tag(tag: str) → list[Node]

Return the nodes identified by the given tag.

Parameters:

tag – The tag by which to search.

Returns:

A list of nodes.

get_annotation_by_id(annotation_id: str) → AnnotationType

Return the annotation identified by the ID.

Parameters:

annotation_id – ID of the annotation to be returned

Returns:

An Annotation object.

Raises:

AnnotationNotFound – If annotation is not found.

get_interface_by_id(interface_id: str) → Interface

Return the interface identified by the ID.

Parameters:

interface_id – ID of the interface to be returned.

Returns:

An Interface object.

Raises:

InterfaceNotFound – If the interface is not found.

Return the link identified by the ID.

Parameters:

link_id – ID of the link to be returned.

Returns:

A Link object.

Raises:

LinkNotFound – If the link is not found.

get_node_by_id(node_id: str) → Node

Return the node identified by the ID.

Parameters:

node_id – ID of the node to be returned.

Returns:

A Node object.

Raises:

NodeNotFound – If the node is not found.

get_node_by_label(label: str) → Node

Return the node identified by the label.

Parameters:

label – Label of the node to be returned.

Returns:

A Node object.

Raises:

NodeNotFound – If the node is not found.

get_pyats_testbed(hostname: str | None = None) → str

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 – Force hostname/ip and port for console terminal server.

Returns:

The pyATS testbed for the lab in YAML format.

get_smart_annotation_by_id(annotation_id: str) → SmartAnnotation

Return the smart annotation identified by the ID.

Parameters:

annotation_id – ID of the annotation to be returned.

Returns:

A SmartAnnotation object.

Raises:

SmartAnnotationNotFound – If annotation is not found.

get_smart_annotation_by_tag(tag: str) → SmartAnnotation

Return the smart annotation identified by the tag.

Parameters:

tag – Tag by which to search for the smart annotation.

Returns:

A SmartAnnotation object.

Raises:

SmartAnnotationNotFound – If annotation is not found.

has_converged() → bool

Check whether the lab has converged.

Returns:

True if the lab has converged, False otherwise.

import_lab(topology: dict) → None

Import a lab from a given topology.

Parameters:

topology – The topology to import.

interfaces() → list[Interface]

Return the list of interfaces in the lab.

Returns:

A list of Interface objects.

is_active() → bool

Check if the lab is active.

Returns:

True if the lab is active, False otherwise

Return the list of links in the lab.

Returns:

A list of Link objects.

need_to_wait(local_wait: bool | None) → bool

Check if waiting is required.

If local_wait is None, return the value of wait_for_convergence. If local_wait is not a boolean, raise a ValueError.

Parameters:

local_wait – Local wait flag.

Returns:

True if waiting is required, False otherwise.

Raises:

ValueError – If local_wait is not a boolean or None.

nodes() → list[Node]

Return the list of nodes in the lab.

Returns:

A list of Node objects.

remove() → None

Remove the lab from the server. The lab must be stopped and wiped first.

remove_annotation(annotation: Annotation | str) → None

Remove an annotation from the lab.

If you have an annotation object, you can also simply do:

annotation.remove()
Parameters:

annotation – The annotation object or ID.

remove_annotations() → None

Remove all annotations from the lab.

remove_interface(iface: Interface | str, wait: bool | None = None) → None

Remove an interface from the lab.

If you have an interface object, you can also simply do:

interface.remove()
Parameters:

  • iface – The interface object or ID.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

Remove a link from the lab.

If you have a link object, you can also simply do:

link.remove()
Parameters:

  • link – The link object or ID.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

remove_node(node: Node | str, wait: bool | None = None) → None

Remove a node from the lab.

If you have a node object, you can also simply do:

node.remove()
Parameters:

  • node – The node object or ID.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

remove_nodes(wait: bool | None = None) → None

Remove all nodes from the lab.

Parameters:

wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

remove_smart_annotation(annotation: SmartAnnotation | str) → None

Remove a smart annotation from the lab.

If you have a smart annotation object, you can also simply do:

smart_annotation.remove()
Parameters:

annotation – The annotation object or ID.

remove_smart_annotations() → None

Remove all smart annotations from the lab.

set_autostart(enabled: bool | None = None, priority: int | None | ~virl2_client.utils._Sentinel = <Unchanged>, delay: int | None | ~virl2_client.utils._Sentinel = <Unchanged>) → None

Set all autostart configuration properties.

Parameters:

  • enabled – Whether autostart is enabled.

  • priority – Priority of the lab autostart (0-10000, None for default).

  • delay – Delay in seconds before lab autostart (0-86400, None for default).

set_node_staging(enabled: bool | None = None, start_remaining: bool | None = None, abort_on_failure: bool | None = None) → None

Set all node staging configuration properties.

Parameters:

  • enabled – Whether node staging is enabled.

  • start_remaining – Whether to start remaining nodes after staging.

  • abort_on_failure – Whether to abort staging on failure.

smart_annotations() → list[SmartAnnotation]

Return the list of smart annotations in the lab.

Returns:

A list of SmartAnnotation objects.

start(wait: bool | None = None) → None

Start all the nodes and links in the lab.

Parameters:

wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

state() → str

Return the state of the lab.

Returns:

The state as text.

stop(wait: bool | None = None) → None

Stop all the nodes and links in the lab.

Parameters:

wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

sync(topology_only=True, exclude_configurations: bool | None = False) → None

Synchronize the current lab, locally applying changes made to the server.

Parameters:

  • topology_only – Only sync the topology without statistics and IP addresses.

  • exclude_configurations – Whether to exclude configurations from synchronization.

sync_events() → bool

Synchronize the events in the lab.

Returns:

True if the events have changed, False otherwise

sync_interfaces_operational() → None

Synchronize the operational state of all interfaces in the lab.

sync_l3_addresses_if_outdated() → None

Sync L3 addresses if they are outdated.

sync_layer3_addresses() → None

Sync all layer 3 IP addresses from the backend server.

sync_operational() → None

Sync the operational status of the lab.

sync_operational_if_outdated() → None

Sync the operational data if it is outdated.

sync_pyats() → None

Sync the pyATS testbed.

sync_states() → None

Sync all the states of the various elements with the backend server.

sync_states_if_outdated() → None

Sync states if they are outdated.

sync_statistics() → None

Retrieve the simulation statistic data from the back end server.

sync_statistics_if_outdated() → None

Sync statistics if they are outdated.

sync_topology_if_outdated(exclude_configurations=True) → None

Sync the topology if it is outdated.

update_associations(associations: dict[str, list[dict[str, list[str]]]]) → dict[str, list[dict[str, list[str]]]]

Modify lab/group/user associations.

Parameters:

associations – An object containing group and user list of objects consisting of ID and permissions.

Returns:

Updated object containing group and user list of objects consisting of ID and permissions.

update_connector_mappings(updates: list[dict[str, str]]) → list[dict[str, str]]

Update lab’s external connector mappings.

Accepts a list of mappings, each with a key to add or modify, and the associated device name (bridge) of the controller host. If no running external connector node uses this key, the device_name value may be None to disassociate the bridge from the key; if no node uses this key in its configuration, the mapping entry is removed.

Returns:

All connector mappings after updates were applied.

update_lab(topology: dict, exclude_configurations: bool) → None

Update the lab with the given topology.

Parameters:

  • topology – The updated topology.

  • exclude_configurations – Whether to exclude configurations from updating.

update_lab_groups(group_list: list[dict[str, str]]) → list[dict[str, str]]

DEPRECATED: Use .update_associations() instead. (Reason: adapted to new format of lab associations)

Modify lab/group association.

Parameters:

group_list – List of objects consisting of group ID and permissions.

Returns:

Updated objects consisting of group ID and permissions.

update_lab_properties(properties: dict[str, Any])

Update lab properties. Will not modify unspecified properties. Is not compatible with schema version 0.0.5.

Parameters:

properties – Dictionary containing the updated lab properties.

wait_until_lab_converged(max_iterations: int | None = None, wait_time: int | None = None) → None

Wait until the lab converges.

Parameters:

  • max_iterations – The maximum number of iterations to wait.

  • wait_time – The time to wait between iterations.

wipe(wait: bool | None = None) → None

Wipe all the nodes and links in the lab.

Parameters:

wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

property associations: dict[str, list[dict[str, list[str]]]]

Return the group and user associations for this lab.

Returns:

An object containing group and user list of objects consisting of ID and permissions.

property autostart: dict[str, Any]

Return the autostart configuration as a dict.

property connector_mappings: list[dict[str, Any]]

Retrieve lab’s external connector mappings.

Returns a list of mappings; each mapping has a key, which is used as the configuration of external connector nodes, and a device name, used to uniquely identify the controller host’s bridge to use. If unset, the mapping is invalid and nodes using it cannot start.

property description: str

Return the description of the lab.

property groups: list[dict[str, str]]

Use .associations instead. (Reason: adapted to new format of lab associations)

Return the groups this lab is associated with.

Returns:

List of objects consisting of group ID and permissions.

Type:

DEPRECATED

property id: str

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

property node_staging: dict[str, bool]

Return the node staging configuration as a dict.

property notes: str

Return the notes of the lab.

property owner: str

Return the owner of the lab.

property resource_pools: list[ResourcePool]

Return the list of resource pools this lab’s nodes belong to.

property statistics: dict

Return lab statistics.

Returns:

A dictionary with stats of the lab.

property title: str | None

Return the title of the lab.

class virl2_client.models.LabRepository(system, id: str, url: str, name: str, folder: str)

Bases: object

__init__(system, id: str, url: str, name: str, folder: str)

A lab repository, which provides access to lab templates and resources.

Parameters:

  • system – The SystemManagement instance.

  • id – The ID of the lab repository.

  • url – The URL of the lab repository.

  • name – The name of the lab repository.

  • folder – The folder name for the lab repository.

remove() → None

Remove the lab repository.

property folder: str

Return the folder name of the lab repository.

property id: str

Return the ID of the lab repository.

property name: str

Return the name of the lab repository.

property url: str

Return the URL of the lab repository.

class virl2_client.models.LabRepositoryManagement(system, session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0)

Bases: object

Manage lab repositories.

__init__(system, session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0) → None

Manage lab repositories.

Parameters:

  • system – The SystemManagement instance.

  • session – The httpx-based HTTP client for this session with the server.

  • auto_sync – A boolean indicating whether auto synchronization is enabled.

  • auto_sync_interval – The interval in seconds between auto synchronizations.

add_lab_repository(url: str, name: str, folder: str) → dict[str, Any]

Add a lab repository.

Parameters:

  • url – The URL of the lab repository.

  • name – The name of the lab repository.

  • folder – The folder name for the lab repository.

Returns:

The created lab repository data.

add_lab_repository_local(id: str, url: str, name: str, folder: str) → LabRepository

Add a lab repository locally.

Parameters:

  • id – The unique identifier of the lab repository.

  • url – The URL of the lab repository.

  • name – The name of the lab repository.

  • folder – The folder name for the lab repository.

Returns:

The newly created lab repository object.

get_lab_repositories() → list[dict[str, Any]]

Get the list of configured lab repositories.

Returns:

A list of lab repository objects.

get_lab_repository(repo_id: str) → LabRepository

Get a lab repository by its ID.

Parameters:

repo_id – The ID of the lab repository.

Returns:

The lab repository with the specified ID.

Raises:

LabRepositoryNotFound – If no lab repository with the specified ID is found.

get_lab_repository_by_name(name: str) → LabRepository

Get a lab repository by its name.

Parameters:

name – The name of the lab repository.

Returns:

The lab repository with the specified name.

Raises:

LabRepositoryNotFound – If no lab repository with the specified name is found.

refresh_lab_repositories() → dict[str, dict[str, Any]]

Performs a git pull on each configured lab repository and returns the result.

Returns:

A dictionary containing the refresh status for each repository.

sync_lab_repositories() → None

Synchronize lab repositories from the server.

sync_lab_repositories_if_outdated() → None

Synchronize lab repositories if they are outdated.

property lab_repositories: dict[str, LabRepository]

Return a dictionary of lab repositories.

class virl2_client.models.Licensing(session: httpx.Client)

Bases: object

__init__(session: httpx.Client) → None

Manage licensing.

Parameters:

  • session – The httpx-based HTTP client for this session with the server.

  • is_cert_deprecated – Whether the certificate supported is deprecated.

cancel_reservation() → bool

Cancel reservation request without completing it.

complete_reservation(authorization_code: str) → str

Complete reservation by installing authorization code from SSMS.

delete_reservation_confirmation_code() → bool

Remove the reservation confirmation code.

delete_reservation_return_code() → bool

Remove the reservation return code.

deregister() → int

Request deregistration from the current SSMS.

disable_reservation_mode() → None

Disable reservation mode in unregistered agent.

discard_reservation(data: str) → str

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

enable_reservation_mode() → None

Enable reservation mode in unregistered agent.

features() → list[dict[str, str | int]]

DEPRECATED: Use .status() instead. (Reason: dropped in favor of single call to get the whole licensing status)

Get current licensing features.

get_reservation_confirmation_code() → str

Get the reservation confirmation code.

get_reservation_return_code() → str

Get the reservation return code.

register(token: str, reregister=False) → bool

Setup licensing registration.

register_renew() → bool

Request a renewal of licensing registration against current SSMS.

register_wait(token: str, reregister=False) → bool

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

release_reservation() → str

Return a completed reservation.

renew_authorization() → bool

Renew licensing authorization with the backend.

request_reservation() → str

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

reservation_mode(data: bool) → None

Enable or disable reservation mode in unregistered agent.

set_default_transport() → bool

Setup licensing transport configuration to default values.

set_product_license(product_license: str) → bool

Setup a product license.

set_transport(ssms: str | None, proxy_server: str | None = None, proxy_port: int | None = None) → bool

Setup licensing transport configuration.

status() → dict[str, Any]

Return current licensing configuration and status.

tech_support() → str

Return current licensing tech support.

update_features(features: dict[str, int] | list[dict[str, int]]) → None

Update licensing feature’s explicit count in reservation mode.

wait_for_status(what: str, *target_status: str) → None

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. :raises RuntimeError: When timeout is reached.

max_wait = 30
wait_interval = 1.5

Bases: object

__init__(lab: Lab, lid: str, iface_a: Interface, iface_b: Interface, label: str | None = None) → None

A VIRL2 network link between two nodes, connecting to two interfaces on these nodes.

Parameters:

  • lab – The lab object to which the link belongs.

  • lid – The ID of the link.

  • iface_a – The first interface of the link.

  • iface_b – The second interface of the link.

  • label – The label of the link.

as_dict() → dict[str, str]

Convert the link object to a dictionary representation.

Returns:

A dictionary representation of the link object.

capture_status() → dict

Get the current packet capture status for this link.

Returns:

Dictionary containing capture configuration, start time, and packet count.

download_capture() → bytes

Download the PCAP file for this link’s last capture.

Returns:

The PCAP file content as bytes.

get_capture_packet(packet_id: int) → dict

Get a specific packet from the last capture in decoded format.

Parameters:

packet_id – The ID of the packet (1-based index).

Returns:

Dictionary containing the decoded packet information.

get_capture_packets() → list[dict]

Get a list of all captured packets in decoded format from last capture.

Returns:

List of packet dictionaries with decoded packet information.

get_condition() → dict

Get the current conditioning parameters for the link.

Returns:

A dictionary containing the current conditioning parameters.

has_converged() → bool

Check if the link has converged.

Returns:

True if the link has converged, False otherwise.

remove()

Remove the link from the lab.

remove_condition() → None

Remove the link conditioning.

set_condition(bandwidth: int | None | ~virl2_client.utils._Sentinel = <Unchanged>, latency: int | None | ~virl2_client.utils._Sentinel = <Unchanged>, jitter: int | None | ~virl2_client.utils._Sentinel = <Unchanged>, loss: float | None | ~virl2_client.utils._Sentinel = <Unchanged>, **kwargs: dict[str, float | int | bool | None]) → None

Set the conditioning parameters for the link.

Parameters:

  • bandwidth – The desired bandwidth in kbps (0-10000000).

  • latency – The desired latency in ms (0-10000).

  • jitter – The desired jitter in ms (0-10000).

  • loss – The desired packet loss in percent (0-100).

  • kwargs – Additional parameters. See below.

Keyword Arguments:

  • enabled: Whether the link conditioning is enabled.

  • delay_corr: The desired packet loss correlation in percent (0-100).

  • limit: The desired maximum delay in ms (0-10000).

  • loss_corr: The desired packet loss correlation in percent (0-100).

  • gap: The desired gap between packets in ms (0-10000).

  • duplicate: The desired probability of duplicates in percent (0-100).

  • duplicate_corr: The desired correlation of duplicates in percent (0-100).

  • reorder_prob: The desired probability of re-orders in percent (0-100).

  • reorder_corr: The desired re-order correlation in percent (0-100).

  • corrupt_prob: The desired corruption probability in percent (0-100).

  • corrupt_corr: The desired corruption correlation in percent (0-100).

set_condition_by_name(name: str) → None

A convenience function to provide some commonly used link condition settings for various link types.

Inspired by: https://github.com/tylertreat/comcast

Name

Latency (ms)

Bandwidth

Loss (%)

gprs

500

50 kbps

2.0

edge

300

250 kbps

1.5

3g

250

750 kbps

1.5

dialup

185

40 kbps

2.0

dsl1

70

2 mbps

2.0

dsl2

40

8 mbps

0.5

wifi

10

30 mbps

0.1

wan1

80

256 kbps

0.2

wan2

80

100 mbps

0.2

satellite

1500

1 mbps

0.2
Parameters:

name – The name of the predefined link condition.

Raises:

ValueError – If the given name is not a known predefined condition.

start(wait: bool | None = None) → None

Start the link.

Parameters:

wait – Whether to wait for convergence after starting the link.

start_capture(maxpackets: int | None = None, maxtime: int | None = None, bpfilter: str | None = None, encap: str = 'ethernet') → dict

Start a packet capture on this link.

Parameters:

  • maxpackets – Maximum number of packets to capture (1-1000000). If None, server sets default.

  • maxtime – Maximum time in seconds to capture (1-86400). If None, server sets default.

  • bpfilter – Berkeley packet filter string (1-128 chars).

  • encap – Link encapsulation type.

Returns:

Dictionary containing the capture status and configuration.

stop(wait: bool | None = None) → None

Stop the link.

Parameters:

wait – Whether to wait for convergence after stopping the link.

stop_capture() → None

Stop the packet capture on this link.

wait_until_converged(max_iterations: int | None = None, wait_time: int | None = None) → None

Wait until the link has converged.

Parameters:

  • max_iterations – The maximum number of iterations to wait for convergence.

  • wait_time – The time to wait between iterations.

Raises:

RuntimeError – If the link does not converge within the specified number of iterations.

property id: str

Return the ID of the link.

property interface_a: Interface

Return the first interface of the link.

property interface_b: Interface

Return the second interface of the link.

property interfaces: tuple[Interface, Interface]

Return the interfaces connected by the link.

property lab: Lab

Return the lab of the link.

property label: str | None

Return the label of the link.

property node_a: Node

Return the first node connected to the link.

property node_b: Node

Return the second node connected to the link.

property nodes: tuple[Node, Node]

Return the nodes connected by the link.

property readbytes: int

Return the number of read bytes on the link.

property readpackets: int

Return the number of read packets on the link.

property state: str | None

Return the current state of the link.

property writebytes: int

Return the number of written bytes on the link.

property writepackets: int

Return the number of written packets on the link.

class virl2_client.models.Node(lab: Lab, nid: str, label: str, node_definition: str, **kwargs)

Bases: object

__init__(lab: Lab, nid: str, label: str, node_definition: str, **kwargs) → None

A VIRL2 node object representing a virtual machine that serves as a router, switch, or server.

Parameters:

  • lab – The Lab instance to which this node belongs.

  • nid – The ID of the node.

  • label – The label of the node.

  • node_definition – The definition of this node.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • image_definition: The definition of the image used by this node.

  • configuration: The initial configuration of this node.

  • x: The X coordinate of the node on the topology canvas.

  • y: The Y coordinate of the node on the topology canvas.

  • ram: The memory of the node in MiB (if applicable).

  • cpus: The number of CPUs in this node (if applicable).

  • cpu_limit: The CPU limit of the node (default is 100%).

  • data_volume: The size in GiB of the second HDD (if > 0).

  • boot_disk_size: The size in GiB of the boot disk

    (will expand to this size).

  • hide_links: A flag indicating whether the node’s links should be hidden

    in UI visualization.

  • tags: A list of tags associated with the node.

  • resource_pool: The ID of the resource pool if the node is part

    of a resource pool.

  • pinned_compute_id: The ID of the compute this node is pinned to.

    The node will not run on any other compute.

  • priority: The launch priority of the node (0-10000, or None).

    The higher the priority, the sooner the node will be started.

  • pyats: PyATS credentials for this node (if applicable).

add_tag(tag: str) → None

Add a tag to this node.

Parameters:

tag – The tag to add.

clear_discovered_addresses() → None

Clear all discovered L3 addresses for this node from the snooper.

clone_image() → dict

Clone the node’s disks into a new Image definition.

console_key(console_number: int = 0) → str

Get the console key of the node.

Parameters:

console_number – The console number (defaults to 0).

Returns:

The console key.

console_logs(console_id: int, lines: int | None = None) → dict

Get the console logs of the node.

Parameters:

  • console_id – The ID of the console.

  • lines – Limit the number of lines to retrieve.

Returns:

A dictionary containing the console logs.

create_interface(slot: int | None = None, wait: bool = False) → Interface

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

Parameters:

  • slot – The slot in which the interface will be created.

  • wait – Wait for the creation to complete.

Returns:

The newly created interface.

degree() → int

Return the degree of the node.

extract_configuration() → None

Update the configuration from the running node.

get_interface_by_label(label: str) → Interface

Get the interface of the node with the specified label.

Parameters:

label – The label of the interface.

Returns:

The interface with the specified label.

Raises:

InterfaceNotFound – If no interface with the specified label is found.

get_interface_by_slot(slot: int) → Interface

Get the interface of the node with the specified slot.

Parameters:

slot – The slot number of the interface.

Returns:

The interface with the specified slot.

Raises:

InterfaceNotFound – If no interface with the specified slot is found.

Return one link between this node and another.

Parameters:

other_node – The other node.

Returns:

A link between this node and the other node, if one exists.

Return all links between this node and another.

Parameters:

other_node – The other node.

Returns:

A list of links between this node and the other node.

has_converged() → bool

Check if the node has converged.

Returns:

True if the node has converged, False otherwise.

interfaces() → list[Interface]

Return a list of interfaces on the node.

is_active() → bool

Check if the node is in an active state.

Returns:

True if the node is in an active state, False otherwise.

is_booted() → bool

Check if the node is booted.

Returns:

True if the node is booted, False otherwise.

Return a list of links connected to this node.

map_l3_addresses_to_interfaces(mapping: dict[str, dict[str, str]]) → None

Map layer 3 addresses to interfaces.

This method updates all loaded interfaces on this node: - Interfaces present in the mapping get updated with new L3 address info - Interfaces NOT present in the mapping get their L3 addresses cleared

Parameters:

mapping – A dictionary mapping MAC addresses to interface information.

next_available_interface(index: int = 0) → Interface | None

Return 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!

Parameters:

index – An optional starting interface index (default: 0).

Returns:

An available physical interface or None if all existing ones are connected.

peer_interfaces() → list[Interface]

Return a list of interfaces connected to this node.

peer_nodes() → list[Node]

Return a list of nodes connected to this node.

physical_interfaces() → list[Interface]

Return a list of physical interfaces on the node.

remove() → None

Remove the node from the system.

remove_tag(tag: str) → None

Remove a tag from this node.

Parameters:

tag – The tag to remove.

run_pyats_command(command: str, **pyats_params: Any) → str

Run a pyATS command in exec mode on the node.

Parameters:

  • command – The command to run (e.g. “show version”).

  • pyats_params – Custom command dialog parameters for PyATS

Returns:

The output from the device.

run_pyats_config_command(command: str, **pyats_params: Any) → str

Run a pyATS command in config mode on the node.

Parameters:

  • command – The command to run (e.g. “interface gi0”).

  • pyats_params – Custom command dialog parameters for PyATS

Returns:

The output from the device.

set_pyats_credentials(username: str | None | ~virl2_client.utils._Sentinel = <Unchanged>, password: str | None | ~virl2_client.utils._Sentinel = <Unchanged>, enable_password: str | None | ~virl2_client.utils._Sentinel = <Unchanged>) → None

Set pyATS credentials for this node.

Parameters:

  • username – The username to set, or None to clear it.

  • password – The password to set, or None to clear it.

  • enable_password – The enable password to set, or None to clear it.

This updates the node on the controller with a pyats field whose structure matches the backend expectation, typically:

{
    "username": "<user>",
    "password": "<pass>",
    "enable_password": "<enable_password_pass>"
}
start(wait=False) → None

Start the node.

Parameters:

wait – Whether to wait until the node has converged.

stop(wait=False) → None

Stop the node.

Parameters:

wait – Whether to wait until the node has converged.

sync_interface_operational() → None

Synchronize the operational state of the node’s interfaces.

sync_interface_operational_if_outdated() → None
sync_l3_addresses_if_outdated() → None
sync_layer3_addresses() → None

Acquire all layer 3 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.

If the node is not running or there’s an error fetching L3 addresses, this method will silently clear the discovered addresses rather than raising an exception.

sync_operational(response: dict[str, Any] | None = None) → None

Synchronize the operational state of the node.

Parameters:

response – If the operational data was fetched from the server elsewhere, it can be passed here to save an API call. Will be fetched automatically otherwise.

sync_operational_if_outdated() → None
tags() → list[str]

Get the tags set on this node.

Returns:

A list of tags.

update(node_data: dict[str, Any], exclude_configurations: bool, push_to_server=None) → None

Update the node with the provided data.

Parameters:

  • node_data – The data to update the node with.

  • exclude_configurations – Whether to exclude configuration updates.

  • push_to_server – DEPRECATED: Was only used by internal methods and should otherwise always be True.

update_parameters(new_params: dict) → None

Update node parameters. If parameter doesn’t exist it will be created. Existing nodes will be updated. To delete parameter set its value to None.

vnc_key() → str

Get the VNC key of the node.

Returns:

The VNC key.

wait_until_converged(max_iterations: int | None = None, wait_time: int | None = None) → None

Wait until the node has converged.

Parameters:

  • max_iterations – The maximum number of iterations to wait for convergence.

  • wait_time – The time to wait between iterations.

Raises:

RuntimeError – If the node does not converge within the specified number of iterations.

wipe(wait=False) → None

Wipe the node’s disks.

Parameters:

wait – Whether to wait until the node has converged.

property boot_disk_size: int

Return the size of the boot disk in GiB.

property compute_id

Return the ID of the compute this node is assigned to.

property configuration: str | None

Return the contents of the main configuration file.

property configuration_files: list[dict[str, str]] | None

Return all configuration files, in a list in the following format: [{“name”: “filename.txt”, “content”: “<file content>”}]

property cpu_limit: int

Return the CPU limit of the node.

property cpu_usage: int | float

Return the CPU usage of this node.

property cpus: int

Return the number of CPUs assigned to the node.

property data_volume: int

Return the size (in GiB) of the second HDD.

property disk_read: int

Return the amount of disk read by this node.

property disk_write: int

Return the amount of disk write by this node.

Return a flag indicating whether the node’s links should be hidden in UI visualization.

property id: str

Return the ID of the node.

property image_definition: str | None

Return the definition of the image used by this node.

property lab: Lab

Return the lab of the node.

property label: str

Return the label of the node.

property node_definition: str

Return the definition of this node.

property operational: dict[str, Any]

Return the full operational data as a dictionary.

property parameters: dict

Return node parameters.

property pinned_compute_id: str | None

Return the ID of the compute this node is pinned to.

property priority: int | None

Return the priority of the node.

property pyats_credentials: dict[str, str | None]

Return pyATS credentials for this node, if configured.

The value is expected to be a mapping with “username” and “password” keys, as provided by the backend (for example via the node’s node definition).

property ram: int

Return the RAM size of the node in bytes.

property resource_pool: str

Return the ID of the resource pool if the node is part of a resource pool.

property smart_annotations: dict[str, SmartAnnotation]

Return the tags on this node and their corresponding smart annotations.

property state: str | None

Return the state of the node.

property x: int

Return the X coordinate of the node.

property y: int

Return the Y coordinate of the node.

class virl2_client.models.NodeImageDefinitions(session: httpx.Client)

Bases: object

__init__(session: httpx.Client) → None

Manage node and image definitions.

Node definitions define the properties of a virtual network node. Image definitions define disk images that are required to boot a network node. Together, they define a complete virtual network node.

Parameters:

session – The httpx-based HTTP client for this session with the server.

download_image_definition(definition_id: str) → str

Return the image definition for a given definition ID.

Example:

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

definition_id – The ID of the image definition.

Returns:

The image definition as YAML.

download_image_file_list() → list[str]

Return a list of image files.

Returns:

A list of image file names.

download_node_definition(definition_id: str) → str

Return the node definition for a given definition ID.

Example:

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

definition_id – The ID of the node definition.

Returns:

The node definition as YAML.

image_definitions() → list[dict]

Return all image definitions.

Returns:

A list of image definitions.

image_definitions_for_node_definition(definition_id: str) → list[dict]

Return all image definitions for a given node definition.

Parameters:

definition_id – The ID of the node definition.

Returns:

A list of image definition objects.

node_definitions() → list[dict]

Return all node definitions.

Returns:

A list of node definitions.

remove_dropfolder_image(filename: str) → str

Remove an image file from the drop folder.

Parameters:

filename – The name of the image file to remove.

Returns:

“Success”.

remove_image_definition(definition_id: str) → None

Remove the image definition with the given ID.

Example:

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

definition_id – The ID of the image definition to remove.

remove_node_definition(definition_id: str) → None

Remove the node definition with the given ID.

Example:

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

definition_id – The ID of the node definition to remove.

set_image_definition_read_only(definition_id: str, read_only: bool) → dict

Set the read-only attribute of the image definition with the given ID.

Parameters:

  • definition_id – The ID of the image definition.

  • read_only – The new value of the read-only attribute.

Returns:

The modified image definition.

set_node_definition_read_only(definition_id: str, read_only: bool) → dict

Set the read-only attribute of the node definition with the given ID.

Parameters:

  • definition_id – The ID of the node definition.

  • read_only – The new value of the read-only attribute.

Returns:

The modified node definition.

upload_image_definition(body: str | dict, update: bool = False) → str

Upload a new image definition.

Parameters:

  • body – The image definition (yaml or json).

  • update – If creating a new image definition or updating an existing one.

Returns:

“Success”.

upload_image_file(filename: Path | str, rename: str | None = None) → None

Upload an image file.

Parameters:

  • filename – The path of the image to upload.

  • rename – Optional filename to rename to.

upload_node_definition(body: str | dict, update: bool = False) → str

Upload a new node definition.

Parameters:

  • body – The node definition (yaml or json).

  • update – If creating a new node definition or updating an existing one.

Returns:

“Success”.

class virl2_client.models.ResourcePoolManagement(session: httpx.Client, auto_sync=True, auto_sync_interval=1.0)

Bases: object

__init__(session: httpx.Client, auto_sync=True, auto_sync_interval=1.0)

Manage and synchronize resource pools.

Parameters:

  • session – The httpx-based HTTP client for this session with the server.

  • auto_sync – Whether to automatically synchronize resource pools.

  • auto_sync_interval – How often to synchronize resource pools in seconds.

create_resource_pool(label: str, **kwargs) → ResourcePool

Create a resource pool with the given parameters.

Parameters:

  • label – The label for the resource pools.

  • kwargs – Additional resource pool parameters as accepted by the ResourcePool object.

Returns:

The created ResourcePool object.

create_resource_pools(label: str, users: list[str], **kwargs) → list[ResourcePool]

Create a list of resource pools with the given parameters. If no template is supplied, a new template pool is created with the specified parameters, and each user is assigned a new pool with no additional limits. If a template pool is supplied, then parameters are applied to each user pool.

Parameters:

  • label – The label for the resource pools.

  • users – The list of user IDs for which to create resource pools.

  • kwargs – Additional resource pool parameters as accepted by the ResourcePool object.

Returns:

A list of created resource pool objects, with the template pool first if created.

get_resource_pools_by_ids(resource_pool_ids: str | Iterable[str]) → ResourcePool | dict[str, ResourcePool]

Get resource pools by their IDs.

Parameters:

resource_pool_ids – A resource pool ID or an iterable of IDs.

Returns:

A ResourcePool object when one ID is passed, or a dictionary of IDs to either ResourcePools when a resource pool exists or None when it doesn’t.

Raises:

KeyError – When one ID is passed, and it doesn’t exist.

sync_resource_pools() → None

Synchronize the resource pools with the server.

sync_resource_pools_if_outdated() → None

Synchronize resource pools if they are outdated.

property resource_pools: dict[str, ResourcePool]

Return all resource pools.

class virl2_client.models.SmartAnnotation(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)

Bases: object

__init__(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None) → None

A VIRL2 lab smart annotation.

Parameters:

  • lab – The lab object to which the smart annotation belongs.

  • annotation_id – The ID of the smart annotation.

as_dict() → dict[str, Any]

Convert the smart annotation object to a dictionary representation.

Returns:

A dictionary representation of the smart annotation object.

remove() → None

Remove smart annotation from the lab.

update(annotation_data: dict[str, Any]) → None

Update smart annotation properties.

Parameters:

annotation_data – JSON dict with new annotation property:value pairs.

property border_color: str

#00000080).

Type:

Border color (example

property border_style: str

‘’ (solid), ‘2,2’ (dotted), ‘4,2’ (dashed).

Type:

Border style; valid values

property fill_color: str

#00000080).

Type:

Fill color (example

property group_distance: int

Group distance.

property id: str

Return ID of the smart annotation.

property is_on: bool

Whether the smart annotation is enabled.

property lab: Lab

Return the lab of the smart annotation.

property label: str

Label.

property padding: int

Padding.

property tag: str

Tag.

property tag_offset_x: int

Tag X offset.

property tag_offset_y: int

Tag Y offset.

property tag_size: int

Tag size.

property thickness: int

Thickness.

property z_index: int

Z index.

class virl2_client.models.SystemManagement(session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0)

Bases: object

__init__(session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0)

Manage the underlying controller software and the host system where it runs.

Parameters:

  • session – The httpx-based HTTP client for this session with the server.

  • auto_sync – A boolean indicating whether auto synchronization is enabled.

  • auto_sync_interval – The interval in seconds between auto synchronizations.

add_compute_host_local(compute_id: str, hostname: str, server_address: str, is_connector: bool, is_simulator: bool, is_connected: bool, is_synced: bool, admission_state: str, node_counts: dict[str, int], nodes: list[str] | None = None) → ComputeHost

Add a compute host locally.

Parameters:

  • compute_id – The ID of the compute host.

  • hostname – The hostname of the compute host.

  • server_address – The server address of the compute host.

  • is_connector – A boolean indicating if the compute host is a connector.

  • is_simulator – A boolean indicating if the compute host is a simulator.

  • is_connected – A boolean indicating if the compute host is connected.

  • is_synced – A boolean indicating if the compute host is synced.

  • admission_state – The admission state of the compute host.

  • node_counts – Count of deployed and running nodes and orphans.

  • nodes – A list of node IDs associated with the compute host.

Returns:

The added compute host.

add_system_notice_local(id: str, level: str, label: str, content: str, enabled: bool, acknowledged: dict[str, bool], groups: list[str] | None = None) → SystemNotice

Add a system notice locally.

Parameters:

  • id – The unique identifier of the system notice.

  • level – The level of the system notice.

  • label – The label or title of the system notice.

  • content – The content or description of the system notice.

  • enabled – A flag indicating whether the system notice is enabled or not.

  • acknowledged – A dictionary mapping user IDs to their acknowledgment status.

  • groups – A list of group names to associate with the system notice. (Optional)

Returns:

The newly created system notice object.

delete_external_connector(connector_id: str) → None

Delete an external connector.

Parameters:

connector_id – The ID of the connector to delete.

get_external_connectors(sync: bool | None = None) → list[dict[str, str]]

Get the list of external connectors present on the controller. Device names or tags are used as External Connector nodes’ configuration.

Parameters:

sync – Admin only. A boolean indicating whether to refresh the cached list from host state. If sync is False, the state is retrieved; if True, configuration is applied back into the controller host.

Returns:

A list of objects with the device name and label.

get_new_compute_host_state() → str

Get the admission state of the new compute host.

Returns:

The admission state of the new compute host.

get_telemetry_events() → list[dict[str, Any]]

Return the list of telemetry events.

get_web_session_timeout() → int

Get the web session timeout in seconds.

Returns:

The web session timeout.

set_new_compute_host_state(admission_state: str) → str

Set the admission state of the new compute host.

Parameters:

admission_state – The admission state to set.

Returns:

The updated admission state.

set_web_session_timeout(timeout: int) → None

Set the web session timeout in seconds.

Parameters:

timeout – The timeout value in seconds.

Returns:

None

sync_compute_hosts() → None

Synchronize compute hosts from the server.

sync_compute_hosts_if_outdated() → None

Synchronize compute hosts if they are outdated.

sync_system_notices() → None

Synchronize system notices from the server.

sync_system_notices_if_outdated() → None

Synchronize system notices if they are outdated.

update_external_connector(connector_id: str, data: dict[str, Any]) → dict[str, Any]

Update an external connector.

Parameters:

  • connector_id – The ID of the connector to update.

  • data – The data to update.

Returns:

The updated data.

property compute_hosts: dict[str, ComputeHost]

Return a dictionary of compute hosts.

property controller: ComputeHost

Return the controller

Raises:

ControllerNotFound – If no controller has been found (should never be the case).

Returns:

The controller object.

property maintenance_mode: bool

Return the maintenance mode status.

property maintenance_notice: SystemNotice | None

Return the current maintenance notice.

property system_notices: dict[str, SystemNotice]

Return a dictionary of system notices.

property telemetry: dict[str, OptInStatus | str]

Return the telemetry state.

property telemetry_state: OptInStatus

Return the telemetry state.

class virl2_client.models.TokenAuth(client_library: ClientLibrary)

Bases: Auth

Token-based authentication for an httpx session.

Inspired by: https://requests.readthedocs.io/en/v2.9.1/user/authentication/?highlight=AuthBase#new-forms-of-authentication Modified for httpx based on: https://www.python-httpx.org/advanced/#customizing-authentication

__init__(client_library: ClientLibrary)

Initialize the TokenAuth object with a client library instance.

Parameters:

client_library – A client library instance.

auth_flow(request: Request) → Generator[Request, Response, None]

Implement the authentication flow for the token-based authentication.

Parameters:

request – The request object to authenticate.

Returns:

A generator of the authenticated request and response objects.

logout(clear_all_sessions=False) → bool

Log out the user (invalidate the current token).

Parameters:

clear_all_sessions – Whether to clear all sessions.

Returns:

Whether the logout succeeded.

requires_response_body = True
property token: str | None

Return the authentication token. If the token has not been set, it is obtained from the server.

class virl2_client.models.UserManagement(session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0)

Bases: object

__init__(session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0) → None
associations(user_id: str) → list[dict[str, list[str]]]

Get a list of lab associations for a user.

Parameters:

user_id – The UUID4 of the user.

Returns:

A list of lab associations for this user.

create_user(username: str, pwd: str, **kwargs: dict[str, Any]) → dict

Create a new user.

Parameters:

  • username – Username.

  • pwd – Desired password.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • fullname: Full name.

  • description: Description.

  • email: Email address.

  • admin: Whether to create an admin user.

  • groups: List of groups to which the user should be added.

  • associations: List of lab associations for the user.

  • resource_pool: Resource pool to which the user should be added.

  • opt_in: Whether the user has seen the initial contact dialog.

  • tour_version: The version of the Workbench tour the user has completed.

  • pubkey: An SSH public key for terminal server. Empty string to clear.

Returns:

User object.

delete_user(user_id: str) → None

Delete a user.

Parameters:

user_id – User UUID4.

get_user(user_id: str) → dict

Get user information.

Parameters:

user_id – User UUID4.

Returns:

User object.

get_username(user_id: str) → str | None

Look up a username by user ID from the locally synced user list.

Triggers a sync if the local list is outdated. Returns None if the user_id is not found.

Parameters:

user_id – User UUID4.

Returns:

The username, or None if not found.

sync_users() → None

Fetch all users from the server and store them locally.

sync_users_if_outdated() → None

Synchronize the user list if the auto-sync interval has elapsed.

update_associations(user_id: str, associations: list[dict[str, list[str]]]) → dict

Update the lab associations for a user.

Parameters:

  • user_id – The UUID4 of the user.

  • associations – The new list of lab associations.

Returns:

The updated user object.

update_user(user_id: str, **kwargs: dict[str, Any]) → dict

Update an existing user.

Parameters:

  • user_id – User UUID4.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • fullname: Full name.

  • description: Description.

  • email: Email address.

  • admin: Whether to create an admin user.

  • groups: List of groups to which the user should be added.

  • associations: List of lab associations for the user.

  • password_dict: Dictionary containing old and new passwords.

  • resource_pool: Resource pool to which the user should be added.

  • opt_in: Whether the user has seen the initial contact dialog.

  • tour_version: The version of the Workbench tour the user has completed.

  • pubkey: An SSH public key for terminal server. Empty string to clear.

Returns:

User object.

user_groups(user_id: str) → list[str]

Get the groups that a user is a member of.

Parameters:

user_id – User UUID4.

Returns:

List of group names.

user_id(username: str) → str

Get the unique UUID4 of a user.

Parameters:

username – User name.

Returns:

User unique identifier.

users() → list[dict]

Get the list of available users.

Returns:

List of user IDs.

Submodules

virl2_client.models.annotation module

class virl2_client.models.annotation.Annotation(lab: Lab, annotation_id: str, annotation_type: AnnotationTypeString)

Bases: object

__init__(lab: Lab, annotation_id: str, annotation_type: AnnotationTypeString) → None

A VIRL2 lab annotation.

Parameters:

  • lab – The lab object to which the annotation belongs.

  • annotation_id – The ID of the annotation.

  • annotation_type – annotation type (text, line, ellipse, rectangle)

as_dict() → dict[str, Any]

Convert the annotation object to a dictionary representation.

Returns:

A dictionary representation of the annotation object.

classmethod get_default_property_values(annotation_type: str) → dict[str, Any]

Return a list of all valid properties set to default values for the selected annotation type.

classmethod is_valid_property(annotation_type: AnnotationTypeString, _property: str) → bool

Check if the given property is recognized by the selected annotation type.

remove() → None

Remove annotation from the lab.

update(annotation_data: dict[str, Any], push_to_server=None) → None

Update annotation properties.

Parameters:

  • annotation_data – JSON dict with new annotation property:value pairs.

  • push_to_server – DEPRECATED: Was only used by internal methods and should otherwise always be True.

property border_color: str

#FF00FF00).

Type:

Border color (example

property border_style: str

‘’ (solid), ‘2,2’ (dotted), ‘4,2’ (dashed).

Type:

Border style; valid values

property color: str

#00AAFF).

Type:

Annotation color (example

property id: str

Return ID of the annotation.

property thickness: int

Annotation border thickness.

property type: str

Return type of the annotation.

property x1: int

X1 coordinate.

property y1: int

Y1 coordinate.

property z_index: int

Z layer (depth) of an annotation.

class virl2_client.models.annotation.AnnotationEllipse(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)

Bases: _CoordinateXY2Mixin, _RotationMixin, Annotation

Annotation class representing ellipse annotation.

__init__(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)
class virl2_client.models.annotation.AnnotationLine(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)

Bases: _CoordinateXY2Mixin, Annotation

Annotation class representing line annotation.

__init__(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)
property line_end: str | None

Line arrow end style.

property line_start: str | None

Line arrow start style.

class virl2_client.models.annotation.AnnotationRectangle(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)

Bases: _CoordinateXY2Mixin, _RotationMixin, Annotation

Annotation class representing rectangle annotation.

__init__(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)
property border_radius: int

Border radius.

class virl2_client.models.annotation.AnnotationText(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)

Bases: _RotationMixin, Annotation

Annotation class representing text annotation.

__init__(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)
property text_bold: bool

Text boldness.

property text_content: str

Text annotation content.

property text_font: str

Text font.

property text_italic: bool

Text cursive.

property text_size: int

Size of the text.

property text_unit: str

Text size unit.

virl2_client.models.auth_management module

class virl2_client.models.auth_management.AuthManagement(session: Client, auto_sync=True, auto_sync_interval=1.0)

Bases: object

__init__(session: Client, auto_sync=True, auto_sync_interval=1.0)

Manage authentication settings and synchronization.

Parameters:

  • session – The httpx-based HTTP client for this session with the server.

  • auto_sync – Whether to automatically synchronize resource pools.

  • auto_sync_interval – How often to synchronize resource pools in seconds.

get_ldap_groups(search_filter=None)

Get CNs of groups available on the LDAP server, optionally filtered by supplied filter.

Parameters:

search_filter – An optional filter applied to the search.

Returns:

A list of CNs of found groups.

get_settings() → dict

Get a dictionary of the settings of the current authentication method.

Returns:

A dictionary of the settings of the current authentication method.

refresh_ldap_groups()

Refresh the members of LDAP groups. Removes any users from the group that are not LDAP users or not a part of said group on LDAP, and adds any users that are LDAP users and are a part of said group on LDAP.

sync() → None

Synchronize the authentication settings with the server.

sync_if_outdated() → None

Synchronize local data with the server if the auto sync interval has elapsed since the last synchronization.

test_auth(config: dict, username: str | None = None, password: str | None = None, group_name: str | None = None) → dict

Test a set of credentials and/or group against the specified authentication configuration.

Parameters:

  • config – A dictionary of authentication settings to test against (including manager password).

  • username – The username to test.

  • password – The password to test.

  • group_name – The group name to test.

Returns:

Results of the test.

test_current_auth(manager_password: str, username: str | None = None, password: str | None = None, group_name: str | None = None) → dict

Test a set of credentials and/or group against the currently applied authentication configuration.

Parameters:

  • manager_password – The manager password to allow testing.

  • username – The username to test.

  • password – The password to test.

  • group_name – The group name to test.

Returns:

Results of the test.

update_settings(settings_dict: dict | None = None, **kwargs) → None

Update multiple authentication settings at once.

This method is more efficient in batches than setting manager properties.

If passed a dictionary, it reads the dictionary for settings. If passed multiple keyword arguments, each is taken as a setting. Can mix and match; keywords take precedence.

Examples::

am = client.auth_management am.update_settings({“method”: “ldap”, “verify_tls”: False}) am.update_settings(method=”ldap”, verify_tls=False) # “verify_tls” key in dictionary overridden by keyword argument into False am.update_settings({“method”: “ldap”, “verify_tls”: True}, verify_tls=False)

Parameters:

  • settings_dict – A dictionary of settings.

  • kwargs – Setting keywords.

property manager: AuthMethodManager

Return the property manager for the current authentication method.

property method: str

Return the current authentication method.

class virl2_client.models.auth_management.AuthMethodManager(auth_management: AuthManagement)

Bases: object

Base class for managing authentication methods. Provides a mechanism to retrieve and update settings related to authentication methods.

__init__(auth_management: AuthManagement)

Initialize the AuthMethodManager with an instance of AuthManagement.

Parameters:

auth_management – An instance of AuthManagement.

METHOD = ''
class virl2_client.models.auth_management.LDAPManager(auth_management: AuthManagement)

Bases: AuthMethodManager

Manages LDAP authentication settings.

Extends the AuthMethodManager class and provides properties for retrieving and updating LDAP settings.

METHOD = 'ldap'
property admin_search_filter: str

Return the admin search filter.

property cert_data_pem: str

Return the PEM-encoded certificate data.

property display_attribute: str

Return the display name LDAP attribute.

property email_address_attribute: str

Return the email address LDAP attribute.

property group_display_attribute: str

Return the group display name LDAP attribute.

property group_membership_filter: str

Return the group membership filter.

property group_search_base: str

Return the group search base.

property group_search_filter: str

Return the group search filter.

property group_user_attribute: str

Return the group user attribute.

property group_via_user: bool

Return the flag indicating whether to use group via user.

property manager_dn: str

Return the manager DN.

property manager_password
property resource_pool: str

Return the resource pool a new user will be added to.

property root_dn: str

Return the root DN.

property server_urls: str

Return the LDAP server URLs.

property timeout: float

Return the LDAP request timeout in seconds.

property use_ntlm: bool

Return the flag indicating whether to use NTLM authentication.

property user_search_base: str

Return the user search base.

property user_search_filter: str

Return the user search filter.

property verify_tls: bool

Return the flag indicating whether to verify the TLS certificate.

class virl2_client.models.auth_management.RADIUSManager(auth_management: AuthManagement)

Bases: AuthMethodManager

Manages RADIUS authentication settings.

Extends the AuthMethodManager class and provides properties for retrieving and updating RADIUS settings.

METHOD = 'radius'
property nas_identifier: str

Return the NAS-Identifier used in requests.

property port: int

Return the default RADIUS server port.

property resource_pool: str

Return the resource pool a new user will be added to.

property secret
property server_hosts: str

Return the RADIUS server hosts.

property timeout: float

Return the RADIUS request timeout in seconds.

virl2_client.models.authentication module

class virl2_client.models.authentication.BlankAuth

Bases: Auth

A class that implements an httpx Auth object that does nothing.

auth_flow(request: Request) → Generator[Request, Response, None]

Execute the authentication flow.

To dispatch a request, yield it:

` yield request `

The client will .send() the response back into the flow generator. You can access it like so:

` response = yield request `

A return (or reaching the end of the generator) will result in the client returning the last response obtained from the server.

You can dispatch as many requests as is necessary.

class virl2_client.models.authentication.CustomClient(*args, **kwargs)

Bases: Client

__init__(*args, **kwargs)
class virl2_client.models.authentication.TokenAuth(client_library: ClientLibrary)

Bases: Auth

Token-based authentication for an httpx session.

Inspired by: https://requests.readthedocs.io/en/v2.9.1/user/authentication/?highlight=AuthBase#new-forms-of-authentication Modified for httpx based on: https://www.python-httpx.org/advanced/#customizing-authentication

__init__(client_library: ClientLibrary)

Initialize the TokenAuth object with a client library instance.

Parameters:

client_library – A client library instance.

auth_flow(request: Request) → Generator[Request, Response, None]

Implement the authentication flow for the token-based authentication.

Parameters:

request – The request object to authenticate.

Returns:

A generator of the authenticated request and response objects.

logout(clear_all_sessions=False) → bool

Log out the user (invalidate the current token).

Parameters:

clear_all_sessions – Whether to clear all sessions.

Returns:

Whether the logout succeeded.

requires_response_body = True
property token: str | None

Return the authentication token. If the token has not been set, it is obtained from the server.

virl2_client.models.authentication.make_session(base_url: str, ssl_verify: bool | str = True, client_type: str | None = None) → Client

Create an httpx Client object with the specified base URL and SSL verification setting.

Note: The base URL is automatically prepended to all HTTP calls. This means you should use _session.get("labs") rather than _session.get(base_url + "labs").

Parameters:

  • base_url – The base URL for the client.

  • ssl_verify – Whether to perform SSL verification.

  • client_type – The client type identifier.

Returns:

The created httpx Client object.

virl2_client.models.authentication.raise_for_status(response: Response)

https://github.com/encode/httpx/discussions/2224#discussioncomment-2732372

When raising for status from certain places, if response is unread, the stream is automatically closed, and we then cannot read the response in later error handling. We thus need to check if the response is 4/500 and read it preemptively if so.

virl2_client.models.cl_pyats module

class virl2_client.models.cl_pyats.ClPyats(lab: Lab, hostname: str | None = None)

Bases: object

__init__(lab: Lab, hostname: str | None = None) → None

Create 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 – The lab object to be used with pyATS.

  • hostname – Forced hostname or IP address and port of the console terminal server.

cleanup(node_label: str | None = None) → None

Clean up pyATS connections.

Parameters:

node_label – The label/title of a specific node to cleanup. If None, all connections will be cleaned up.

run_command(node_label: str, command: str, init_exec_commands: list[str] | None = None, init_config_commands: list[str] | None = None, **pyats_params: Any) → str

Run a command on the device in exec mode.

Parameters:

  • node_label – The label/title of the device.

  • command – The command to be run in exec mode.

  • init_exec_commands – A list of exec commands to be executed before the command. Default commands will be run if omitted. Pass an empty list to run no commands.

  • init_config_commands – A list of config commands to be executed before the command. Default commands will be run if omitted. Pass an empty list to run no commands.

  • pyats_params – Additional PyATS call parameters

Raises:
Returns:

The output from the device.

run_config_command(node_label: str, command: str, init_exec_commands: list[str] | None = None, init_config_commands: list[str] | None = None, **pyats_params: Any) → str

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

Parameters:

  • node_label – The label/title of the device.

  • command – The command to be run in configure mode.

  • init_exec_commands – A list of exec commands to be executed before the command. Default commands will be run if omitted. Pass an empty list to run no commands.

  • init_config_commands – A list of config commands to be executed before the command. Default commands will be run if omitted. Pass an empty list to run no commands.

  • pyats_params – Additional PyATS call parameters

Raises:
Returns:

The output from the device.

set_termserv_credentials(username: str | None = None, password: str | None = None, key_path: Path | str | None = None, ssh_options: str = '-o IdentitiesOnly=yes -o IdentityAgent=none') → None

Configure how to connect to the SSH terminal server after the testbed was synced with the server; the username must be known before making any connections. Then either set the password, or path to an identity file if SSH authentication with public keys is set up on the server. By default, this function disables authentication agents and identity files that would be loaded from the environment and running user ssh configuration, so that the passed password or key is attempted first. Pass empty string or custom SSH options to override this behavior.

Parameters:

  • username – The username to be set.

  • password – The password to be set.

  • key_path – The SSH key path to be set.

Raises:

PyatsNotInstalled – If pyATS is not installed.

switch_serial_console(node_label: str, console_number: int | str) → None

Switch to different serial console that is used to execute PyAts commands should be executed after sync_testbed and re-executed after every sync_testbed call.

Parameters:

  • node_label – The label/title of the device.

  • console_number – The serial console number to be used for PyAts.

Raises:
sync_testbed(username: str, password: str) → None

Sync the testbed (the latest topology data) from the server.

Parameters:

  • username – The username to be inserted into the testbed data.

  • password – The password to be inserted into the testbed data.

Raises:

PyatsNotInstalled – If pyATS is not installed.

property hostname: str | None

Return the forced hostname/IP and port terminal server setting.

virl2_client.models.group module

class virl2_client.models.group.GroupManagement(session: httpx.Client)

Bases: object

Manage groups.

__init__(session: httpx.Client) → None
associations(group_id: str) → list[dict[str, list[str]]]

Get a list of lab associations for a group.

Parameters:

group_id – The UUID4 of the group.

Returns:

A list of lab associations for this group.

create_group(name: str, **kwargs: Any) → dict

Create a group.

Parameters:

  • name – The name of the group.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • description: The description of the group.

  • members: The members of the group.

  • associations: The lab associations for the group.

  • labs: DEPRECATED: replaced by ‘associations’.

    The labs associated with the group.

Returns:

The created group object.

delete_group(group_id: str) → None

Delete a group.

Parameters:

group_id – The UUID4 of the group.

get_group(group_id: str) → dict

Get information for the specified group.

Parameters:

group_id – The UUID4 of the group.

Returns:

A group object.

group_id(group_name: str) → str

Get the unique UUID4 of a group.

Parameters:

group_name – The name of the group.

Returns:

The unique identifier of the group.

group_labs(group_id: str) → list[str]

DEPRECATED: Use .associations() instead. (Reason: adapted to the new format of lab associations)

Get a list of labs associated with a group.

Parameters:

group_id – The UUID4 of the group.

Returns:

A list of labs associated with this group.

group_members(group_id: str) → list[str]

Get the members of a group.

Parameters:

group_id – The UUID4 of the group.

Returns:

A list of users associated with this group.

groups() → list

Get the list of available groups.

Returns:

A list of group objects.

update_associations(group_id: str, associations: list[dict[str, list[str]]]) → dict

Update the lab associations for a group.

Parameters:

  • group_id – The UUID4 of the group.

  • associations – The new list of lab associations.

Returns:

The updated group object.

update_group(group_id: str, **kwargs: Any) → dict

Update a group.

Parameters:

  • group_id – The UUID4 of the group.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • name: The name of the group.

  • description: The description of the group.

  • members: The members of the group.

  • associations: The lab associations for the group.

  • labs: DEPRECATED: replaced by ‘associations’.

    The labs associated with the group.

Returns:

The updated group object.

virl2_client.models.groups module

virl2_client.models.interface module

class virl2_client.models.interface.Interface(iid: str, node: Node, label: str, slot: int | None, iface_type: str = 'physical', mac_address: str | None = None)

Bases: object

__init__(iid: str, node: Node, label: str, slot: int | None, iface_type: str = 'physical', mac_address: str | None = None) → None

A CML 2 network interface, part of a node.

Parameters:

  • iid – The interface ID.

  • node – The node object.

  • label – The label of the interface.

  • slot – The slot of the interface.

  • iface_type – The type of the interface.

  • mac_address – The MAC address of the interface.

as_dict() → dict[str, str | dict]

Convert the interface to a dictionary representation.

bring_up() → None

Bring up the interface.

Return the link between this interface and another.

Parameters:

other_interface – The other interface.

Returns:

A Link object if a link exists between the interfaces, None otherwise.

remove() → None

Remove the interface from the node.

shutdown() → None

Shutdown the interface.

property connected: bool

Check if the interface is connected to a link.

property deployed_mac_address: str | None

Return the deployed MAC address of the interface.

property discovered_ipv4: list[str] | None

Return the discovered IPv4 addresses of the interface.

property discovered_ipv6: list[str] | None

Return the discovered IPv6 addresses of the interface.

property discovered_mac_address: str | None

Return the discovered MAC address of the interface.

property id: str

Return the ID of the interface.

property ip_snooped_info: dict[str, list[str] | str | None]

Return the discovered MAC, IPv4 and IPv6 addresses of the interface in a dictionary.

property label: str

Return the label of the interface.

Get the link if the interface is connected, otherwise None.

property mac_address: str | None

Return the MAC address set to the interface. This is the address that will be used when the device is started.

property node: Node

Return the node object to which the interface belongs.

property operational: dict[str, Any]

Return the operational data for this interface.

property peer_interface: Interface | None

Return the peer interface connected to the interface.

property peer_node: Node | None

Return the node to which the peer interface belongs.

property physical: bool

Check if the interface is physical.

property readbytes: int

Return the number of bytes read by the interface.

property readpackets: int

Return the number of packets read by the interface.

property slot: int | None

Return the slot of the interface.

property state: str | None

Return the state of the interface.

property type: str

Return the type of the interface.

property writebytes: int

Return the number of bytes written by the interface.

property writepackets: int

Return the number of packets written by the interface.

virl2_client.models.lab module

class virl2_client.models.lab.Lab(title: str | None, lab_id: str, session: httpx.Client, username: str, password: str, auto_sync: bool = True, auto_sync_interval: float = 1.0, wait: bool = True, wait_max_iterations: int = 500, wait_time: int | float = 5, hostname: str | None = None, resource_pool_manager: ResourcePoolManagement | None = None, user_management: UserManagement | None = None)

Bases: object

__init__(title: str | None, lab_id: str, session: httpx.Client, username: str, password: str, auto_sync: bool = True, auto_sync_interval: float = 1.0, wait: bool = True, wait_max_iterations: int = 500, wait_time: int | float = 5, hostname: str | None = None, resource_pool_manager: ResourcePoolManagement | None = None, user_management: UserManagement | None = None) → None

A VIRL2 lab network topology.

Parameters:

  • title – Name or title of the lab.

  • lab_id – Lab ID.

  • session – The httpx-based HTTP client for this session with the server.

  • username – Username of the user to authenticate.

  • password – Password of the user to authenticate.

  • auto_sync – A flag indicating whether local changes should be automatically synced to the server.

  • auto_sync_interval – Interval in seconds for automatic syncing.

  • wait – A flag indicating whether to wait for convergence on the backend.

  • wait_max_iterations – Maximum number of iterations for convergence.

  • wait_time – Time in seconds to sleep between convergence calls on the backend.

  • hostname – Hostname/IP and port for pyATS console terminal server.

  • resource_pool_manager – ResourcePoolManagement object shared with parent ClientLibrary.

  • user_management – UserManagement object shared with parent ClientLibrary for resolving user IDs to usernames.

Raises:

VirlException – If the lab object is created without a resource pool manager.

annotations() → list[AnnotationType]

Return the list of annotations in the lab.

Returns:

A list of Annotation objects.

build_configurations() → None

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

cleanup_pyats_connections() → None

Close and clean up connection that pyATS might still hold.

clear_discovered_addresses() → None

Clear all discovered L3 addresses for all nodes in this lab from snooper.

connect_two_nodes(node1: Node, node2: Node, index: int = 0) → Link

Connect two nodes within a lab.

Parameters:

  • node1 – The first node object.

  • node2 – The second node object.

  • index – An optional starting interface index (default: 0).

Returns:

The created link.

create_annotation(annotation_type: str, **kwargs) → AnnotationType

Create a lab annotation.

Parameters:

  • annotation_type – Type of the annotation (rectangle, ellipse, line or text).

  • kwargs – Keyword arguments with annotation property values.

Returns:

The created annotation.

create_interface(node: Node | str, slot: int | None = None, wait: bool | None = None) → Interface

Create an interface in the next available slot, or, if a slot is specified, in all available slots up to and including the specified slot.

Parameters:

  • node – The node on which the interface is created.

  • slot – The slot number to create the interface in.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

Returns:

The newly created interface.

Create a link between two interfaces.

Parameters:

  • i1 – The first interface object or ID.

  • i2 – The second interface object or ID.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

Returns:

The created link.

create_node(label: str, node_definition: str, x: int = 0, y: int = 0, wait: bool | None = None, populate_interfaces: bool = False, **kwargs) → Node

Create a node in the lab with the given parameters.

Parameters:

  • label – Label.

  • node_definition – Node definition.

  • x – The X coordinate.

  • y – The Y coordinate.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

  • populate_interfaces – Automatically create a pre-defined number of interfaces on node creation.

  • kwargs – Optional parameters. See below.

Returns:

A Node object.

Keyword Arguments:

  • image_definition: The definition of the image used by this node.

  • configuration: The initial configuration of this node.

  • ram: The memory of the node in MiB (if applicable).

  • cpus: The number of CPUs in this node (if applicable).

  • cpu_limit: The CPU limit of the node (default is 100%).

  • data_volume: The size in GiB of the second HDD (if > 0).

  • boot_disk_size: The size in GiB of the boot disk

    (will expand to this size).

  • hide_links: A flag indicating whether the node’s links should be hidden

    in UI visualization.

  • tags: A list of tags associated with the node.

  • resource_pool: The ID of the resource pool if the node is part

    of a resource pool.

  • pinned_compute_id: The ID of the compute this node is pinned to.

    The node will not run on any other compute.

  • priority: The launch priority of the node (0-10000, or None).

    The higher the priority, the sooner the node will be started.

create_smart_annotation(tag: str, nodes: list[str | Node], **kwargs) → SmartAnnotation

Create a smart annotation in the lab. Smart annotations are automatically created when adding a new tag to a node, so this is simply a convenience function to add the tag to all listed nodes, retrieve the new smart annotation and update it with the given properties.

Parameters:

  • tag – Tag which the smart annotation will be bound to.

  • nodes – Nodes to which to add the tag and smart annotation.

  • kwargs – Keyword arguments with annotation property values. See models.SmartAnnotation for available properties.

Returns:

The created annotation.

details() → dict[str, str | list | int]

Retrieve the details of the lab, including its state.

Returns:

A dictionary containing the detailed lab state

download() → str

Download the lab from the server in YAML format.

Returns:

The lab in YAML format.

find_nodes_by_tag(tag: str) → list[Node]

Return the nodes identified by the given tag.

Parameters:

tag – The tag by which to search.

Returns:

A list of nodes.

get_annotation_by_id(annotation_id: str) → AnnotationType

Return the annotation identified by the ID.

Parameters:

annotation_id – ID of the annotation to be returned

Returns:

An Annotation object.

Raises:

AnnotationNotFound – If annotation is not found.

get_interface_by_id(interface_id: str) → Interface

Return the interface identified by the ID.

Parameters:

interface_id – ID of the interface to be returned.

Returns:

An Interface object.

Raises:

InterfaceNotFound – If the interface is not found.

Return the link identified by the ID.

Parameters:

link_id – ID of the link to be returned.

Returns:

A Link object.

Raises:

LinkNotFound – If the link is not found.

get_node_by_id(node_id: str) → Node

Return the node identified by the ID.

Parameters:

node_id – ID of the node to be returned.

Returns:

A Node object.

Raises:

NodeNotFound – If the node is not found.

get_node_by_label(label: str) → Node

Return the node identified by the label.

Parameters:

label – Label of the node to be returned.

Returns:

A Node object.

Raises:

NodeNotFound – If the node is not found.

get_pyats_testbed(hostname: str | None = None) → str

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 – Force hostname/ip and port for console terminal server.

Returns:

The pyATS testbed for the lab in YAML format.

get_smart_annotation_by_id(annotation_id: str) → SmartAnnotation

Return the smart annotation identified by the ID.

Parameters:

annotation_id – ID of the annotation to be returned.

Returns:

A SmartAnnotation object.

Raises:

SmartAnnotationNotFound – If annotation is not found.

get_smart_annotation_by_tag(tag: str) → SmartAnnotation

Return the smart annotation identified by the tag.

Parameters:

tag – Tag by which to search for the smart annotation.

Returns:

A SmartAnnotation object.

Raises:

SmartAnnotationNotFound – If annotation is not found.

has_converged() → bool

Check whether the lab has converged.

Returns:

True if the lab has converged, False otherwise.

import_lab(topology: dict) → None

Import a lab from a given topology.

Parameters:

topology – The topology to import.

interfaces() → list[Interface]

Return the list of interfaces in the lab.

Returns:

A list of Interface objects.

is_active() → bool

Check if the lab is active.

Returns:

True if the lab is active, False otherwise

Return the list of links in the lab.

Returns:

A list of Link objects.

need_to_wait(local_wait: bool | None) → bool

Check if waiting is required.

If local_wait is None, return the value of wait_for_convergence. If local_wait is not a boolean, raise a ValueError.

Parameters:

local_wait – Local wait flag.

Returns:

True if waiting is required, False otherwise.

Raises:

ValueError – If local_wait is not a boolean or None.

nodes() → list[Node]

Return the list of nodes in the lab.

Returns:

A list of Node objects.

remove() → None

Remove the lab from the server. The lab must be stopped and wiped first.

remove_annotation(annotation: Annotation | str) → None

Remove an annotation from the lab.

If you have an annotation object, you can also simply do:

annotation.remove()
Parameters:

annotation – The annotation object or ID.

remove_annotations() → None

Remove all annotations from the lab.

remove_interface(iface: Interface | str, wait: bool | None = None) → None

Remove an interface from the lab.

If you have an interface object, you can also simply do:

interface.remove()
Parameters:

  • iface – The interface object or ID.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

Remove a link from the lab.

If you have a link object, you can also simply do:

link.remove()
Parameters:

  • link – The link object or ID.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

remove_node(node: Node | str, wait: bool | None = None) → None

Remove a node from the lab.

If you have a node object, you can also simply do:

node.remove()
Parameters:

  • node – The node object or ID.

  • wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

remove_nodes(wait: bool | None = None) → None

Remove all nodes from the lab.

Parameters:

wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

remove_smart_annotation(annotation: SmartAnnotation | str) → None

Remove a smart annotation from the lab.

If you have a smart annotation object, you can also simply do:

smart_annotation.remove()
Parameters:

annotation – The annotation object or ID.

remove_smart_annotations() → None

Remove all smart annotations from the lab.

set_autostart(enabled: bool | None = None, priority: int | None | ~virl2_client.utils._Sentinel = <Unchanged>, delay: int | None | ~virl2_client.utils._Sentinel = <Unchanged>) → None

Set all autostart configuration properties.

Parameters:

  • enabled – Whether autostart is enabled.

  • priority – Priority of the lab autostart (0-10000, None for default).

  • delay – Delay in seconds before lab autostart (0-86400, None for default).

set_node_staging(enabled: bool | None = None, start_remaining: bool | None = None, abort_on_failure: bool | None = None) → None

Set all node staging configuration properties.

Parameters:

  • enabled – Whether node staging is enabled.

  • start_remaining – Whether to start remaining nodes after staging.

  • abort_on_failure – Whether to abort staging on failure.

smart_annotations() → list[SmartAnnotation]

Return the list of smart annotations in the lab.

Returns:

A list of SmartAnnotation objects.

start(wait: bool | None = None) → None

Start all the nodes and links in the lab.

Parameters:

wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

state() → str

Return the state of the lab.

Returns:

The state as text.

stop(wait: bool | None = None) → None

Stop all the nodes and links in the lab.

Parameters:

wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

sync(topology_only=True, exclude_configurations: bool | None = False) → None

Synchronize the current lab, locally applying changes made to the server.

Parameters:

  • topology_only – Only sync the topology without statistics and IP addresses.

  • exclude_configurations – Whether to exclude configurations from synchronization.

sync_events() → bool

Synchronize the events in the lab.

Returns:

True if the events have changed, False otherwise

sync_interfaces_operational() → None

Synchronize the operational state of all interfaces in the lab.

sync_l3_addresses_if_outdated() → None

Sync L3 addresses if they are outdated.

sync_layer3_addresses() → None

Sync all layer 3 IP addresses from the backend server.

sync_operational() → None

Sync the operational status of the lab.

sync_operational_if_outdated() → None

Sync the operational data if it is outdated.

sync_pyats() → None

Sync the pyATS testbed.

sync_states() → None

Sync all the states of the various elements with the backend server.

sync_states_if_outdated() → None

Sync states if they are outdated.

sync_statistics() → None

Retrieve the simulation statistic data from the back end server.

sync_statistics_if_outdated() → None

Sync statistics if they are outdated.

sync_topology_if_outdated(exclude_configurations=True) → None

Sync the topology if it is outdated.

update_associations(associations: dict[str, list[dict[str, list[str]]]]) → dict[str, list[dict[str, list[str]]]]

Modify lab/group/user associations.

Parameters:

associations – An object containing group and user list of objects consisting of ID and permissions.

Returns:

Updated object containing group and user list of objects consisting of ID and permissions.

update_connector_mappings(updates: list[dict[str, str]]) → list[dict[str, str]]

Update lab’s external connector mappings.

Accepts a list of mappings, each with a key to add or modify, and the associated device name (bridge) of the controller host. If no running external connector node uses this key, the device_name value may be None to disassociate the bridge from the key; if no node uses this key in its configuration, the mapping entry is removed.

Returns:

All connector mappings after updates were applied.

update_lab(topology: dict, exclude_configurations: bool) → None

Update the lab with the given topology.

Parameters:

  • topology – The updated topology.

  • exclude_configurations – Whether to exclude configurations from updating.

update_lab_groups(group_list: list[dict[str, str]]) → list[dict[str, str]]

DEPRECATED: Use .update_associations() instead. (Reason: adapted to new format of lab associations)

Modify lab/group association.

Parameters:

group_list – List of objects consisting of group ID and permissions.

Returns:

Updated objects consisting of group ID and permissions.

update_lab_properties(properties: dict[str, Any])

Update lab properties. Will not modify unspecified properties. Is not compatible with schema version 0.0.5.

Parameters:

properties – Dictionary containing the updated lab properties.

wait_until_lab_converged(max_iterations: int | None = None, wait_time: int | None = None) → None

Wait until the lab converges.

Parameters:

  • max_iterations – The maximum number of iterations to wait.

  • wait_time – The time to wait between iterations.

wipe(wait: bool | None = None) → None

Wipe all the nodes and links in the lab.

Parameters:

wait – A flag indicating whether to wait for convergence. If left at the default value, the lab’s wait property is used instead.

property associations: dict[str, list[dict[str, list[str]]]]

Return the group and user associations for this lab.

Returns:

An object containing group and user list of objects consisting of ID and permissions.

property autostart: dict[str, Any]

Return the autostart configuration as a dict.

property connector_mappings: list[dict[str, Any]]

Retrieve lab’s external connector mappings.

Returns a list of mappings; each mapping has a key, which is used as the configuration of external connector nodes, and a device name, used to uniquely identify the controller host’s bridge to use. If unset, the mapping is invalid and nodes using it cannot start.

property description: str

Return the description of the lab.

property groups: list[dict[str, str]]

Use .associations instead. (Reason: adapted to new format of lab associations)

Return the groups this lab is associated with.

Returns:

List of objects consisting of group ID and permissions.

Type:

DEPRECATED

property id: str

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

property node_staging: dict[str, bool]

Return the node staging configuration as a dict.

property notes: str

Return the notes of the lab.

property owner: str

Return the owner of the lab.

property resource_pools: list[ResourcePool]

Return the list of resource pools this lab’s nodes belong to.

property statistics: dict

Return lab statistics.

Returns:

A dictionary with stats of the lab.

property title: str | None

Return the title of the lab.

virl2_client.models.lab_repository module

class virl2_client.models.lab_repository.LabRepository(system, id: str, url: str, name: str, folder: str)

Bases: object

__init__(system, id: str, url: str, name: str, folder: str)

A lab repository, which provides access to lab templates and resources.

Parameters:

  • system – The SystemManagement instance.

  • id – The ID of the lab repository.

  • url – The URL of the lab repository.

  • name – The name of the lab repository.

  • folder – The folder name for the lab repository.

remove() → None

Remove the lab repository.

property folder: str

Return the folder name of the lab repository.

property id: str

Return the ID of the lab repository.

property name: str

Return the name of the lab repository.

property url: str

Return the URL of the lab repository.

class virl2_client.models.lab_repository.LabRepositoryManagement(system, session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0)

Bases: object

Manage lab repositories.

__init__(system, session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0) → None

Manage lab repositories.

Parameters:

  • system – The SystemManagement instance.

  • session – The httpx-based HTTP client for this session with the server.

  • auto_sync – A boolean indicating whether auto synchronization is enabled.

  • auto_sync_interval – The interval in seconds between auto synchronizations.

add_lab_repository(url: str, name: str, folder: str) → dict[str, Any]

Add a lab repository.

Parameters:

  • url – The URL of the lab repository.

  • name – The name of the lab repository.

  • folder – The folder name for the lab repository.

Returns:

The created lab repository data.

add_lab_repository_local(id: str, url: str, name: str, folder: str) → LabRepository

Add a lab repository locally.

Parameters:

  • id – The unique identifier of the lab repository.

  • url – The URL of the lab repository.

  • name – The name of the lab repository.

  • folder – The folder name for the lab repository.

Returns:

The newly created lab repository object.

get_lab_repositories() → list[dict[str, Any]]

Get the list of configured lab repositories.

Returns:

A list of lab repository objects.

get_lab_repository(repo_id: str) → LabRepository

Get a lab repository by its ID.

Parameters:

repo_id – The ID of the lab repository.

Returns:

The lab repository with the specified ID.

Raises:

LabRepositoryNotFound – If no lab repository with the specified ID is found.

get_lab_repository_by_name(name: str) → LabRepository

Get a lab repository by its name.

Parameters:

name – The name of the lab repository.

Returns:

The lab repository with the specified name.

Raises:

LabRepositoryNotFound – If no lab repository with the specified name is found.

refresh_lab_repositories() → dict[str, dict[str, Any]]

Performs a git pull on each configured lab repository and returns the result.

Returns:

A dictionary containing the refresh status for each repository.

sync_lab_repositories() → None

Synchronize lab repositories from the server.

sync_lab_repositories_if_outdated() → None

Synchronize lab repositories if they are outdated.

property lab_repositories: dict[str, LabRepository]

Return a dictionary of lab repositories.

virl2_client.models.licensing module

class virl2_client.models.licensing.Licensing(session: httpx.Client)

Bases: object

__init__(session: httpx.Client) → None

Manage licensing.

Parameters:

  • session – The httpx-based HTTP client for this session with the server.

  • is_cert_deprecated – Whether the certificate supported is deprecated.

cancel_reservation() → bool

Cancel reservation request without completing it.

complete_reservation(authorization_code: str) → str

Complete reservation by installing authorization code from SSMS.

delete_reservation_confirmation_code() → bool

Remove the reservation confirmation code.

delete_reservation_return_code() → bool

Remove the reservation return code.

deregister() → int

Request deregistration from the current SSMS.

disable_reservation_mode() → None

Disable reservation mode in unregistered agent.

discard_reservation(data: str) → str

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

enable_reservation_mode() → None

Enable reservation mode in unregistered agent.

features() → list[dict[str, str | int]]

DEPRECATED: Use .status() instead. (Reason: dropped in favor of single call to get the whole licensing status)

Get current licensing features.

get_reservation_confirmation_code() → str

Get the reservation confirmation code.

get_reservation_return_code() → str

Get the reservation return code.

register(token: str, reregister=False) → bool

Setup licensing registration.

register_renew() → bool

Request a renewal of licensing registration against current SSMS.

register_wait(token: str, reregister=False) → bool

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

release_reservation() → str

Return a completed reservation.

renew_authorization() → bool

Renew licensing authorization with the backend.

request_reservation() → str

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

reservation_mode(data: bool) → None

Enable or disable reservation mode in unregistered agent.

set_default_transport() → bool

Setup licensing transport configuration to default values.

set_product_license(product_license: str) → bool

Setup a product license.

set_transport(ssms: str | None, proxy_server: str | None = None, proxy_port: int | None = None) → bool

Setup licensing transport configuration.

status() → dict[str, Any]

Return current licensing configuration and status.

tech_support() → str

Return current licensing tech support.

update_features(features: dict[str, int] | list[dict[str, int]]) → None

Update licensing feature’s explicit count in reservation mode.

wait_for_status(what: str, *target_status: str) → None

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. :raises RuntimeError: When timeout is reached.

max_wait = 30
wait_interval = 1.5

virl2_client.models.node module

class virl2_client.models.node.Node(lab: Lab, nid: str, label: str, node_definition: str, **kwargs)

Bases: object

__init__(lab: Lab, nid: str, label: str, node_definition: str, **kwargs) → None

A VIRL2 node object representing a virtual machine that serves as a router, switch, or server.

Parameters:

  • lab – The Lab instance to which this node belongs.

  • nid – The ID of the node.

  • label – The label of the node.

  • node_definition – The definition of this node.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • image_definition: The definition of the image used by this node.

  • configuration: The initial configuration of this node.

  • x: The X coordinate of the node on the topology canvas.

  • y: The Y coordinate of the node on the topology canvas.

  • ram: The memory of the node in MiB (if applicable).

  • cpus: The number of CPUs in this node (if applicable).

  • cpu_limit: The CPU limit of the node (default is 100%).

  • data_volume: The size in GiB of the second HDD (if > 0).

  • boot_disk_size: The size in GiB of the boot disk

    (will expand to this size).

  • hide_links: A flag indicating whether the node’s links should be hidden

    in UI visualization.

  • tags: A list of tags associated with the node.

  • resource_pool: The ID of the resource pool if the node is part

    of a resource pool.

  • pinned_compute_id: The ID of the compute this node is pinned to.

    The node will not run on any other compute.

  • priority: The launch priority of the node (0-10000, or None).

    The higher the priority, the sooner the node will be started.

  • pyats: PyATS credentials for this node (if applicable).

add_tag(tag: str) → None

Add a tag to this node.

Parameters:

tag – The tag to add.

clear_discovered_addresses() → None

Clear all discovered L3 addresses for this node from the snooper.

clone_image() → dict

Clone the node’s disks into a new Image definition.

console_key(console_number: int = 0) → str

Get the console key of the node.

Parameters:

console_number – The console number (defaults to 0).

Returns:

The console key.

console_logs(console_id: int, lines: int | None = None) → dict

Get the console logs of the node.

Parameters:

  • console_id – The ID of the console.

  • lines – Limit the number of lines to retrieve.

Returns:

A dictionary containing the console logs.

create_interface(slot: int | None = None, wait: bool = False) → Interface

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

Parameters:

  • slot – The slot in which the interface will be created.

  • wait – Wait for the creation to complete.

Returns:

The newly created interface.

degree() → int

Return the degree of the node.

extract_configuration() → None

Update the configuration from the running node.

get_interface_by_label(label: str) → Interface

Get the interface of the node with the specified label.

Parameters:

label – The label of the interface.

Returns:

The interface with the specified label.

Raises:

InterfaceNotFound – If no interface with the specified label is found.

get_interface_by_slot(slot: int) → Interface

Get the interface of the node with the specified slot.

Parameters:

slot – The slot number of the interface.

Returns:

The interface with the specified slot.

Raises:

InterfaceNotFound – If no interface with the specified slot is found.

Return one link between this node and another.

Parameters:

other_node – The other node.

Returns:

A link between this node and the other node, if one exists.

Return all links between this node and another.

Parameters:

other_node – The other node.

Returns:

A list of links between this node and the other node.

has_converged() → bool

Check if the node has converged.

Returns:

True if the node has converged, False otherwise.

interfaces() → list[Interface]

Return a list of interfaces on the node.

is_active() → bool

Check if the node is in an active state.

Returns:

True if the node is in an active state, False otherwise.

is_booted() → bool

Check if the node is booted.

Returns:

True if the node is booted, False otherwise.

Return a list of links connected to this node.

map_l3_addresses_to_interfaces(mapping: dict[str, dict[str, str]]) → None

Map layer 3 addresses to interfaces.

This method updates all loaded interfaces on this node: - Interfaces present in the mapping get updated with new L3 address info - Interfaces NOT present in the mapping get their L3 addresses cleared

Parameters:

mapping – A dictionary mapping MAC addresses to interface information.

next_available_interface(index: int = 0) → Interface | None

Return 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!

Parameters:

index – An optional starting interface index (default: 0).

Returns:

An available physical interface or None if all existing ones are connected.

peer_interfaces() → list[Interface]

Return a list of interfaces connected to this node.

peer_nodes() → list[Node]

Return a list of nodes connected to this node.

physical_interfaces() → list[Interface]

Return a list of physical interfaces on the node.

remove() → None

Remove the node from the system.

remove_tag(tag: str) → None

Remove a tag from this node.

Parameters:

tag – The tag to remove.

run_pyats_command(command: str, **pyats_params: Any) → str

Run a pyATS command in exec mode on the node.

Parameters:

  • command – The command to run (e.g. “show version”).

  • pyats_params – Custom command dialog parameters for PyATS

Returns:

The output from the device.

run_pyats_config_command(command: str, **pyats_params: Any) → str

Run a pyATS command in config mode on the node.

Parameters:

  • command – The command to run (e.g. “interface gi0”).

  • pyats_params – Custom command dialog parameters for PyATS

Returns:

The output from the device.

set_pyats_credentials(username: str | None | ~virl2_client.utils._Sentinel = <Unchanged>, password: str | None | ~virl2_client.utils._Sentinel = <Unchanged>, enable_password: str | None | ~virl2_client.utils._Sentinel = <Unchanged>) → None

Set pyATS credentials for this node.

Parameters:

  • username – The username to set, or None to clear it.

  • password – The password to set, or None to clear it.

  • enable_password – The enable password to set, or None to clear it.

This updates the node on the controller with a pyats field whose structure matches the backend expectation, typically:

{
    "username": "<user>",
    "password": "<pass>",
    "enable_password": "<enable_password_pass>"
}
start(wait=False) → None

Start the node.

Parameters:

wait – Whether to wait until the node has converged.

stop(wait=False) → None

Stop the node.

Parameters:

wait – Whether to wait until the node has converged.

sync_interface_operational() → None

Synchronize the operational state of the node’s interfaces.

sync_interface_operational_if_outdated() → None
sync_l3_addresses_if_outdated() → None
sync_layer3_addresses() → None

Acquire all layer 3 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.

If the node is not running or there’s an error fetching L3 addresses, this method will silently clear the discovered addresses rather than raising an exception.

sync_operational(response: dict[str, Any] | None = None) → None

Synchronize the operational state of the node.

Parameters:

response – If the operational data was fetched from the server elsewhere, it can be passed here to save an API call. Will be fetched automatically otherwise.

sync_operational_if_outdated() → None
tags() → list[str]

Get the tags set on this node.

Returns:

A list of tags.

update(node_data: dict[str, Any], exclude_configurations: bool, push_to_server=None) → None

Update the node with the provided data.

Parameters:

  • node_data – The data to update the node with.

  • exclude_configurations – Whether to exclude configuration updates.

  • push_to_server – DEPRECATED: Was only used by internal methods and should otherwise always be True.

update_parameters(new_params: dict) → None

Update node parameters. If parameter doesn’t exist it will be created. Existing nodes will be updated. To delete parameter set its value to None.

vnc_key() → str

Get the VNC key of the node.

Returns:

The VNC key.

wait_until_converged(max_iterations: int | None = None, wait_time: int | None = None) → None

Wait until the node has converged.

Parameters:

  • max_iterations – The maximum number of iterations to wait for convergence.

  • wait_time – The time to wait between iterations.

Raises:

RuntimeError – If the node does not converge within the specified number of iterations.

wipe(wait=False) → None

Wipe the node’s disks.

Parameters:

wait – Whether to wait until the node has converged.

property boot_disk_size: int

Return the size of the boot disk in GiB.

property compute_id

Return the ID of the compute this node is assigned to.

property configuration: str | None

Return the contents of the main configuration file.

property configuration_files: list[dict[str, str]] | None

Return all configuration files, in a list in the following format: [{“name”: “filename.txt”, “content”: “<file content>”}]

property cpu_limit: int

Return the CPU limit of the node.

property cpu_usage: int | float

Return the CPU usage of this node.

property cpus: int

Return the number of CPUs assigned to the node.

property data_volume: int

Return the size (in GiB) of the second HDD.

property disk_read: int

Return the amount of disk read by this node.

property disk_write: int

Return the amount of disk write by this node.

Return a flag indicating whether the node’s links should be hidden in UI visualization.

property id: str

Return the ID of the node.

property image_definition: str | None

Return the definition of the image used by this node.

property lab: Lab

Return the lab of the node.

property label: str

Return the label of the node.

property node_definition: str

Return the definition of this node.

property operational: dict[str, Any]

Return the full operational data as a dictionary.

property parameters: dict

Return node parameters.

property pinned_compute_id: str | None

Return the ID of the compute this node is pinned to.

property priority: int | None

Return the priority of the node.

property pyats_credentials: dict[str, str | None]

Return pyATS credentials for this node, if configured.

The value is expected to be a mapping with “username” and “password” keys, as provided by the backend (for example via the node’s node definition).

property ram: int

Return the RAM size of the node in bytes.

property resource_pool: str

Return the ID of the resource pool if the node is part of a resource pool.

property smart_annotations: dict[str, SmartAnnotation]

Return the tags on this node and their corresponding smart annotations.

property state: str | None

Return the state of the node.

property x: int

Return the X coordinate of the node.

property y: int

Return the Y coordinate of the node.

virl2_client.models.node_image_definition module

class virl2_client.models.node_image_definition.NodeImageDefinitions(session: httpx.Client)

Bases: object

__init__(session: httpx.Client) → None

Manage node and image definitions.

Node definitions define the properties of a virtual network node. Image definitions define disk images that are required to boot a network node. Together, they define a complete virtual network node.

Parameters:

session – The httpx-based HTTP client for this session with the server.

download_image_definition(definition_id: str) → str

Return the image definition for a given definition ID.

Example:

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

definition_id – The ID of the image definition.

Returns:

The image definition as YAML.

download_image_file_list() → list[str]

Return a list of image files.

Returns:

A list of image file names.

download_node_definition(definition_id: str) → str

Return the node definition for a given definition ID.

Example:

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

definition_id – The ID of the node definition.

Returns:

The node definition as YAML.

image_definitions() → list[dict]

Return all image definitions.

Returns:

A list of image definitions.

image_definitions_for_node_definition(definition_id: str) → list[dict]

Return all image definitions for a given node definition.

Parameters:

definition_id – The ID of the node definition.

Returns:

A list of image definition objects.

node_definitions() → list[dict]

Return all node definitions.

Returns:

A list of node definitions.

remove_dropfolder_image(filename: str) → str

Remove an image file from the drop folder.

Parameters:

filename – The name of the image file to remove.

Returns:

“Success”.

remove_image_definition(definition_id: str) → None

Remove the image definition with the given ID.

Example:

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

definition_id – The ID of the image definition to remove.

remove_node_definition(definition_id: str) → None

Remove the node definition with the given ID.

Example:

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

definition_id – The ID of the node definition to remove.

set_image_definition_read_only(definition_id: str, read_only: bool) → dict

Set the read-only attribute of the image definition with the given ID.

Parameters:

  • definition_id – The ID of the image definition.

  • read_only – The new value of the read-only attribute.

Returns:

The modified image definition.

set_node_definition_read_only(definition_id: str, read_only: bool) → dict

Set the read-only attribute of the node definition with the given ID.

Parameters:

  • definition_id – The ID of the node definition.

  • read_only – The new value of the read-only attribute.

Returns:

The modified node definition.

upload_image_definition(body: str | dict, update: bool = False) → str

Upload a new image definition.

Parameters:

  • body – The image definition (yaml or json).

  • update – If creating a new image definition or updating an existing one.

Returns:

“Success”.

upload_image_file(filename: Path | str, rename: str | None = None) → None

Upload an image file.

Parameters:

  • filename – The path of the image to upload.

  • rename – Optional filename to rename to.

upload_node_definition(body: str | dict, update: bool = False) → str

Upload a new node definition.

Parameters:

  • body – The node definition (yaml or json).

  • update – If creating a new node definition or updating an existing one.

Returns:

“Success”.

virl2_client.models.node_image_definition.print_progress_bar(cur: int, total: int, start_time: float, length=50) → None

Print a progress bar.

Parameters:

  • cur – The current progress value.

  • total – The total progress value.

  • start_time – The start time of the progress.

  • length – The length of the progress bar.

virl2_client.models.node_image_definitions module

virl2_client.models.resource_pool module

class virl2_client.models.resource_pool.ResourcePool(resource_pools: ResourcePoolManagement, pool_id: str, label: str, description: str | None, template: str | None, licenses: int | None, ram: int | None, cpus: int | None, disk_space: int | None, external_connectors: list[str] | None, users: list[str] | None, user_pools: list[str] | None)

Bases: object

__init__(resource_pools: ResourcePoolManagement, pool_id: str, label: str, description: str | None, template: str | None, licenses: int | None, ram: int | None, cpus: int | None, disk_space: int | None, external_connectors: list[str] | None, users: list[str] | None, user_pools: list[str] | None)

Initialize a resource pool.

Parameters:

  • resource_pools – The parent ResourcePoolManagement object.

  • pool_id – The ID of the resource pool.

  • label – The label of the resource pool.

  • description – The description of the resource pool.

  • template – The template of the resource pool.

  • licenses – The number of licenses in the resource pool.

  • ram – The amount of RAM in the resource pool.

  • cpus – The number of CPUs in the resource pool.

  • disk_space – The amount of disk space in the resource pool.

  • external_connectors – A list of external connectors in the resource pool.

  • users – A list of users in the resource pool.

  • user_pools – A list of user pools in the resource pool.

get_usage() → ResourcePoolUsage

Get the usage stats of the resource pool.

remove() → None

Remove the resource pool.

update(pool_data: dict[str, Any], push_to_server=None) → None

Update multiple properties of the pool at once.

Parameters:

  • pool_data – A dictionary of the properties to update.

  • push_to_server – DEPRECATED: Was only used by internal methods and should otherwise always be True.

property cpus: int

Return the number of CPUs in the resource pool.

property description: str

Return the description of the resource pool.

property disk_space: int

Return the amount of disk space in the resource pool.

property external_connectors: list[str] | None

Return a list of external connectors in the resource pool.

property id: str

Return the ID of the resource pool.

property is_template: bool

Return whether the resource pool is a template.

property label: str

Set the label of the resource pool.

property licenses: int

Return the number of licenses in the resource pool.

property ram: int

Return the amount of RAM in the resource pool.

property template: str

Return the template of the resource pool.

property user_pools: list[str]

Return the list of user pools in the template.

property users: list[str]

Return the list of users in the resource pool.

class virl2_client.models.resource_pool.ResourcePoolManagement(session: httpx.Client, auto_sync=True, auto_sync_interval=1.0)

Bases: object

__init__(session: httpx.Client, auto_sync=True, auto_sync_interval=1.0)

Manage and synchronize resource pools.

Parameters:

  • session – The httpx-based HTTP client for this session with the server.

  • auto_sync – Whether to automatically synchronize resource pools.

  • auto_sync_interval – How often to synchronize resource pools in seconds.

create_resource_pool(label: str, **kwargs) → ResourcePool

Create a resource pool with the given parameters.

Parameters:

  • label – The label for the resource pools.

  • kwargs – Additional resource pool parameters as accepted by the ResourcePool object.

Returns:

The created ResourcePool object.

create_resource_pools(label: str, users: list[str], **kwargs) → list[ResourcePool]

Create a list of resource pools with the given parameters. If no template is supplied, a new template pool is created with the specified parameters, and each user is assigned a new pool with no additional limits. If a template pool is supplied, then parameters are applied to each user pool.

Parameters:

  • label – The label for the resource pools.

  • users – The list of user IDs for which to create resource pools.

  • kwargs – Additional resource pool parameters as accepted by the ResourcePool object.

Returns:

A list of created resource pool objects, with the template pool first if created.

get_resource_pools_by_ids(resource_pool_ids: str | Iterable[str]) → ResourcePool | dict[str, ResourcePool]

Get resource pools by their IDs.

Parameters:

resource_pool_ids – A resource pool ID or an iterable of IDs.

Returns:

A ResourcePool object when one ID is passed, or a dictionary of IDs to either ResourcePools when a resource pool exists or None when it doesn’t.

Raises:

KeyError – When one ID is passed, and it doesn’t exist.

sync_resource_pools() → None

Synchronize the resource pools with the server.

sync_resource_pools_if_outdated() → None

Synchronize resource pools if they are outdated.

property resource_pools: dict[str, ResourcePool]

Return all resource pools.

class virl2_client.models.resource_pool.ResourcePoolUsage(limit: 'ResourcePoolUsageBase', usage: 'ResourcePoolUsageBase')

Bases: object

__init__(limit: ResourcePoolUsageBase, usage: ResourcePoolUsageBase) → None
limit: ResourcePoolUsageBase
usage: ResourcePoolUsageBase
class virl2_client.models.resource_pool.ResourcePoolUsageBase(licenses: 'int', cpus: 'int', ram: 'int', disk_space: 'int', external_connectors: 'list')

Bases: object

__init__(licenses: int, cpus: int, ram: int, disk_space: int, external_connectors: list) → None
cpus: int
disk_space: int
external_connectors: list
licenses: int
ram: int

virl2_client.models.resource_pools module

virl2_client.models.smart_annotation module

class virl2_client.models.smart_annotation.SmartAnnotation(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None)

Bases: object

__init__(lab: Lab, annotation_id: str, annotation_data: dict[str, Any] | None = None) → None

A VIRL2 lab smart annotation.

Parameters:

  • lab – The lab object to which the smart annotation belongs.

  • annotation_id – The ID of the smart annotation.

as_dict() → dict[str, Any]

Convert the smart annotation object to a dictionary representation.

Returns:

A dictionary representation of the smart annotation object.

remove() → None

Remove smart annotation from the lab.

update(annotation_data: dict[str, Any]) → None

Update smart annotation properties.

Parameters:

annotation_data – JSON dict with new annotation property:value pairs.

property border_color: str

#00000080).

Type:

Border color (example

property border_style: str

‘’ (solid), ‘2,2’ (dotted), ‘4,2’ (dashed).

Type:

Border style; valid values

property fill_color: str

#00000080).

Type:

Fill color (example

property group_distance: int

Group distance.

property id: str

Return ID of the smart annotation.

property is_on: bool

Whether the smart annotation is enabled.

property lab: Lab

Return the lab of the smart annotation.

property label: str

Label.

property padding: int

Padding.

property tag: str

Tag.

property tag_offset_x: int

Tag X offset.

property tag_offset_y: int

Tag Y offset.

property tag_size: int

Tag size.

property thickness: int

Thickness.

property z_index: int

Z index.

virl2_client.models.system module

class virl2_client.models.system.ComputeHost(system: SystemManagement, compute_id: str, hostname: str, server_address: str, is_connector: bool, is_simulator: bool, is_connected: bool, is_synced: bool, admission_state: str, node_counts: dict[str, int], nodes: list[str] | None = None)

Bases: object

__init__(system: SystemManagement, compute_id: str, hostname: str, server_address: str, is_connector: bool, is_simulator: bool, is_connected: bool, is_synced: bool, admission_state: str, node_counts: dict[str, int], nodes: list[str] | None = None)

A compute host, which hosts some of the nodes of the simulation.

Parameters:

  • system – The SystemManagement instance.

  • compute_id – The ID of the compute host.

  • hostname – The hostname of the compute host.

  • server_address – The server address of the compute host.

  • is_connector – Whether the compute host is a connector.

  • is_simulator – Whether the compute host is a simulator.

  • is_connected – Whether the compute host is connected.

  • is_synced – Whether the compute host is synced.

  • admission_state – The admission state of the compute host.

  • node_counts – The counts of deployed and running nodes and orphans.

  • nodes – DEPRECATED: replaced by node_counts. The list of node IDs associated with the compute host.

remove() → None

Remove the compute host.

update(host_data: dict[str, Any], push_to_server=None) → None

Update the compute host with the given data.

Parameters:

  • host_data – The data to update the compute host.

  • push_to_server – DEPRECATED: Was only used by internal methods and should otherwise always be True.

property admission_state: str

Return the admission state of the compute host.

property compute_id: str

Return the ID of the compute host.

property hostname: str

Return the hostname of the compute host.

property is_connected: bool

Return whether the compute host is connected.

property is_connector: bool

Return whether the compute host is a connector.

property is_simulator: bool

Return whether the compute host is a simulator.

property is_synced: bool

Return whether the compute host is synced.

property node_counts: dict[str, int]

Return the counts of deployed and running nodes and orphans.

property nodes: list[str]

Return the list of nodes associated with the compute host.

property server_address: str

Return the server address of the compute host.

class virl2_client.models.system.SystemManagement(session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0)

Bases: object

__init__(session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0)

Manage the underlying controller software and the host system where it runs.

Parameters:

  • session – The httpx-based HTTP client for this session with the server.

  • auto_sync – A boolean indicating whether auto synchronization is enabled.

  • auto_sync_interval – The interval in seconds between auto synchronizations.

add_compute_host_local(compute_id: str, hostname: str, server_address: str, is_connector: bool, is_simulator: bool, is_connected: bool, is_synced: bool, admission_state: str, node_counts: dict[str, int], nodes: list[str] | None = None) → ComputeHost

Add a compute host locally.

Parameters:

  • compute_id – The ID of the compute host.

  • hostname – The hostname of the compute host.

  • server_address – The server address of the compute host.

  • is_connector – A boolean indicating if the compute host is a connector.

  • is_simulator – A boolean indicating if the compute host is a simulator.

  • is_connected – A boolean indicating if the compute host is connected.

  • is_synced – A boolean indicating if the compute host is synced.

  • admission_state – The admission state of the compute host.

  • node_counts – Count of deployed and running nodes and orphans.

  • nodes – A list of node IDs associated with the compute host.

Returns:

The added compute host.

add_system_notice_local(id: str, level: str, label: str, content: str, enabled: bool, acknowledged: dict[str, bool], groups: list[str] | None = None) → SystemNotice

Add a system notice locally.

Parameters:

  • id – The unique identifier of the system notice.

  • level – The level of the system notice.

  • label – The label or title of the system notice.

  • content – The content or description of the system notice.

  • enabled – A flag indicating whether the system notice is enabled or not.

  • acknowledged – A dictionary mapping user IDs to their acknowledgment status.

  • groups – A list of group names to associate with the system notice. (Optional)

Returns:

The newly created system notice object.

delete_external_connector(connector_id: str) → None

Delete an external connector.

Parameters:

connector_id – The ID of the connector to delete.

get_external_connectors(sync: bool | None = None) → list[dict[str, str]]

Get the list of external connectors present on the controller. Device names or tags are used as External Connector nodes’ configuration.

Parameters:

sync – Admin only. A boolean indicating whether to refresh the cached list from host state. If sync is False, the state is retrieved; if True, configuration is applied back into the controller host.

Returns:

A list of objects with the device name and label.

get_new_compute_host_state() → str

Get the admission state of the new compute host.

Returns:

The admission state of the new compute host.

get_telemetry_events() → list[dict[str, Any]]

Return the list of telemetry events.

get_web_session_timeout() → int

Get the web session timeout in seconds.

Returns:

The web session timeout.

set_new_compute_host_state(admission_state: str) → str

Set the admission state of the new compute host.

Parameters:

admission_state – The admission state to set.

Returns:

The updated admission state.

set_web_session_timeout(timeout: int) → None

Set the web session timeout in seconds.

Parameters:

timeout – The timeout value in seconds.

Returns:

None

sync_compute_hosts() → None

Synchronize compute hosts from the server.

sync_compute_hosts_if_outdated() → None

Synchronize compute hosts if they are outdated.

sync_system_notices() → None

Synchronize system notices from the server.

sync_system_notices_if_outdated() → None

Synchronize system notices if they are outdated.

update_external_connector(connector_id: str, data: dict[str, Any]) → dict[str, Any]

Update an external connector.

Parameters:

  • connector_id – The ID of the connector to update.

  • data – The data to update.

Returns:

The updated data.

property compute_hosts: dict[str, ComputeHost]

Return a dictionary of compute hosts.

property controller: ComputeHost

Return the controller

Raises:

ControllerNotFound – If no controller has been found (should never be the case).

Returns:

The controller object.

property maintenance_mode: bool

Return the maintenance mode status.

property maintenance_notice: SystemNotice | None

Return the current maintenance notice.

property system_notices: dict[str, SystemNotice]

Return a dictionary of system notices.

property telemetry: dict[str, OptInStatus | str]

Return the telemetry state.

property telemetry_state: OptInStatus

Return the telemetry state.

class virl2_client.models.system.SystemNotice(system: SystemManagement, id: str, level: str, label: str, content: str, enabled: bool, acknowledged: dict[str, bool], groups: list[str] | None = None)

Bases: object

__init__(system: SystemManagement, id: str, level: str, label: str, content: str, enabled: bool, acknowledged: dict[str, bool], groups: list[str] | None = None)

A system notice, which notifies users of maintenance or other events.

Parameters:

  • system – The SystemManagement instance.

  • id – The ID of the system notice.

  • level – The level of the system notice.

  • label – The label of the system notice.

  • content – The content of the system notice.

  • enabled – Whether the system notice is enabled.

  • acknowledged – The acknowledgement status of the system notice.

  • groups – The groups associated with the system notice.

remove() → None

Remove the system notice.

update(notice_data: dict[str, Any], push_to_server=None) → None

Update the system notice with the given data.

Parameters:

  • notice_data – The data to update the system notice with.

  • push_to_server – DEPRECATED: Was only used by internal methods and should otherwise always be True.

property acknowledged: dict[str, bool]

Return the acknowledgement status of the system notice.

property content: str

Return the content of the system notice.

property enabled: bool

Return whether the system notice is enabled.

property groups: list[str] | None

Return the groups associated with the system notice.

property id: str

Return the ID of the system notice.

property label: str

Return the label of the system notice.

property level: str

Return the level of the system notice.

virl2_client.models.user module

class virl2_client.models.user.UserManagement(session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0)

Bases: object

__init__(session: httpx.Client, auto_sync: bool = True, auto_sync_interval: float = 1.0) → None
associations(user_id: str) → list[dict[str, list[str]]]

Get a list of lab associations for a user.

Parameters:

user_id – The UUID4 of the user.

Returns:

A list of lab associations for this user.

create_user(username: str, pwd: str, **kwargs: dict[str, Any]) → dict

Create a new user.

Parameters:

  • username – Username.

  • pwd – Desired password.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • fullname: Full name.

  • description: Description.

  • email: Email address.

  • admin: Whether to create an admin user.

  • groups: List of groups to which the user should be added.

  • associations: List of lab associations for the user.

  • resource_pool: Resource pool to which the user should be added.

  • opt_in: Whether the user has seen the initial contact dialog.

  • tour_version: The version of the Workbench tour the user has completed.

  • pubkey: An SSH public key for terminal server. Empty string to clear.

Returns:

User object.

delete_user(user_id: str) → None

Delete a user.

Parameters:

user_id – User UUID4.

get_user(user_id: str) → dict

Get user information.

Parameters:

user_id – User UUID4.

Returns:

User object.

get_username(user_id: str) → str | None

Look up a username by user ID from the locally synced user list.

Triggers a sync if the local list is outdated. Returns None if the user_id is not found.

Parameters:

user_id – User UUID4.

Returns:

The username, or None if not found.

sync_users() → None

Fetch all users from the server and store them locally.

sync_users_if_outdated() → None

Synchronize the user list if the auto-sync interval has elapsed.

update_associations(user_id: str, associations: list[dict[str, list[str]]]) → dict

Update the lab associations for a user.

Parameters:

  • user_id – The UUID4 of the user.

  • associations – The new list of lab associations.

Returns:

The updated user object.

update_user(user_id: str, **kwargs: dict[str, Any]) → dict

Update an existing user.

Parameters:

  • user_id – User UUID4.

  • kwargs – Optional parameters. See below.

Keyword Arguments:

  • fullname: Full name.

  • description: Description.

  • email: Email address.

  • admin: Whether to create an admin user.

  • groups: List of groups to which the user should be added.

  • associations: List of lab associations for the user.

  • password_dict: Dictionary containing old and new passwords.

  • resource_pool: Resource pool to which the user should be added.

  • opt_in: Whether the user has seen the initial contact dialog.

  • tour_version: The version of the Workbench tour the user has completed.

  • pubkey: An SSH public key for terminal server. Empty string to clear.

Returns:

User object.

user_groups(user_id: str) → list[str]

Get the groups that a user is a member of.

Parameters:

user_id – User UUID4.

Returns:

List of group names.

user_id(username: str) → str

Get the unique UUID4 of a user.

Parameters:

username – User name.

Returns:

User unique identifier.

users() → list[dict]

Get the list of available users.

Returns:

List of user IDs.

virl2_client.models.users module