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
- 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".
- platform[source]¶
The Platform class object associated with this VM.
GenericPlatform or a more specific subclass if recognized as such.
- verbosity_options = {None: 1, 'brief': 0, 'verbose': 2}¶