`COT.ovf.ovf` module¶

Module for handling OVF and OVA virtual machine description files.

Functions

`byte_count`	Convert an OVF-style value + multiplier into decimal byte count.
`byte_string`	Pretty-print the given bytes value.
`factor_bytes`	Convert a byte count into OVF-style bytes + multiplier.

Classes

OVF Representation of the contents of an OVF or OVA.

class OVF(input_file, output_file)[source]¶

Bases: COT.vm_description.VMDescription, COT.xml_file.XML

Representation of the contents of an OVF or OVA.

Properties

`input_file`	Data file to read in.
`output_file`	OVF or OVA file that will be created or updated by `write()`.
`ovf_version`	Float representing the OVF specification version in use.
`product_class`	The product class identifier, such as com.cisco.csr1000v.
`platform`	The platform type, as determined from the OVF descriptor.
`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 method strings.
`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`	Short descriptive version string (XML `Version` element).
`version_long`	Long descriptive version string (XML `FullVersion` element).

__init__(input_file, output_file)[source]¶

Open the specified OVF and read its XML into memory.

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_file` when it is determined.
Raises:	`VMInitError` if the OVF descriptor cannot be located if an XML parsing error occurs if the XML is not actually an OVF descriptor if the OVF hardware validation fails `Exception` – will call `destroy()` to clean up before reraising any exception encountered.

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 (object) – (Optional) subtype string such as `'virtio'` or list of subtype strings address (int) – Controller address such as 0 or 1 (optional) ctrl_item (OVFItem) – Existing controller device to update (optional)
Returns:	OVFItem – New or updated controller device object
Raises:	`ValueTooHighError` – if no more controllers can be created

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 (COT.disks.DiskRepresentation) – Disk file representation file_id (str) – Identifier string for the file/disk mapping drive_type (str) – ‘harddisk’ or ‘cdrom’ disk (xml.etree.ElementTree.Element) – Existing object to overwrite
Returns:	xml.etree.ElementTree.Element – New or updated disk object

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

Create a new disk hardware device or overwrite an existing 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 (xml.etree.ElementTree.Element) – Disk object to map to this device
file_obj (xml.etree.ElementTree.Element) – File object to map to this device
ctrl_item (OVFItem) – Controller object to serve as parent
disk_item (OVFItem) – Existing disk device to update instead of making a new device.

Returns:

xml.etree.ElementTree.Element – 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 (xml.etree.ElementTree.Element) – Existing file object to overwrite disk (xml.etree.ElementTree.Element) – Existing disk object referencing `file`.
Returns:	xml.etree.ElementTree.Element – 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 (xml.etree.ElementTree.Element) – Disk object to validate file_obj (xml.etree.ElementTree.Element) – File object which this disk should be linked to (optional) disk_item (OVFItem) – Disk device object which should link to this disk (optional) ctrl_item (OVFItem) – Controller device object which should link to the `disk_item`
Raises:	`ValueMismatchError` – if the given items are not linked properly. `ValueUnsupportedError` – if the `disk_item` has a `HostResource` value in an unrecognized or invalid format.

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 resulting properties be configurable at deployment time by the user?
Raises:	`NotImplementedError` – if the `platform` for this OVF does not define `LITERAL_CLI_STRING`

convert_disk_if_needed(disk_image, kind)[source]¶

Convert the disk to a more appropriate format if needed.

All hard disk files are converted to stream-optimized VMDK as it is the only format that VMware supports in OVA packages.
CD-ROM iso images are accepted without change.

Parameters:	disk_image (COT.disks.DiskRepresentation) – Image 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)[source]¶

Create or 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 profile with the given ID.

Parameters:	profile (str) – Profile ID to delete.
Raises:	`LookupError` – if the profile does not exist.

static detect_type_from_name(filename)[source]¶

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

For our purposes, the file needs to match ”.ov[af]” to appear to be an OVF/OVA file. We also support names like “foo.ovf.20150101” as those have been seen in the wild.

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

Parameters:	filename (str) – File name/path
Returns:	str – ‘.ovf’, ‘.box’ or ‘.ova’
Raises:	`ValueUnsupportedError` – if filename doesn’t match ovf/ova

device_info_str(device_item)[source]¶

Get a one-line summary of a hardware device.

Parameters:	device_item (OVFItem) – Device to summarize
Returns:	str – Descriptive string such as “harddisk @ IDE 1:0”

find_device_location(device)[source]¶

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

Parameters:	device (OVFItem) – Hardware device object.
Returns:	tuple – `(type, address)`, such as `("ide", "1:0")`.
Raises:	`LookupError` – if the controller is not found.

find_disk_from_file_id(file_id)[source]¶

Find the Disk that uses the given file_id for backing.

Parameters:	file_id (str) – File identifier string
Returns:	xml.etree.ElementTree.Element – Disk matching the file, or None

find_empty_drive(drive_type)[source]¶

Find a disk device that exists but contains no data.

Parameters:	drive_type (str) – Either ‘cdrom’ or ‘harddisk’
Returns:	OVFItem – Instance representing this disk device, or None.
Raises:	`ValueUnsupportedError` – if `drive_type` is unrecognized.

find_item_from_disk(disk)[source]¶

Find the disk Item that references the given Disk.

Parameters:	disk (xml.etree.ElementTree.Element) – Disk element
Returns:	OVFItem – Corresponding instance, or None

find_item_from_file(file_obj)[source]¶

Find the disk Item that references the given File.

Parameters:	file_obj (xml.etree.ElementTree.Element) – File element
Returns:	OVFItem – Corresponding instance, 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 – `(ctrl_item, address_string)` or `(None, None)`

find_parent_from_item(item)[source]¶

Find the parent Item of the given Item.

Parameters:	item (OVFItem) – Item whose parent is desired
Returns:	OVFItem – instance representing the parent device, or None

generate_manifest(ovf_file)[source]¶

Construct the manifest file for this package, if possible.

Parameters:	ovf_file (str) – OVF descriptor file path
Returns:	bool – True if the manifest was successfully generated, False if not successful (such as if checksum helper tools are unavailable).

get_capacity_from_disk(disk)[source]¶

Get the capacity of the given Disk in bytes.

Parameters:	disk (xml.etree.ElementTree.Element) – Disk element to inspect
Returns:	int – Disk capacity, in bytes

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 the 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 (xml.etree.ElementTree.Element) – ‘Disk’ element
Returns:	str – ‘fileRef’ attribute value of this element

get_id_from_disk(disk)[source]¶

Get the identifier string associated with the given Disk object.

Parameters:	disk (xml.etree.ElementTree.Element) – Disk object to inspect
Returns:	str – Disk identifier

get_id_from_file(file_obj)[source]¶

Get the file ID from the given opaque file object.

Parameters:	file_obj (xml.etree.ElementTree.Element) – ‘File’ element
Returns:	str – ‘id’ attribute value of this element

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 (xml.etree.ElementTree.Element) – ‘File’ element
Returns:	str – ‘href’ attribute value of this element

get_property_value(key)[source]¶

Get the value of the given property.

Parameters:	key (str) – Property identifier
Returns:	str – Value of this property as a string, 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 – connectivity strings

get_serial_count(profile_list)[source]¶

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

Parameters:	profile_list (list) – Profile(s) of interest.
Returns:	dict – `{ profile_name : serial_count }`

info_string(width=79, verbosity_option=None)[source]¶

Get a descriptive string summarizing the contents of this OVF.

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_list(width=79, verbose=False)[source]¶

Get a list describing available configuration profiles.

Parameters:	width (int) – Line length to wrap to if possible verbose (bool) – if True, generate multiple lines per profile
Returns:	tuple – (header, list)

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 (xml.etree.ElementTree.Element) – File object to remove disk (xml.etree.ElementTree.Element) – Disk object referencing `file` disk_drive (OVFItem) – Disk drive mapping `file` to a device
Raises:	`ValueUnsupportedError` – If the `disk_drive` is a device type other than ‘cdrom’ or ‘harddisk’

search_from_controller(controller, address)[source]¶

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

This implementation uses the parameters to find matching controller and disk Item elements, then using the disk Item to find matching File and/or Disk.

Parameters:	controller (str) – `'ide'` or `'scsi'` address (str) – Device address such as `'1:0'`
Returns:	tuple – `(file, disk, ctrl_item, disk_item)`, any or all of which may be `None`

search_from_file_id(file_id)[source]¶

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

This implementation uses the given file_id to find a matching File in the OVF, then using that to find a matching Disk and Item entries.

Parameters:

file_id (str) – File ID to search from

Returns:

tuple – (file, disk, ctrl_item, disk_item), any or all of which

may be None

Raises:

LookupError – If the disk entry is found but no corresponding file is found.
LookupError – If the disk_item is found but no ctrl_item is found to be its parent.

search_from_filename(filename)[source]¶

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

This implementation uses the given filename to find a matching File in the OVF, then using that to find a matching Disk and Item entries.

Parameters:	filename (str) – Filename to search from
Returns:	tuple – `(file, disk, ctrl_item, disk_item)`, any or all of which may be `None`
Raises:	`LookupError` – If the `disk_item` is found but no `ctrl_item` is found to be its parent.

set_capacity_of_disk(disk, capacity_bytes)[source]¶

Set the storage capacity of the given Disk.

Tries to use the most human-readable form possible (i.e., 8 GiB instead of 8589934592 bytes).

Parameters:	disk (xml.etree.ElementTree.Element) – Disk to update capacity_bytes (int) – Disk capacity, in bytes

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_subtypes(type_list, profile_list)[source]¶

Set the device subtype(s) 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_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.
Raises:	`NotImplementedError` – if `ovf_version` is less than 1.0; OVF version 0.9 is not currently supported.

set_scsi_subtypes(type_list, profile_list)[source]¶

Set the device subtype(s) 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 serial ports.

Parameters:	count (int) – Number of serial ports profile_list (list) – Change only the given profiles

tar(ovf_descriptor, tar_file)[source]¶

Create a .ova tar file based on the given OVF descriptor.

Parameters:	ovf_descriptor (str) – File path for an OVF descriptor tar_file (str) – File path for the desired OVA archive.

untar(file_path)[source]¶

Untar the OVF descriptor from an .ova to the working directory.

Parameters:	file_path (str) – OVA file path
Returns:	str – Path to extracted OVF descriptor
Raises:	`VMInitError` – if the given file doesn’t represent a valid OVA archive.

validate_and_update_file_references()[source]¶

Check all File entries to make sure they are valid and up to date.

Helper method for write().

validate_and_update_networks()[source]¶

Make sure all defined networks are actually used by NICs.

Delete any networks that are unused and warn the user. Helper method for write().

validate_hardware()[source]¶

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

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

write()[source]¶: Write OVF or OVA to output_file, if set.

INFO_STRING_DISK_COLUMNS_WIDTH = 41¶

INFO_STRING_DISK_TEMPLATE = '{{0:{0}}} {{1:>9}} {{2:>9}} {{3:.20}}'¶

INFO_STRING_FILE_TEMPLATE = '{{0:{0}}} {{1:>9}}'¶

PROFILE_INFO_TEMPLATE = '{{0:{0}}} {{1:>4}} {{2:>9}} {{3:>4}} {{4:>7}} {{5:>14}}'¶

application_url¶: Application URL string (XML AppUrl element).

config_profiles¶

The list of supported configuration profiles.

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

environment_properties¶

The array of environment properties.

Array of dicts (one per property) with the keys "key", "value", "qualifiers", "type", "user_configurable", "label", and "description".

environment_transports¶: The list of environment transport method strings.

network_descriptions¶

The list of network descriptions currently defined in this VM.

Returns:	list – List of network description strings

networks¶: The list of network names currently defined in this VM.

output_file¶

OVF or OVA file that will be created or updated by write().

Raises:	`ValueUnsupportedError` – if `detect_type_from_name()` fails

ovf_version¶

Float representing the OVF specification version in use.

Supported values at present are 0.9, 1.0, and 2.0.

platform¶

The platform type, as determined from the OVF descriptor.

This will be the class GenericPlatform or a more-specific subclass if recognized as such.

product¶: Short descriptive product string (XML Product element).

product_class¶: The product class identifier, such as com.cisco.csr1000v.

product_url¶: Product URL string (XML ProductUrl element).

system_types¶

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

For an OVF, this corresponds to the VirtualSystemType element.

vendor¶: Short descriptive vendor string (XML Vendor element).

vendor_url¶: Vendor URL string (XML VendorUrl element).

version_long¶: Long descriptive version string (XML FullVersion element).

version_short¶: Short descriptive version string (XML Version element).

byte_count(base_val, multiplier)[source]¶

Convert an OVF-style value + multiplier into decimal byte count.

Inverse operation of factor_bytes().

Parameters:	base_val (str) – Base value string (value of `ovf:capacity`, etc.) multiplier (str) – Multiplier string (value of `ovf:capacityAllocationUnits`, etc.)
Returns:	int – Number of bytes

Examples

>>> byte_count("128", "byte * 2^20")
134217728
>>> byte_count("512", "MegaBytes")
536870912

byte_string(byte_value, base_shift=0)[source]¶

Pretty-print the given bytes value.

Parameters:	byte_value (float) – Value base_shift (int) – Base value of byte_value (0 = bytes, 1 = KiB, 2 = MiB, etc.)
Returns:	str – Pretty-printed byte string such as “1.00 GiB”

Examples

>>> byte_string(512)
'512 B'
>>> byte_string(512, 2)
'512 MiB'
>>> byte_string(65536, 2)
'64 GiB'
>>> byte_string(65547)
'64.01 KiB'
>>> byte_string(65530, 3)
'63.99 TiB'
>>> byte_string(1023850)
'999.9 KiB'
>>> byte_string(1024000)
'1000 KiB'
>>> byte_string(1048575)
'1024 KiB'
>>> byte_string(1049200)
'1.001 MiB'
>>> byte_string(2560)
'2.5 KiB'

factor_bytes(byte_value)[source]¶

Convert a byte count into OVF-style bytes + multiplier.

Inverse operation of byte_count()

Parameters:	byte_value (int) – Number of bytes
Returns:	tuple – `(base_val, multiplier)`

Examples

>>> factor_bytes(134217728)
('128', 'byte * 2^20')
>>> factor_bytes(134217729)
('134217729', 'byte')

COT.ovf.ovf module¶

`COT.ovf.ovf` module¶