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. 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
- type (str) –
-
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.
- type (str) –
-
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
-
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_disk
(disk)[source]¶ Get the identifier string associated with the given Disk object.
Parameters: disk – Disk object Return type: string
-
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_connectivity
(profile)[source]¶ Get the serial port connectivity strings under the given profile.
Parameters: profile (str) – Profile of interest. Returns: List of connectivity strings
-
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.
-
remove_file
(file, disk=None, disk_drive=None)[source]¶ Remove the given file object from the VM.
Parameters: - file – File object to remove
- disk – Disk object referencing
file
- disk_drive – 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: (file, disk, controller_device, disk_device)
, opaque objects of which any or all may beNone
- controller (str) –
-
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 beNone
-
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 beNone
-
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).
Deprecated since version 1.5: Use
set_ide_subtypes()
instead.Parameters: - type (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) – 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).
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.
Deprecated since version 1.5: Use
set_nic_types()
instead.Parameters: - 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)[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).
Deprecated since version 1.5: Use
set_scsi_subtypes()
instead.Parameters: - type (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
-
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: Profile name or None
if none are defined.
-
environment_properties
¶ The array of environment properties.
Returns: Array of dicts (one per property) with the keys "key"
,"value"
,"qualifiers"
,"type"
,"label"
, and"description"
.
-
environment_transports
¶ The list of environment transport methods.
Return type: list[str]
-
input_file
¶ Data file to read in.
-
networks
¶ The list of network names currently defined in this VM.
Return type: list[str]
-
platform
¶ The Platform class object associated with this VM.
GenericPlatform
or a more specific subclass if recognized as such.
-
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.
-