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.
networks The list of network names 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.
add_controller_device(type, subtype, address, ctrl_item=None)[source]

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

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

New or updated controller device object

add_disk(file_path, file_id, disk_type, disk=None)[source]

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

Parameters:
  • file_path (str) – Path to disk image file
  • file_id (str) – Identifier string for the file/disk mapping
  • disk_type (str) – ‘harddisk’ or ‘cdrom’
  • disk – Existing disk object to overwrite
Returns:

New or updated disk object

add_disk_device(type, address, name, description, disk, file, ctrl_item, disk_item=None)[source]

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

Parameters:
  • 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 – Disk object to map to this device
  • file – File object to map to this device
  • ctrl_item – Controller object to serve as parent
  • disk_item – Existing disk device to update instead of making a new device.
Returns:

New or updated disk device object.

add_file(file_path, file_id, file=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 – Existing file object to overwrite
  • disk – Existing disk object referencing file.
Returns:

New or updated file object

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

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

Parameters:
  • disk – Disk object to validate
  • file – File object which this disk should be linked to (optional)
  • disk_item – Disk device object which should link to this disk (optional)
  • ctrl_item – 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)[source]

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

Parameters:file (str) – File name to import.
convert_disk_if_needed(file_path, kind)[source]

Convert the disk to a more appropriate format if needed.

Parameters:
  • file_path (str) – Image to inspect and possibly convert
  • kind (str) – Image type (harddisk/cdrom)
Returns:

  • file_path, if no conversion was required
  • or a file path in output_dir containing the converted image

create_configuration_profile(id, label, description)[source]

Create/update a configuration profile with the given ID.

Parameters:
  • id – 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.

Parameters:
  • label (str) – Brief label for the network
  • description (str) – Verbose description of the network
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.

Returns:A string representing a recognized and supported type of file
Raises ValueUnsupportedError:
 if we don’t know how to handle this file.
find_device_location(device)[source]

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

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

Find a disk device that exists but contains no data.

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

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

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

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

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

Get the file reference from the given opaque disk object.

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

Get the file ID from the given opaque file object.

Parameters:file – File object to query
Returns: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.
Return type:dict
Returns:{ profile_name : nic_count }
get_path_from_file(file)[source]

Get the file path from the given opaque file object.

Parameters:file – File object to query
Returns: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:Value of this property, or None
get_serial_count(profile_list)[source]

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

Return type:dict
Returns:{ profile_name : serial_count }
get_subtype_from_device(device)[source]

Get the sub-type of the given opaque device object.

Parameters:device – Device object to query
Returns:None, or string such as ‘virtio’ or ‘lsilogic’
get_type_from_device(device)[source]

Get the type of the given opaque device object.

Parameters:device – Device object to query
Returns:string such as ‘ide’ or ‘memory’
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:

Wrapped, appropriately verbose string.

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

Get a string summarizing available configuration profiles.

Parameters:
  • TEXT_WIDTH (int) – Line length to wrap to if possible
  • verbosity_option (str) – 'brief', None (default), or 'verbose'
  • enumerate (boolean) – If True, number the profiles.
Returns:

Appropriately formatted and verbose string.

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:

(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:filename (str) – Filename to search from
Returns:(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:(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(type, profile_list)[source]

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

Parameters:
  • type (str) – IDE subtype string
  • 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).

Since NICs are often named sequentially, this API supports a wildcard option for the final element in name_list which can be expanded to automatically assign sequential NIC names. The syntax for the wildcard option is { followed by a number (indicating the starting index for the name) followed by }. Examples:

["eth{0}"]
Expands to ["eth0", "eth1", "eth2", ...]
["mgmt0" "eth{10}"]
Expands to ["mgmt0", "eth10", "eth11", "eth12", ...]
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(type, profile_list)[source]

Set the hardware type for NICs.

Parameters:
  • type (str) – NIC hardware type
  • profile_list (list) – Change only the given profiles.
set_property_value(key, value)[source]

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

Parameters:
  • key (str) – Property identifier
  • value – Value to set for this property
Returns:

the (converted) value that was set.

set_scsi_subtype(type, profile_list)[source]

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

Parameters:
  • type (str) – SCSI subtype string
  • 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
write()[source]

Write the VM description to output_file, if any.

config_profiles[source]

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

The name of the default configuration profile.

Returns:Profile name or None if none are defined.
environment_properties[source]

The array of environment properties.

Returns:Array of dicts (one per property) with the keys "key", "value", "qualifiers", "type", "label", and "description".
input_file[source]

Data file to read in.

networks[source]

The list of network names currently defined in this VM.

Return type:list[str]
output_file[source]

Filename that write() will output to.

platform[source]

The Platform class object associated with this VM.

GenericPlatform or a more specific subclass if recognized as such.

system_types[source]

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

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

A long string describing the product version.

version_short[source]

A short string describing the product version.