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.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_settings() → dict

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

Returns:

A dictionary of the settings of the current authentication method.

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, password: str) → dict

Test a set of credentials 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.

Returns:

Results of the test.

test_current_auth(manager_password: str, username: str, password: str) → dict

Test a set of credentials 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.

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
create_group(name: str, description: str = '', members: list[str] | None = None, labs: list[dict[str, str]] | None = None) → dict

Create a group.

Parameters:

  • name – The name of the group.

  • description – The description of the group.

  • members – The members of the group.

  • labs – 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]

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_group(group_id: str, name: str | None = None, description: str | None = <Unchanged>, members: list[str] | None = <Unchanged>, labs: list[dict[str, str]] | None = <Unchanged>) → dict

Update a group.

Parameters:

  • group_id – The UUID4 of the group.

  • name – The new name of the group.

  • description – The description of the group.

  • members – The members of the group.

  • labs – 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')

Bases: object

__init__(iid: str, node: Node, label: str, slot: int | None, iface_type: str = 'physical') → 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.

as_dict() → dict[str, str]

Convert the interface to a dictionary representation.

bring_up() → None

Bring up the interface.

degree()

DEPRECATED: Use .connected instead. (Reason: degree always 0 or 1)

Return the degree of 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.

is_connected()

DEPRECATED: Use .connected instead. (Reason: should have been a parameter, renamed to match similar parameters)

Check if the interface is connected to a link.

DEPRECATED: Use .link instead. (Reason: pointless plural, could have been a parameter)

Return the link connected to this interface in a list.

peer_interfaces()

DEPRECATED: Use .peer_interface instead. (Reason: pointless plural, could have been a parameter)

Return the peer interface connected to this interface in a set.

peer_nodes()

DEPRECATED: Use .peer_node instead. (Reason: pointless plural, could have been a parameter)

Return the node of the peer interface in a set.

remove() → None

Remove the interface from the node.

remove_on_server() → None

DEPRECATED: Use .remove() instead. (Reason: was never meant to be public, removing only on server is not useful)

Remove the interface on the server.

shutdown() → None

Shutdown the interface.

property connected: bool

Check if the interface is connected to a link.

property discovered_ipv4: str | None

Return the discovered IPv4 address of the interface.

property discovered_ipv6: str | None

Return the discovered IPv6 address 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, str | None]

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

property is_physical: bool

Use .physical instead. (Reason: renamed to match similar parameters)

Check if the interface is physical.

Type:

DEPRECATED

property label: str

Return the label of the interface.

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

property node: Node

Return the node object to which the interface belongs.

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 = 5, hostname: str | None = None, resource_pool_manager: ResourcePoolManagement | 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 = 5, hostname: str | None = None, resource_pool_manager: ResourcePoolManagement | 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.

Raises:

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

add_node_local(*args, **kwargs)

DEPRECATED: Use .create_node() instead. (Reason: only creates a node in the client, which is not useful; if really needed, use ._create_node_local())

Creates a node in the client, but not on the server.

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.

connect_two_nodes(node1: Node, node2: Node) → Link

Connect two nodes within a lab.

Parameters:

  • node1 – The first node object.

  • node2 – The second node object.

Returns:

The created link.

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

Create a lab annotation.

Parameters:

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

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.

Returns:

A Node object.

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.

DEPRECATED: Use Interface.get_link_to() instead. (Reason: redundancy)

Return the link identified by two interface objects.

Parameters:

  • iface1 – The first interface.

  • iface2 – The second interface.

Returns:

The link between the interfaces.

Raises:

LinkNotFound – If no such link exists.

DEPRECATED: Use Node.get_link_to() to get one link or Node.get_links_to() to get all links. (Reason: redundancy)

Return ONE of the links identified by two node objects.

Parameters:

  • node1 – The first node.

  • node2 – The second node.

Returns:

One of links between the nodes.

Raises:

LinkNotFound – If no such link exists.

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.

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.

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, with_node_configurations: bool | None = None, 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.

  • with_node_configurations – DEPRECATED: does the opposite of what is expected. Use exclude_configurations instead.

  • 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_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_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]]

Modify lab/group association.

Parameters:

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

Returns:

Updated objects consisting of group ID and permission.

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

Return the groups this lab is associated with.

property id: str

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

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.Licensing(session: httpx.Client, is_cert_deprecated: bool)

Bases: object

__init__(session: httpx.Client, is_cert_deprecated: bool) → 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]]

Get current licensing features.

get_certificate() → str | None

DEPRECATED: There is no replacement as the certificate support was dropped. (Reason: the certificate support was dropped in CML 2.7.0)

Get the currently installed licensing public certificate.

get_reservation_confirmation_code() → str

Get the reservation confirmation code.

get_reservation_return_code() → str

Get the reservation return code.

install_certificate(cert: str) → bool

DEPRECATED: There is no replacement as the certificate support was dropped. (Reason: the certificate support was dropped in CML 2.7.0)

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

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.

remove_certificate() → bool

DEPRECATED: There is no replacement as the certificate support was dropped. (Reason: the certificate support was dropped in CML 2.7.0)

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

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, 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.

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.

remove_on_server() → None

DEPRECATED: Use .remove() instead. (Reason: was never meant to be public, removing only on server is not useful)

Remove the link on the server.

set_condition(bandwidth: int, latency: int, jitter: int, loss: float) → 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 percentage (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.

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

Stop the link.

Parameters:

wait – Whether to wait for convergence after stopping the 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 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, image_definition: str | None, configuration: list[dict[str, str]] | str | None, x: int, y: int, ram: int | None, cpus: int | None, cpu_limit: int | None, data_volume: int | None, boot_disk_size: int | None, hide_links: bool, tags: list[str], resource_pool: str | None, parameters: dict, pinned_compute_id: str | None)

Bases: object

__init__(lab: Lab, nid: str, label: str, node_definition: str, image_definition: str | None, configuration: list[dict[str, str]] | str | None, x: int, y: int, ram: int | None, cpus: int | None, cpu_limit: int | None, data_volume: int | None, boot_disk_size: int | None, hide_links: bool, tags: list[str], resource_pool: str | None, parameters: dict, pinned_compute_id: str | None) → 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.

  • 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.

add_tag(tag: str) → None

Add a tag to this node.

Parameters:

tag – The tag to add.

console_key() → str

Get the console key of the node.

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.

Parameters:

mapping – A dictionary mapping MAC addresses to interface information.

next_available_interface() → 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!

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_on_server() → None

DEPRECATED: Use .remove() instead. (Reason: was never meant to be public, removing only on server is not useful)

Remove the node on the server.

remove_tag(tag: str) → None

Remove a tag from this node.

Parameters:

tag – The tag to remove.

run_pyats_command(command: str) → str

Run a pyATS command in exec mode on the node.

Parameters:

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

Returns:

The output from the device.

run_pyats_config_command(command: str) → str

Run a pyATS command in config mode on the node.

Parameters:

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

Returns:

The output from the device.

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_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.

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

Synchronize the operational state of the node.

Parameters:

response – The response from the server.

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: bool = True) → 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 – Whether to push the changes to the server. Defaults to True; should only be False when used by internal methods.

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 config: str | None

Use .configuration instead. (Reason: consistency with API)

Return the initial configuration of this node.

Type:

DEPRECATED

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 label: str

Return the label of the node.

property node_definition: str

Return the definition of this node.

property parameters: dict

Return node parameters.

property pinned_compute_id: str | None

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

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 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, json: bool | None = None) → 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.

  • json – DEPRECATED: Replaced with type check.

Returns:

“Success”.

upload_image_file(filename: 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, json: bool | None = None) → 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.

  • json – DEPRECATED: Replaced with type check.

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 | ResourcePools

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.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, 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.

  • 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_mac_address_block() → int

Get the MAC address block.

Returns:

The MAC address block.

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_web_session_timeout() → int

Get the web session timeout in seconds.

Returns:

The web session timeout.

set_mac_address_block(block: int) → str

Set the MAC address block.

Parameters:

block – The MAC address block.

Returns:

‘OK’

Raises:

InvalidMacAddressBlock – If the MAC address block is not in 0-7 range.

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) → str

Set the web session timeout in seconds.

Parameters:

timeout – The timeout value in seconds.

Returns:

‘OK’

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.

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. Invalidates 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)

Bases: object

__init__(session: httpx.Client) → None
create_user(username: str, pwd: str, fullname: str = '', description: str = '', admin: bool = False, groups: list[str] | None = None, resource_pool: str | None = None) → dict

Create a new user.

Parameters:

  • username – Username.

  • pwd – Desired password.

  • fullname – Full name.

  • description – Description.

  • admin – Whether to create an admin user.

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

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

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.

update_user(user_id: str, fullname: str | None = <Unchanged>, description: str | None = <Unchanged>, groups: list[str] | None = <Unchanged>, admin: bool | None = None, password_dict: dict[str, str] | None = None, resource_pool: str | None = <Unchanged>) → dict

Update an existing user.

Parameters:

  • user_id – User UUID4.

  • fullname – Full name.

  • description – Description.

  • admin – Whether to create an admin user.

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

  • password_dict – Dictionary containing old and new passwords.

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

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

Get the list of available users.

Returns:

List of user IDs.

Submodules

virl2_client.models.annotation

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 link 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: bool = True) → None

Update annotation properties.

Parameters:

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

  • push_to_server – Whether to push the changes to the server. Defaults to True; should only be False when used by internal methods.

property border_color: str

#FF00FF00).

Type:

Border color (example

property border_style: str
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: Annotation

Annotation class representing ellipse annotation.

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

A VIRL2 lab annotation.

Parameters:

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

  • annotation_id – The ID of the annotation.

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

property x2: int

X2 coordinate.

property y2: int

Y2 coordinate.

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

Bases: Annotation

Annotation class representing line annotation.

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

A VIRL2 lab annotation.

Parameters:

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

  • annotation_id – The ID of the annotation.

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

property line_end: str | None

Line arrow end style.

property line_start: str | None

Line arrow start style.

property x2: int

X2 coordinate.

property y2: int

Y2 coordinate.

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

Bases: Annotation

Annotation class representing rectangle annotation.

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

A VIRL2 lab annotation.

Parameters:

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

  • annotation_id – The ID of the annotation.

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

property border_radius: int

Border radius.

property x2: int

X2 coordinate.

property y2: int

Y2 coordinate.

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

Bases: Annotation

Annotation class representing text annotation.

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

A VIRL2 lab annotation.

Parameters:

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

  • annotation_id – The ID of the annotation.

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

property rotation: int

Rotation of an object, in degrees.

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

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_settings() → dict

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

Returns:

A dictionary of the settings of the current authentication method.

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, password: str) → dict

Test a set of credentials 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.

Returns:

Results of the test.

test_current_auth(manager_password: str, username: str, password: str) → dict

Test a set of credentials 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.

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_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 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.

virl2_client.models.authentication

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.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. Invalidates 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 = True) → 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.

Returns:

The created httpx Client object.

virl2_client.models.authentication.response_raise(response: Response) → None

Raise an exception if the response has an HTTP status error. Replace the useless link to httpstatuses.com with error description.

Parameters:

response – The response object to check.

Raises:

httpx.HTTPStatusError – If the response has an HTTP status error.

virl2_client.models.cl_pyats

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.

Raises:
cleanup() → None

Clean up the pyATS connections.

run_command(node_label: str, command: str, init_exec_commands: list[str] | None = None, init_config_commands: list[str] | None = None) → 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.

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) → 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.

Returns:

The output from the device.

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

Sync the testbed from the server. This fetches 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.

property hostname: str | None

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

virl2_client.models.configuration

A collection of utility classes to make getting credentials and configuration easier.

virl2_client.models.configuration.get_configuration(host: str, username: str, password: str, ssl_verify: bool | str) → tuple[str, str, str, str]

Get the login configuration.

The login configuration is retrieved in the following order:

  1. Retrieve from function arguments

  2. Check for .virlrc in the current directory

  3. Recurse up the directory tree for .virlrc

  4. Check environment variables

  5. Check ~/.virlrc

  6. Prompt the user (except for the cert path)

Parameters:

  • host – The host address of the CML server.

  • username – The username.

  • password – The password.

  • ssl_verify – The CA bundle path or boolean value indicating SSL verification.

Returns:

A tuple containing the host, username, password, and SSL verification information.

virl2_client.models.groups

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

Bases: object

Manage groups.

__init__(session: httpx.Client) → None
create_group(name: str, description: str = '', members: list[str] | None = None, labs: list[dict[str, str]] | None = None) → dict

Create a group.

Parameters:

  • name – The name of the group.

  • description – The description of the group.

  • members – The members of the group.

  • labs – 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]

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_group(group_id: str, name: str | None = None, description: str | None = <Unchanged>, members: list[str] | None = <Unchanged>, labs: list[dict[str, str]] | None = <Unchanged>) → dict

Update a group.

Parameters:

  • group_id – The UUID4 of the group.

  • name – The new name of the group.

  • description – The description of the group.

  • members – The members of the group.

  • labs – The labs associated with the group.

Returns:

The updated group object.

virl2_client.models.interface

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

Bases: object

__init__(iid: str, node: Node, label: str, slot: int | None, iface_type: str = 'physical') → 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.

as_dict() → dict[str, str]

Convert the interface to a dictionary representation.

bring_up() → None

Bring up the interface.

degree()

DEPRECATED: Use .connected instead. (Reason: degree always 0 or 1)

Return the degree of 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.

is_connected()

DEPRECATED: Use .connected instead. (Reason: should have been a parameter, renamed to match similar parameters)

Check if the interface is connected to a link.

DEPRECATED: Use .link instead. (Reason: pointless plural, could have been a parameter)

Return the link connected to this interface in a list.

peer_interfaces()

DEPRECATED: Use .peer_interface instead. (Reason: pointless plural, could have been a parameter)

Return the peer interface connected to this interface in a set.

peer_nodes()

DEPRECATED: Use .peer_node instead. (Reason: pointless plural, could have been a parameter)

Return the node of the peer interface in a set.

remove() → None

Remove the interface from the node.

remove_on_server() → None

DEPRECATED: Use .remove() instead. (Reason: was never meant to be public, removing only on server is not useful)

Remove the interface on the server.

shutdown() → None

Shutdown the interface.

property connected: bool

Check if the interface is connected to a link.

property discovered_ipv4: str | None

Return the discovered IPv4 address of the interface.

property discovered_ipv6: str | None

Return the discovered IPv6 address 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, str | None]

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

property is_physical: bool

Use .physical instead. (Reason: renamed to match similar parameters)

Check if the interface is physical.

Type:

DEPRECATED

property label: str

Return the label of the interface.

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

property node: Node

Return the node object to which the interface belongs.

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

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 = 5, hostname: str | None = None, resource_pool_manager: ResourcePoolManagement | 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 = 5, hostname: str | None = None, resource_pool_manager: ResourcePoolManagement | 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.

Raises:

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

add_node_local(*args, **kwargs)

DEPRECATED: Use .create_node() instead. (Reason: only creates a node in the client, which is not useful; if really needed, use ._create_node_local())

Creates a node in the client, but not on the server.

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.

connect_two_nodes(node1: Node, node2: Node) → Link

Connect two nodes within a lab.

Parameters:

  • node1 – The first node object.

  • node2 – The second node object.

Returns:

The created link.

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

Create a lab annotation.

Parameters:

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

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.

Returns:

A Node object.

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.

DEPRECATED: Use Interface.get_link_to() instead. (Reason: redundancy)

Return the link identified by two interface objects.

Parameters:

  • iface1 – The first interface.

  • iface2 – The second interface.

Returns:

The link between the interfaces.

Raises:

LinkNotFound – If no such link exists.

DEPRECATED: Use Node.get_link_to() to get one link or Node.get_links_to() to get all links. (Reason: redundancy)

Return ONE of the links identified by two node objects.

Parameters:

  • node1 – The first node.

  • node2 – The second node.

Returns:

One of links between the nodes.

Raises:

LinkNotFound – If no such link exists.

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.

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.

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, with_node_configurations: bool | None = None, 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.

  • with_node_configurations – DEPRECATED: does the opposite of what is expected. Use exclude_configurations instead.

  • 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_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_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]]

Modify lab/group association.

Parameters:

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

Returns:

Updated objects consisting of group ID and permission.

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

Return the groups this lab is associated with.

property id: str

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

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.licensing

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

Bases: object

__init__(session: httpx.Client, is_cert_deprecated: bool) → 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]]

Get current licensing features.

get_certificate() → str | None

DEPRECATED: There is no replacement as the certificate support was dropped. (Reason: the certificate support was dropped in CML 2.7.0)

Get the currently installed licensing public certificate.

get_reservation_confirmation_code() → str

Get the reservation confirmation code.

get_reservation_return_code() → str

Get the reservation return code.

install_certificate(cert: str) → bool

DEPRECATED: There is no replacement as the certificate support was dropped. (Reason: the certificate support was dropped in CML 2.7.0)

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

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.

remove_certificate() → bool

DEPRECATED: There is no replacement as the certificate support was dropped. (Reason: the certificate support was dropped in CML 2.7.0)

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

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, 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

class virl2_client.models.node.Node(lab: Lab, nid: str, label: str, node_definition: str, image_definition: str | None, configuration: list[dict[str, str]] | str | None, x: int, y: int, ram: int | None, cpus: int | None, cpu_limit: int | None, data_volume: int | None, boot_disk_size: int | None, hide_links: bool, tags: list[str], resource_pool: str | None, parameters: dict, pinned_compute_id: str | None)

Bases: object

__init__(lab: Lab, nid: str, label: str, node_definition: str, image_definition: str | None, configuration: list[dict[str, str]] | str | None, x: int, y: int, ram: int | None, cpus: int | None, cpu_limit: int | None, data_volume: int | None, boot_disk_size: int | None, hide_links: bool, tags: list[str], resource_pool: str | None, parameters: dict, pinned_compute_id: str | None) → 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.

  • 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.

add_tag(tag: str) → None

Add a tag to this node.

Parameters:

tag – The tag to add.

console_key() → str

Get the console key of the node.

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.

Parameters:

mapping – A dictionary mapping MAC addresses to interface information.

next_available_interface() → 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!

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_on_server() → None

DEPRECATED: Use .remove() instead. (Reason: was never meant to be public, removing only on server is not useful)

Remove the node on the server.

remove_tag(tag: str) → None

Remove a tag from this node.

Parameters:

tag – The tag to remove.

run_pyats_command(command: str) → str

Run a pyATS command in exec mode on the node.

Parameters:

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

Returns:

The output from the device.

run_pyats_config_command(command: str) → str

Run a pyATS command in config mode on the node.

Parameters:

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

Returns:

The output from the device.

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_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.

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

Synchronize the operational state of the node.

Parameters:

response – The response from the server.

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: bool = True) → 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 – Whether to push the changes to the server. Defaults to True; should only be False when used by internal methods.

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 config: str | None

Use .configuration instead. (Reason: consistency with API)

Return the initial configuration of this node.

Type:

DEPRECATED

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 label: str

Return the label of the node.

property node_definition: str

Return the definition of this node.

property parameters: dict

Return node parameters.

property pinned_compute_id: str | None

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

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 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_definitions

class virl2_client.models.node_image_definitions.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, json: bool | None = None) → 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.

  • json – DEPRECATED: Replaced with type check.

Returns:

“Success”.

upload_image_file(filename: 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, json: bool | None = None) → 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.

  • json – DEPRECATED: Replaced with type check.

Returns:

“Success”.

virl2_client.models.node_image_definitions.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.resource_pools

class virl2_client.models.resource_pools.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: bool = True)

Update multiple properties of the pool at once.

Parameters:

  • pool_data – A dictionary of the properties to update.

  • push_to_server – Whether to push the changes to the server. Defaults to True; should only be False when used by internal methods.

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_pools.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 | ResourcePools

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_pools.ResourcePoolUsage(limit: 'ResourcePoolUsageBase', usage: 'ResourcePoolUsageBase')

Bases: object

__init__(limit: ResourcePoolUsageBase, usage: ResourcePoolUsageBase) → None
limit: ResourcePoolUsageBase
usage: ResourcePoolUsageBase
class virl2_client.models.resource_pools.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.system

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, 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, 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.

  • nodes – The list of nodes associated with the compute host.

remove() → None

Remove the compute host.

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

Update the compute host with the given data.

Parameters:

  • host_data – The data to update the compute host.

  • push_to_server – Whether to push the changes to the server. Defaults to True; should only be False when used by internal methods.

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 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, 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.

  • 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_mac_address_block() → int

Get the MAC address block.

Returns:

The MAC address block.

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_web_session_timeout() → int

Get the web session timeout in seconds.

Returns:

The web session timeout.

set_mac_address_block(block: int) → str

Set the MAC address block.

Parameters:

block – The MAC address block.

Returns:

‘OK’

Raises:

InvalidMacAddressBlock – If the MAC address block is not in 0-7 range.

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) → str

Set the web session timeout in seconds.

Parameters:

timeout – The timeout value in seconds.

Returns:

‘OK’

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.

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: bool = True) → None

Update the system notice with the given data.

Parameters:

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

  • push_to_server – Whether to push the changes to the server. Defaults to True; should only be False when used by internal methods.

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.users

class virl2_client.models.users.UserManagement(session: httpx.Client)

Bases: object

__init__(session: httpx.Client) → None
create_user(username: str, pwd: str, fullname: str = '', description: str = '', admin: bool = False, groups: list[str] | None = None, resource_pool: str | None = None) → dict

Create a new user.

Parameters:

  • username – Username.

  • pwd – Desired password.

  • fullname – Full name.

  • description – Description.

  • admin – Whether to create an admin user.

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

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

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.

update_user(user_id: str, fullname: str | None = <Unchanged>, description: str | None = <Unchanged>, groups: list[str] | None = <Unchanged>, admin: bool | None = None, password_dict: dict[str, str] | None = None, resource_pool: str | None = <Unchanged>) → dict

Update an existing user.

Parameters:

  • user_id – User UUID4.

  • fullname – Full name.

  • description – Description.

  • admin – Whether to create an admin user.

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

  • password_dict – Dictionary containing old and new passwords.

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

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

Get the list of available users.

Returns:

List of user IDs.