COT.vm_description module

Abstract superclass for reading, editing, and writing VMs.

VMInitError Class representing errors encountered when trying to init/load a VM.
VMDescription Abstract class for reading, editing, and writing VM definitions.
exception VMInitError[source]

Bases: exceptions.EnvironmentError

Class representing errors encountered when trying to init/load a VM.

class VMDescription(input_file, output_file=None)[source]

Bases: object

Abstract class for reading, editing, and writing VM definitions.

Properties

input_file Data file to read in.
output_file Filename that write() will output to.
platform The Platform class object associated with this VM.
config_profiles The list of supported configuration profiles.
default_config_profile The name of the default configuration profile.
environment_properties The array of environment properties.
environment_transports The list of environment transport methods.
networks The list of network names currently defined in this VM.
network_descriptions The list of network descriptions currently defined in this VM.
system_types List of virtual system type(s) supported by this virtual machine.
version_short A short string describing the product version.
version_long A long string describing the product version.
__init__(input_file, output_file=None)[source]

Read the given VM description file into memory.

Also creates a temporary directory as a working directory.

Parameters:
  • input_file (str) – Data file to read in.
  • output_file (str) –

    File name to write to.

    • If this VM is read-only, (there will never be an output file) this value should be None
    • If the output filename is not yet known, use "" and subsequently set output when it is determined.
add_controller_device(device_type, subtype, address, ctrl_item=None)[source]

Create a new IDE or SCSI controller, or update existing one.

Parameters:
  • device_type (str) – 'ide' or 'scsi'
  • subtype (str) – Subtype such as 'virtio' (optional)
  • address (int) – Controller address such as 0 or 1 (optional)
  • ctrl_item (object) – Existing controller device to update (optional)
Returns:

object – New or updated controller device object

add_disk(disk_repr, file_id, drive_type, disk=None)[source]

Add a new disk object to the VM or overwrite the provided one.

Parameters:
  • disk_repr (DiskRepresentation) – Disk file representation
  • file_id (str) – Identifier string for the file/disk mapping
  • drive_type (str) – ‘harddisk’ or ‘cdrom’
  • disk (object) – Existing disk object to overwrite
Returns:

object – New or updated disk object

add_disk_device(drive_type, address, name, description, disk, file_obj, ctrl_item, disk_item=None)[source]

Add a new disk device to the VM or update the provided one.

Parameters:
  • drive_type (str) – 'harddisk' or 'cdrom'
  • address (str) – Address on controller, such as “1:0” (optional)
  • name (str) – Device name string (optional)
  • description (str) – Description string (optional)
  • disk (object) – Disk object to map to this device
  • file_obj (object) – File object to map to this device
  • ctrl_item (object) – Controller object to serve as parent
  • disk_item (object) – Existing disk device to update instead of making a new device.
Returns:

object – New or updated disk device object.

add_file(file_path, file_id, file_obj=None, disk=None)[source]

Add a new file object to the VM or overwrite the provided one.

Parameters:
  • file_path (str) – Path to file to add
  • file_id (str) – Identifier string for the file in the VM
  • file_obj (object) – Existing file object to overwrite
  • disk (object) – Existing disk object referencing file.
Returns:

object – New or updated file object

check_sanity_of_disk_device(disk, file_obj, disk_item, ctrl_item)[source]

Check if the given disk is linked properly to the other objects.

Parameters:
  • disk (object) – Disk object to validate
  • file_obj (object) – File object which this disk should be linked to (optional)
  • disk_item (object) – Disk device object which should link to this disk (optional)
  • ctrl_item (object) – Controller device object which should link to the disk_item
Raises:

ValueMismatchError – if the given items are not linked properly.

config_file_to_properties(file_path, user_configurable=None)[source]

Import each line of a text file into a configuration property.

Parameters:
  • file_path (str) – File name to import.
  • user_configurable (bool) – Should the properties be configurable at deployment time by the user?
convert_disk_if_needed(disk_image, kind)[source]

Convert the disk to a more appropriate format if needed.

Parameters:
  • disk_image (DiskRepresentation) – Disk to inspect and possibly convert
  • kind (str) – Image type (harddisk/cdrom).
Returns:

DiskRepresentationdisk_image, if no conversion was required, or a new DiskRepresentation instance representing a converted image that has been created in output_dir.

create_configuration_profile(pid, label, description)[source]

Create/update a configuration profile with the given ID.

Parameters:
  • pid (str) – Profile identifier
  • label (str) – Brief descriptive label for the profile
  • description (str) – Verbose description of the profile
create_network(label, description)[source]

Define a new network with the given label and description.

Also serves to update the description of an existing network label.

Parameters:
  • label (str) – Brief label for the network
  • description (str) – Verbose description of the network
delete_configuration_profile(profile)[source]

Delete the configuration profile with the given ID.

Parameters:profile (str) – Profile identifier
destroy()[source]

Clean up after ourselves.

Deletes self.working_dir and its contents.

classmethod detect_type_from_name(filename)[source]

Check the given filename to see if it looks like a type we support.

Does not check file contents, as the given filename may not yet exist.

Parameters:filename (str) – File name or path
Returns:str – A string representing a recognized and supported type of file
Raises:ValueUnsupportedError – if COT can’t recognize the file type or doesn’t know how to handle this file type.
find_device_location(device)[source]

Find the controller type and address of a given device object.

Parameters:device (object) – Hardware device object.
Returns:tuple(type, address), such as ("ide", "1:0").
find_empty_drive(drive_type)[source]

Find a disk device that exists but contains no data.

Parameters:drive_type (str) – Disk drive type, such as ‘cdrom’ or ‘harddisk’
Returns:object – Hardware device object, or None.
find_open_controller(controller_type)[source]

Find the first open slot on a controller of the given type.

Parameters:controller_type (str) – 'ide' or 'scsi'
Returns:tuple(controller_device, address_string) or (None, None)
get_common_subtype(device_type)[source]

Get the sub-type common to all devices of the given type.

Parameters:device_type (str) – Device type such as 'ide' or 'memory'.
Returns:str – Subtype string common to all devices of this type, or None, if multiple such devices exist and they do not all have the same sub-type.
get_file_ref_from_disk(disk)[source]

Get the file reference from the given opaque disk object.

Parameters:disk (object) – Disk object to query
Returns:str – String that can be used to identify the file associated with this disk
get_id_from_disk(disk)[source]

Get the identifier string associated with the given Disk object.

Parameters:disk (object) – Disk object
Returns:str – Identifier string associated with this object
get_id_from_file(file_obj)[source]

Get the file ID from the given opaque file object.

Parameters:file_obj (object) – File object to query
Returns:str – Identifier string associated with this object
get_nic_count(profile_list)[source]

Get the number of NICs under the given profile(s).

Parameters:profile_list (list) – Profile(s) of interest.
Returns:dict{ profile_name : nic_count }
get_path_from_file(file_obj)[source]

Get the file path from the given opaque file object.

Parameters:file_obj (object) – File object to query
Returns:str – Relative path to the file associated with this object
get_property_value(key)[source]

Get the value of the given property.

Parameters:key (str) – Property identifier
Returns:str – Value of this property, or None
get_serial_connectivity(profile)[source]

Get the serial port connectivity strings under the given profile.

Parameters:profile (str) – Profile of interest.
Returns:list – List of connectivity strings
get_serial_count(profile_list)[source]

Get the number of serial ports under the given profile(s).

Parameters:profile_list (list) – Change only the given profiles
Returns:dict{ profile_name : serial_count }
info_string(width=79, verbosity_option=None)[source]

Get a descriptive string summarizing the contents of this VM.

Parameters:
  • width (int) – Line length to wrap to where possible.
  • verbosity_option (str) – ‘brief’, None (default), or ‘verbose’
Returns:

str – Wrapped, appropriately verbose string.

profile_info_string(width=79, verbosity_option=None)[source]

Get a string summarizing available configuration profiles.

Parameters:
  • width (int) – Line length to wrap to if possible
  • verbosity_option (str) – ‘brief’, None (default), or ‘verbose’
Returns:

str – Appropriately formatted and verbose string.

remove_file(file_obj, disk=None, disk_drive=None)[source]

Remove the given file object from the VM.

Parameters:
  • file_obj (object) – File object to remove
  • disk (object) – Disk object referencing file
  • disk_drive (object) – Disk drive mapping file to a device
search_from_controller(controller, address)[source]

From the controller type and device address, look for existing disk.

Parameters:
  • controller (str) – 'ide' or 'scsi'
  • address (str) – Device address such as '1:0'
Returns:

tuple(file, disk, controller_device, disk_device), opaque objects of which any or all may be None

search_from_file_id(file_id)[source]

From the given file ID, try to find any existing objects.

Parameters:file_id (str) – File ID to search from
Returns:tuple(file, disk, controller_device, disk_device), opaque objects of which any or all may be None
search_from_filename(filename)[source]

From the given filename, try to find any existing objects.

Parameters:filename (str) – Filename to search from
Returns:tuple(file, disk, controller_device, disk_device), opaque objects of which any or all may be None
set_cpu_count(cpus, profile_list)[source]

Set the number of CPUs.

Parameters:
  • cpus (int) – Number of CPUs
  • profile_list (list) – Change only the given profiles
set_ide_subtype(subtype, profile_list)[source]

Set the device subtype for the IDE controller(s).

Deprecated since version 1.5: Use set_ide_subtypes() instead.

Parameters:
  • subtype (str) – IDE subtype string
  • profile_list (list) – Change only the given profiles
set_ide_subtypes(type_list, profile_list)[source]

Set the device subtype list for the IDE controller(s).

Parameters:
  • type_list (list) – IDE subtype string list
  • profile_list (list) – Change only the given profiles
set_memory(megabytes, profile_list)[source]

Set the amount of RAM, in megabytes.

Parameters:
  • megabytes (int) – Memory value, in megabytes
  • profile_list (list) – Change only the given profiles
set_nic_count(count, profile_list)[source]

Set the given profile(s) to have the given number of NICs.

Parameters:
  • count (int) – number of NICs
  • profile_list (list) – Change only the given profiles
set_nic_mac_addresses(mac_list, profile_list)[source]

Set the MAC addresses for NICs under the given profile(s).

Note

If the length of mac_list is less than the number of NICs, will use the last entry in the list for all remaining NICs.

Parameters:
  • mac_list (list) – List of MAC addresses to assign to NICs
  • profile_list (list) – Change only the given profiles
set_nic_names(name_list, profile_list)[source]

Set the device names for NICs under the given profile(s).

Parameters:
  • name_list (list) – List of names to assign.
  • profile_list (list) – Change only the given profiles
set_nic_networks(network_list, profile_list)[source]

Set the NIC to network mapping for NICs under the given profile(s).

Note

If the length of network_list is less than the number of NICs, will use the last entry in the list for all remaining NICs.

Parameters:
  • network_list (list) – List of networks to map NICs to
  • profile_list (list) – Change only the given profiles
set_nic_type(nic_type, profile_list)[source]

Set the hardware type for NICs.

Deprecated since version 1.5: Use set_nic_types() instead.

Parameters:
  • nic_type (str) – NIC hardware type
  • profile_list (list) – Change only the given profiles.
set_nic_types(type_list, profile_list)[source]

Set the hardware type(s) for NICs.

Parameters:
  • type_list (list) – NIC hardware type(s)
  • profile_list (list) – Change only the given profiles.
set_property_value(key, value, user_configurable=None, property_type=None, label=None, description=None)[source]

Set the value of the given property (converting value if needed).

Parameters:
  • key (str) – Property identifier
  • value (object) – Value to set for this property
  • user_configurable (bool) – Should this property be configurable at deployment time by the user?
  • property_type (str) – Value type - ‘string’ or ‘boolean’
  • label (str) – Brief explanatory label for this property
  • description (str) – Detailed description of this property
Returns:

str – the (converted) value that was set.

set_scsi_subtype(subtype, profile_list)[source]

Set the device subtype for the SCSI controller(s).

Deprecated since version 1.5: Use set_scsi_subtypes() instead.

Parameters:
  • subtype (str) – SCSI subtype string
  • profile_list (list) – Change only the given profiles
set_scsi_subtypes(type_list, profile_list)[source]

Set the device subtype list for the SCSI controller(s).

Parameters:
  • type_list (list) – SCSI subtype string list
  • profile_list (list) – Change only the given profiles
set_serial_connectivity(conn_list, profile_list)[source]

Set the serial port connectivity under the given profile(s).

Parameters:
  • conn_list (list) – List of connectivity strings
  • profile_list (list) – Change only the given profiles
set_serial_count(count, profile_list)[source]

Set the given profile(s) to have the given number of NICs.

Parameters:
  • count (int) – Number of serial ports
  • profile_list (list) – Change only the given profiles
validate_hardware()[source]

Check sanity of hardware properties for this VM/product/platform.

Returns:boolTrue if hardware is sane, False if not.
write()[source]

Write the VM description to output_file, if any.

config_profiles

The list of supported configuration profiles.

If there are no profiles defined, returns an empty list. If there is a default profile, it will be first in the list.

default_config_profile

The name of the default configuration profile.

Returns:str – Profile name or None if none are defined.
environment_properties

The array of environment properties.

Returns:list – Array of dicts (one per property) with the keys "key", "value", "qualifiers", "type", "label", and "description".
environment_transports

The list of environment transport methods.

input_file

Data file to read in.

network_descriptions

The list of network descriptions currently defined in this VM.

networks

The list of network names currently defined in this VM.

output_file

Filename that write() will output to.

platform

The Platform class object associated with this VM.

GenericPlatform or a more specific subclass if recognized as such.

product_class

The product class identifier, such as com.cisco.csr1000v.

system_types

List of virtual system type(s) supported by this virtual machine.

verbosity_options = {'verbose': 2, 'brief': 0, None: 1}
version_long

A long string describing the product version.

version_short

A short string describing the product version.