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

Bases: exceptions.EnvironmentError

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

class VMDescription(input_file, output_file=None)

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)

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)

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)

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)

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)

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)

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)

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)

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:

DiskRepresentation – disk_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)

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)

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)

Delete the configuration profile with the given ID.

Parameters:profile (str) – Profile identifier

destroy()

Clean up after ourselves.

Deletes self.working_dir and its contents.

classmethod detect_type_from_name(filename)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Get the value of the given property.

Parameters:key (str) – Property identifier Returns:str – Value of this property, or None

get_serial_connectivity(profile)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

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

Returns:bool – True if hardware is sane, False if not.

write()

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.