Common OVF Tool (COT)¶

Introduction¶

COT (the Common OVF Tool) is a tool for editing Open Virtualization Format (.ovf, .ova) virtual appliances, with a focus on virtualized network appliances such as the Cisco CSR 1000V and Cisco IOS XRv platforms.

COT’s capabilities include:

Add a disk or other file to an OVF/OVA
Edit OVF hardware information (CPUs, RAM, NICs, configuration profiles, etc.)
Edit product description information in an OVF/OVA
Edit OVF environment properties
Display a descriptive summary of the contents of an OVA or OVF package
Embed a bootstrap configuration text file into an OVF/OVA.
Deploy an OVF/OVA to an ESXi (VMware vSphere or vCenter) server to provision a new virtual machine (VM).

Examples¶

Displaying a summary of OVA contents:

> cot info --brief iosxrv.5.1.1.ova
---------------------------------------------------------------------------
iosxrv.5.1.1.ova
COT detected platform type: Cisco IOS XRv
---------------------------------------------------------------------------
Product:  Cisco IOS XRv
Vendor:   Cisco Systems, Inc.
Version:  5.1.1

Files and Disks:     File Size  Capacity Device
                     --------- --------- --------------------
  iosxrv.vmdk        271.59 MB   3.00 GB harddisk @ IDE 0:0

Hardware Variants:
  System types:             vmx-08 Cisco:Internal:VMCloud-01
  Ethernet device types:    E1000

Configuration Profiles:   CPUs    Memory NICs Serials Disks/Capacity
                          ---- --------- ---- ------- --------------
  1CPU-3GB-2NIC (default)    1   3.00 GB    2       2  1 /   3.00 GB
  2CPU-4GB-8NIC              2   4.00 GB    8       2  1 /   3.00 GB
  4CPU-6GB-10NIC             4   6.00 GB   10       2  1 /   3.00 GB

Adding a custom hardware configuration profile to an OVA:

> cot edit-hardware csr1000v.ova --output csr1000v_custom.ova \
      --profile 1CPU-4GB --cpus 1 --memory 4GB

Customizing OVF environment properties:

> cot edit-properties csr1000v.ova --output csr1000v_custom.ova \
      --properties mgmt-ipv4-addr=10.1.1.100/24 \
                   mgmt-ipv4-gateway=10.1.1.1

System requirements ¶

COT requires either Python 2.7 or Python 3.3 or later.
COT is tested to work under Mac OS X and Ubuntu Linux and similar distros.
COT now has limited support for CentOS and Python 2.6 as well.

On Mac OS X you can install COT from MacPorts, or you can install it manually by following the same steps as Linux, described below.

Download COT ¶

You can download COT via Git or using HTTP.

git clone git://github.com/glennmatthews/cot
cd cot

or

wget -O cot.tgz https://github.com/glennmatthews/cot/archive/master.tar.gz
tar zxf cot.tgz
cd cot-master

or

curl -o cot.tgz https://github.com/glennmatthews/cot/archive/master.tar.gz
tar zxf cot.tgz
cd cot-master

Install the COT libraries and script ¶

sudo python setup.py install

Install helper programs ¶

Certain COT features require helper programs - you can install these as part of the COT installation process, or they can be installed as-needed by COT:

COT uses qemu-img as a helper program for various operations involving the creation, inspection, and modification of hard disk image files packaged in an OVF.
The cot add-disk command requires either qemu-img (version 2.1 or later) or vmdktool as a helper program when adding hard disks to an OVF.
The cot inject-config command requires mkisofs (or its fork genisoimage) to create ISO (CD-ROM) images for platforms that use ISOs.
Similarly, for platforms using hard disks for bootstrap configuration, cot inject-config requires fatdisk to format hard disk images.
The cot deploy ... esxi command requires ovftool to communicate with an ESXi server. If ovftool is installed, COT’s automated unit tests will also make use of ovftool to perform additional verification that OVFs and OVAs created by COT align with VMware’s expectations for these file types.

COT can attempt to install these tools using the appropriate package manager for your platform (i.e., MacPorts for Mac OS X, and either apt-get or yum for Linux).

Warning

Unfortunately, VMware requires a site login to download ovftool, so if you need this tool, you will have to install it yourself. COT cannot install it for you at present.

To let COT attempt to pre-install all of the above helpers, you can optionally run:

cot install-helpers

See here for more details.

If you skip this step, then when you are running COT, and it encounters the need for a helper that has not been installed, COT will prompt you to allow it to install the helper in question.

Using COT¶

Getting CLI help¶

Synopsis¶

cot --help
cot --version
cot help <command>
cot <command> --help
cot <options> <command> <command-options>

Description¶

Common OVF Tool (COT), version 1.3.0+0.g250307f.dirty

A tool for editing Open Virtualization Format (.ovf, .ova) virtual appliances, with a focus on virtualized network appliances such as the Cisco CSR 1000V and Cisco IOS XRv platforms.

You can always get detailed help for COT by running cot --help, cot <command> --help, or cot help <command>.

Options¶

`-h, --help`	show this help message and exit
`-V, --version`	show program’s version number and exit
`-f, --force`	Perform requested actions without prompting for confirmation
`-q, --quiet`	Quiet output and logging (warnings and errors only)
`-v, --verbose`	Verbose output and logging
`-d, --debug`	Debug (most verbose) output and logging

Commands¶

add-disk: Add a disk image to an OVF package and map it as a disk in the guest environment
add-file: Add a file to an OVF package
deploy: Create a new VM on the target hypervisor from the given OVF or OVA
edit-hardware: Edit virtual machine hardware properties of an OVF
edit-product: Edit product info in an OVF
edit-properties: Edit environment properties of an OVF
help: Print help for a command
info: Generate a description of an OVF package
inject-config: Inject a configuration file into an OVF package
install-helpers: Install/verify COT manual pages and any third- party helper programs that COT may require

Verifying and installing helper programs with `cot install-helpers`¶

Synopsis¶

cot install-helpers --help
cot <opts> install-helpers --verify-only
cot <opts> install-helpers [--ignore-errors]

Description¶

Install or verify the installation of COT manual pages and various required third-party helper programs for COT.

qemu-img (http://www.qemu.org/)
mkisofs (http://cdrecord.org/)
ovftool (https://www.vmware.com/support/developer/ovf/)
fatdisk (http://github.com/goblinhack/fatdisk)
vmdktool (http://www.freshports.org/sysutils/vmdktool/)

Options¶

`-h, --help`	show this help message and exit
`--verify-only`	Only verify helpers – do not attempt to install any missing helpers.
`-i, --ignore-errors`
	Do not fail even if helper installation fails.

Examples¶

Verify whether COT can find all expected helper programs

> cot install-helpers --verify-only
Results:
-------------
COT manpages: present in /usr/share/man/man1/
fatdisk:      present at /opt/local/bin/fatdisk
mkisofs:      present at /opt/local/bin/mkisofs
ovftool:      present at /usr/local/bin/ovftool
qemu-img:     present at /opt/local/bin/qemu-img
vmdktool:     NOT FOUND

Have COT attempt to install missing helpers for you. Note that most helpers require administrator / sudo privileges to install. If any installation fails, COT will exit with an error, unless you pass --ignore-errors.

> cot install-helpers
    INFO: Installing 'fatdisk'...
    INFO: Compiling 'fatdisk'
    INFO: Calling './RUNME'...
(...)
    INFO: ...done
    INFO: Compilation complete, installing now
    INFO: Calling 'sudo cp fatdisk /usr/local/bin/fatdisk'...
    INFO: ...done
    INFO: Successfully installed 'fatdisk'
    INFO: Installing 'vmdktool'...
    INFO: vmdktool requires 'zlib'... installing 'zlib'
    INFO: Calling 'sudo apt-get -q install zlib1g-dev'...
(...)
    INFO: ...done
    INFO: Compiling 'vmdktool'
    INFO: Calling 'make CFLAGS="-D_GNU_SOURCE -g -O -pipe"'...
(...)
    INFO: ...done
    INFO: Compilation complete, installing now.
    INFO: Calling 'sudo mkdir -p --mode=755 /usr/local/man/man8'...
    INFO: ...done
    INFO: Calling 'sudo make install'...
install -s vmdktool /usr/local/bin/
install vmdktool.8 /usr/local/man/man8/
    INFO: ...done
    INFO: Successfully installed 'vmdktool'
    INFO: Copying cot-add-disk.1 to /usr/share/man/man1/cot-add-disk.1
(...)
    INFO: Copying cot.1 to /usr/share/man/man1/cot.1
Results:
-------------
COT manpages: successfully installed to /usr/share/man
fatdisk:      successfully installed to /usr/local/bin/fatdisk
mkisofs:      present at /usr/bin/mkisofs
ovftool:      INSTALLATION FAILED: No support for automated
              installation of ovftool, as VMware requires a site
              login to download it. See
              https://www.vmware.com/support/developer/ovf/
qemu-img:     present at /usr/bin/qemu-img
vmdktool:     successfully installed to /usr/local/bin/vmdktool

Unable to install some helpers

Warning

Unfortunately, VMware requires a site login to download ovftool, so if you need this tool, you will have to install it yourself. COT cannot install it for you at present.

Inspecting OVF contents with `cot info`¶

Synopsis¶

cot info --help
cot info [-b | -v] PACKAGE [PACKAGE ...]

Description¶

Show a summary of the contents of the given OVF(s) and/or OVA(s).

Options¶

PACKAGE [PACKAGE ...]: OVF descriptor(s) and/or OVA file(s) to describe

`-h, --help`	show this help message and exit
`-b, --brief`	Brief output (shorter)
`-v, --verbose`	Verbose output (longer)

Updating version information with `cot edit-product`¶

Synopsis¶

cot edit-product --help
cot <opts> edit-product PACKAGE [-o OUTPUT] [-v SHORT_VERSION]
                        [-V FULL_VERSION]

Description¶

Edit product information attributes of the given OVF or OVA

Options¶

PACKAGE: OVF descriptor or OVA file to edit

`-h, --help`	show this help message and exit
`-o OUTPUT, --output OUTPUT`
	Name/path of new OVF/OVA package to create instead of updating the existing OVF
`-v SHORT_VERSION, --version SHORT_VERSION`
	Software short version string, such as “15.3(4)S” or “5.2.0.01I”
`-V FULL_VERSION, --full-version FULL_VERSION`
	Software long version string, such as “Cisco IOS-XE Software, Version 15.3(4)S”

Adding disks to an OVF with `cot add-disk`¶

Synopsis¶

cot add-disk --help
cot <opts> add-disk DISK_IMAGE PACKAGE [-o OUTPUT] [-f FILE_ID]
                    [-t {harddisk,cdrom}] [-c {ide,scsi}]
                    [-s SUBTYPE] [-a ADDRESS] [-d DESCRIPTION]
                    [-n DISKNAME]

Description¶

Add or replace a disk image in the specified OVF or OVA. If the specified disk image, controller/address, file-id, and/or instance match an existing entry in the OVF, will replace the existing disk with the provided file (prompting for confirmation if –force was not set); otherwise, will create a new disk entry.

Options¶

DISK_IMAGE: Disk image file to add to the package
PACKAGE: OVF descriptor or OVA file to edit

General options¶

`-h, --help`	Show this help message and exit
`-o OUTPUT, --output OUTPUT`
	Name/path of new OVF/OVA package to create instead of updating the existing OVF

Descriptive options¶

`-d DESCRIPTION, --description DESCRIPTION`
	Description of this disk (optional)
`-n DISKNAME, --name DISKNAME`
	Name of this disk (default: “Hard disk #” or “CD-ROM #” as appropriate)

Packaging additional files into an OVF with `cot add-file`¶

Synopsis¶

cot add-file --help
cot <opts> add-file FILE PACKAGE [-o OUTPUT] [-f FILE_ID]

Description¶

Add or replace a file in the given OVF. If the specified file and/or file-id match existing package contents, will replace it (prompting for confirmation if –force was not set); otherwise, will create a new file entry.

Options¶

FILE: File to add to the package
PACKAGE: Package, OVF descriptor or OVA file to edit

`-h, --help`	show this help message and exit
`-o OUTPUT, --output OUTPUT`
	Name/path of new VM package to create instead of updating the existing package
`-f FILE_ID, --file-id FILE_ID`
	File ID string within the package (default: same as filename)

Customizing hardware profiles with `cot edit-hardware`¶

Synopsis¶

cot edit-hardware --help
cot <opts> edit-hardware PACKAGE [-o OUTPUT] -v TYPE [TYPE2 ...]
cot <opts> edit-hardware PACKAGE [-o OUTPUT]
                         [-p PROFILE [PROFILE2 ...]] [-c CPUS]
                         [-m MEMORY] [-n NICS]
                         [--nic-type {e1000,virtio,vmxnet3}]
                         [-N NETWORK [NETWORK2 ...]]
                         [-M MAC1 [MAC2 ...]]
                         [--nic-names NAME1 [NAME2 ...]]
                         [-s SERIAL_PORTS] [-S URI1 [URI2 ...]]
                         [--scsi-subtype SCSI_SUBTYPE]
                         [--ide-subtype IDE_SUBTYPE]

Description¶

Edit hardware properties of the specified OVF or OVA

Options¶

PACKAGE: OVF descriptor or OVA file to edit

General options¶

`-h, --help`	Show this help message and exit
`-o OUTPUT, --output OUTPUT`
	Name/path of new OVF/OVA package to create instead of updating the existing OVF
`-v <TYPE...>, --virtual-system-type <TYPE...>`
	Change virtual system type(s) supported by this OVF/OVA package.
`-p <PROFILE...>, --profiles <PROFILE...>`
	Make hardware changes only under the given configuration profile(s). (default: changes apply to all profiles)

Computational hardware options¶

`-c CPUS, --cpus CPUS`
	Set the number of CPUs.
`-m MEMORY, --memory MEMORY`
	Set the amount of RAM. (Examples: “4096MB”, “4GB”)

Network interface options¶

`-n NICS, --nics NICS`
	Set the number of NICs.
`--nic-type <e1000,virtio,vmxnet3>`
	Set the hardware type for all NICs. (default: do not change existing NICs, and new NICs added will match the existing type.)
`-N <NETWORK...>, --nic-networks <NETWORK...>`
	Specify a series of one or more network names to map NICs to. If N network names are specified, the first (N-1) NICs will be mapped to the first (N-1) networks and all remaining NICs will be mapped to the Nth network.
`-M <MAC1...>, --mac-addresses-list <MAC1...>`
	Specify a list of MAC addresses for the NICs. If N MACs are specified, the first (N-1) NICs will receive the first (N-1) MACs, and all remaining NICs will receive the Nth MAC
`--nic-names <NAME1...>`
	Specify a list of one or more NIC names or patterns to apply to NIC devices. If N names/patterns are specified, the first (N-1) NICs will receive the first (N-1) names and remaining NICs will be named based on the name or pattern of the Nth item. See examples.

Serial port options¶

`-s SERIAL_PORTS, --serial-ports SERIAL_PORTS`
	Set the number of serial ports.
`-S <URI1...>, --serial-connectivity <URI1...>`
	Specify a series of connectivity strings (URIs such as “telnet://localhost:9101”) to map serial ports to. If fewer URIs than serial ports are specified, the remaining ports will be unmapped.

Disk and disk controller options¶

`--scsi-subtype SCSI_SUBTYPE`
	Set resource subtype (such as “lsilogic” or “virtio”) for all SCSI controllers. If an empty string is provided, any existing subtype will be removed.
`--ide-subtype IDE_SUBTYPE`
	Set resource subtype (such as “virtio”) for all IDE controllers. If an empty string is provided, any existing subtype will be removed.

Examples¶

Create a new profile named “1CPU-8GB” with 1 CPU and 8 gigabytes of RAM

cot edit-hardware csr1000v.ova --output csr1000v_custom.ova \
    --profile 1CPU-4GB --cpus 1 --memory 8GB

Rename the NICs in the output OVA as ‘mgmt’, ‘eth0’, ‘eth1’, ‘eth2’...

cot edit-hardware input.ova -o output.ova --nic-names "mgmt" \
    "eth{0}"

Rename the NICs in the output OVA as ‘Ethernet0/10’, ‘Ethernet0/11’, ‘Ethernet0/12’, etc.

cot edit-hardware input.ova -o output.ova \
    --nic-names "Ethernet0/{10}"

Customizing OVF environment settings with `cot edit-properties`¶

Synopsis¶

cot edit-properties --help
cot <opts> edit-properties PACKAGE -p KEY1=VALUE1 [KEY2=VALUE2 ...]
                           [-o OUTPUT]
cot <opts> edit-properties PACKAGE -c CONFIG_FILE [-o OUTPUT]
cot <opts> edit-properties PACKAGE [-o OUTPUT]

Description¶

Configure environment properties of the given OVF or OVA. The user may specify key-value pairs as command-line arguments or may provide a config-file to read from. If neither are specified, the program will run interactively.

Options¶

PACKAGE: OVF descriptor or OVA file to edit

General options¶

`-h, --help`	Show this help message and exit
`-o OUTPUT, --output OUTPUT`
	Name/path of new OVF/OVA package to create instead of updating the existing OVF

Property setting options¶

`-c CONFIG_FILE, --config-file CONFIG_FILE`
	Read configuration CLI from this text file and generate generic properties for each line of CLI
`-p <KEY1=VALUE1...>, --properties <KEY1=VALUE1...>`
	Set the given property key-value pair(s). This argument may be repeated as needed to specify multiple properties to edit.

Embedding bootstrap configuration with `cot inject-config`¶

Synopsis¶

cot inject-config --help
cot <opts> inject-config PACKAGE -c CONFIG_FILE [-o OUTPUT]
cot <opts> inject-config PACKAGE -s SECONDARY_CONFIG_FILE [-o OUTPUT]
cot <opts> inject-config PACKAGE -c CONFIG_FILE
                         -s SECONDARY_CONFIG_FILE [-o OUTPUT]

Description¶

Add one or more “bootstrap” configuration file(s) to the given OVF or OVA.

Options¶

PACKAGE: Package, OVF descriptor or OVA file to edit

`-h, --help`	show this help message and exit
`-o OUTPUT, --output OUTPUT`
	Name/path of new VM package to create instead of updating the existing package
`-c CONFIG_FILE, --config-file CONFIG_FILE`
	Primary configuration text file to embed
`-s SECONDARY_CONFIG_FILE, --secondary-config-file SECONDARY_CONFIG_FILE`
	Secondary configuration text file to embed (currently only supported in IOS XRv for admin config)

Deploying an OVF to create a VM with `cot deploy`¶

Synopsis¶

cot deploy --help
cot <opts> deploy PACKAGE esxi ...

Description¶

Deploy an OVF or OVA to create a virtual machine on a specified server.

Options¶

PACKAGE: OVF descriptor or OVA file

-h, --help

show this help message and exit

Hypervisors¶

esxi: Deploy to ESXi, vSphere, or vCenter

Creating a VM on VMware vCenter/vSphere with `cot deploy esxi`¶

Synopsis¶

cot deploy PACKAGE esxi --help
cot <opts> deploy PACKAGE esxi LOCATOR [-u USERNAME] [-p PASSWORD]
                               [-c CONFIGURATION] [-n VM_NAME] [-P]
                               [-N OVF1=HOST1 [-N OVF2=HOST2 ...]]
                               [-d DATASTORE] [-o=OVFTOOL_ARGS]

Description¶

Deploy OVF/OVA to ESXi/vCenter/vSphere hypervisor

Options¶

LOCATOR: vSphere target locator. Examples: “192.0.2.100” (deploy directly to ESXi server), “192.0.2.101/mydatacenter/host/192.0.2.100” (deploy via vCenter server)

`-h, --help`	show this help message and exit
`-u USERNAME, --username USERNAME`
	Server login username
`-p PASSWORD, --password PASSWORD`
	Server login password
`-c CONFIGURATION, --configuration CONFIGURATION`
	Use the specified configuration profile defined in the OVF. If unspecified and the OVF has multiple profiles, the user will be prompted or the default configuration will be used.
`-n VM_NAME, --vm-name VM_NAME`
	Name to use for the VM (if applicable) and any files created. If unspecified, the name of the OVF will be used.
`-P, --power-on`	Power on the created VM to begin booting immediately.
`-N <OVF_NET1=HOST_NET1...>, --network-map <OVF_NET1=HOST_NET1...>`
	Map networks named in the OVF to networks (bridges, vSwitches, etc.) in the hypervisor environment. This argument may be repeated as needed to specify multiple mappings.
`-d DATASTORE, --datastore DATASTORE`
	ESXi datastore to use for the new VM
`-o OVFTOOL_ARGS, --ovftool-args OVFTOOL_ARGS`
	Quoted string describing additional CLI parameters to pass through to “ovftool”. Examples: -o=”–foo”, –ovftool-args=”–foo –bar”

Examples¶

Deploy to vSphere/ESXi server 192.0.2.100 with credentials admin/admin, creating a VM named ‘test_vm’ from foo.ova.

cot deploy foo.ova esxi 192.0.2.100 -u admin -p admin \
    -n test_vm

Deploy to vSphere/ESXi server 192.0.2.100, with username admin (prompting the user to input a password at runtime), creating a VM based on profile ‘1CPU-2.5GB’ in foo.ova.

cot deploy foo.ova esxi 192.0.2.100 -u admin -c 1CPU-2.5GB

Deploy to vSphere server 192.0.2.1 which belongs to datacenter ‘mydc’ on vCenter server 192.0.2.100, and map the two NIC networks to vSwitches. Note that in this case -u specifies the vCenter login username.

cot deploy foo.ova esxi "192.0.2.100/mydc/host/192.0.2.1" \
    -u administrator -N "GigabitEthernet1=VM Network" \
    -N "GigabitEthernet2=myvswitch"

Deploy with passthrough arguments to ovftool.

cot deploy foo.ova esxi 192.0.2.100 -u admin -p password \
    --ovftool-args="--overwrite --acceptAllEulas"

Contributing to COT¶

Please do contribute! We only have a few simple requirements for diffs and pull requests.

Follow coding guidelines
Add automated unit tests
Update documentation
Add yourself as a contributor

Follow coding guidelines¶

Logging level usage¶

ERROR

Something is wrong (such as a violation of the OVF specification) but COT was able to attempt to recover. If recovery is not possible, you should raise an Error of appropriate type instead of logging an ERROR message.

WARNING

Something unexpected or risky happened that the user needs a heads-up about. This includes cases where the software had to make an uncertain choice on its own due to lack of information from the user.

INFO

Important status updates about normal operation of the software. As this is the lowest logging level enabled by default, you should keep the logs generated at this level relatively brief but meaningful.

VERBOSE

Detailed information of interest to an advanced or inquisitive user.

DEBUG

Highly detailed information only useful to a developer familiar with the code.

Coding style¶

To verify that your code meets applicable Python coding standards, use flake8 (pip install flake8):

cot/$ flake8
./COT/tests/ovf.py:180:80: E501 line too long (80 > 79 characters)
./COT/tests/ovf.py:184:77: F841 local variable 'ovf' is assigned to but never used
./COT/tests/ovf.py:184:80: E501 line too long (80 > 79 characters)
./COT/tests/ovf.py:196:40: F841 local variable 'ova' is assigned to but never used
./COT/tests/ovf.py:210:75: F841 local variable 'ovf' is assigned to but never used
./COT/ovf.py:776:5: E303 too many blank lines (2)

Fix any errors it reports, and run again until no errors are reported.

Add automated unit tests¶

Whether adding new functionality or fixing a bug, please add appropriate unit test case(s) under COT/tests/ to cover your changes. Your changes must pass all existing and new automated test cases before your code will be accepted.

You can run the COT automated tests under a single Python version by running python ./setup.py test.

For full testing under all supported versions as well as verifying code coverage for your tests, you should install tox (pip install tox) and coverage (pip install coverage) then run tox from the COT directory:

cot/$ tox
...
py26 runtests: commands[0] | coverage run --append setup.py test --quiet
...
py27 runtests: commands[0] | coverage run --append setup.py test --quiet
...
py32 runtests: commands[0] | coverage run --append setup.py test --quiet
...
py33 runtests: commands[0] | coverage run --append setup.py test --quiet
...
py34 runtests: commands[0] | coverage run --append setup.py test --quiet
...
pypy runtests: commands[0] | coverage run --append setup.py test --quiet
...
stats runtests: commands[0] | coverage combine
stats runtests: commands[1] | coverage report -i
Name                        Stmts   Miss  Cover
-----------------------------------------------
COT/__init__.py                 4      0   100%
COT/add_disk.py               147      1    99%
COT/add_file.py                50      0   100%
COT/cli.py                    143      6    96%
COT/data_validation.py         69      0   100%
COT/deploy.py                 142      5    96%
COT/edit_hardware.py          159      0   100%
COT/edit_product.py            36      0   100%
COT/edit_properties.py        104     40    62%
COT/helper_tools.py           171      3    98%
COT/info.py                    41      0   100%
COT/inject_config.py           87      2    98%
COT/ovf.py                   1586     52    96%
COT/platforms.py              173      0   100%
COT/submodule.py               80      2    98%
COT/ui_shared.py               24      0   100%
COT/vm_context_manager.py      12      0   100%
COT/vm_description.py         119      1    99%
COT/vm_factory.py              25      0   100%
COT/xml_file.py               112      0   100%
-----------------------------------------------
TOTAL                        3284    112    96%
stats runtests: commands[2] | coverage html -i
...
flake8 runtests: commands[0] | flake8
_______________ summary _______________
  clean: commands succeeded
  py26: commands succeeded
  py27: commands succeeded
  py32: commands succeeded
  py33: commands succeeded
  py34: commands succeeded
  pypy: commands succeeded
  stats: commands succeeded
  flake8: commands succeeded
  congratulations :)

After running tox you can check the code coverage details by opening htmlcov/index.html in a web browser.

Update documentation¶

If you add or change any COT CLI or APIs, or add or remove any external dependencies, please update the relevant documentation.

Add yourself as a contributor¶

If you haven’t contributed to COT previously, be sure to add yourself as a contributor in the COPYRIGHT.txt file.

Credits¶

We would like to thank:

For evangelization, user feedback and bug reports:
- Mark Coverdill
- Jonathan Muslow
- Rick Ogg
- David Rosenfeld
- Perumal Venkatesh
For initial design review and comments:
- Andy Dalton
- Jusheng Feng
- Doug Gordon
- Lina Long
- Neil McGill
- Vinod Pandarinathan
- Rich Wellum
For providing managerial support for the development and release of COT as open source:
- Ray Romney
- Sanjeev Tondale
- Taskin Ucpinar
Rich Wellum, for creating “Build, Deploy, Execute OVA” (bdeo.sh), the precursor to COT.
Neil McGill, for creating and maintaining fatdisk
Brian Somers, for creating and maintaining vmdktool

`COT` package reference¶

The below documents describe in depth the code structure and APIs of COT. These are not generally of interest to the end users of the COT script, but are provided for reference of developers wishing to integrate the COT package directly into their code.

Package implementing the Common OVF Tool.

Virtual machine definition modules¶

`COT.vm_description`	Abstract superclass for reading, editing, and writing VMs.
`COT.vm_factory`	Factory for virtual machine objects.
`COT.vm_context_manager`	Context manager for virtual machine definitions.
`COT.xml_file`	Reading, editing, and writing XML files.
`COT.ovf`	Module for handling OVF and OVA virtual machine description files.

Command modules¶

`COT.submodule`	Parent classes for implementing COT subcommands.
`COT.add_disk`	Module for adding disks to VMs.
`COT.add_file`	Module for adding files to VM definitions.
`COT.deploy`	Module for deploying VM descriptions to a hypervisor to instantiate VMs.
`COT.edit_hardware`	Module for editing hardware details of a VM.
`COT.edit_product`	Module for editing product information in a VM description.
`COT.edit_properties`	Module for managing VM environment configuration properties.
`COT.help`	Provide ‘help’ keyword for COT CLI.
`COT.info`	Implements “info” subcommand.
`COT.inject_config`	Implements “inject-config” command.
`COT.install_helpers`	Implements “install-helpers” command.

Helper library modules¶

`COT.data_validation`	Various helpers for data sanity checks.
`COT.platforms`	Handles behavior that varies between guest platforms.

User interface modules¶

`COT.ui_shared`	Abstract user interface superclass.
`COT.cli`	CLI entry point for the Common OVF Tool (COT) suite.

`COT.helpers` package reference¶

Provide various non-Python helper programs that COT makes use of.

In general, COT submodules should work through the APIs provided in COT.helpers.api rather than accessing individual helper program classes. This gives us the flexibility to change the specific set of helper programs that are used to provide any given functionality with minimal impact to COT as a whole.

API¶

`convert_disk_image`	Convert the given disk image to the requested format/subformat.
`create_disk_image`	Create a new disk image at the requested location.
`get_checksum`	Get the checksum of the given file.
`get_disk_capacity`	Get the storage capacity of the given disk image.
`get_disk_format`	Get the disk image format of the given file.

Exceptions¶

`HelperError`	A helper program exited with non-zero return code.
`HelperNotFoundError`	A helper program cannot be located.

Helper modules¶

`COT.helpers.api`	API for abstract access to third-party helper tools.
`COT.helpers.helper`	Interface for providers of non-Python helper programs.
`COT.helpers.fatdisk`	Give COT access to `fatdisk` for creating and updating FAT32 file systems.
`COT.helpers.mkisofs`	Give COT access to `mkisofs` or `genisoimage` for creating ISO images.
`COT.helpers.ovftool`	Give COT access to `ovftool` for validating and deploying OVF to ESXi.
`COT.helpers.qemu_img`	Give COT access to `qemu-img` for manipulating disk image formats.
`COT.helpers.vmdktool`	Give COT access to `vmdktool` for manipulating compressed VMDK files.

`-f FILE_ID, --file-id FILE_ID`
	Disk image file ID string within the OVF package (default: use disk image filename)
`-t <harddisk,cdrom>, --type <harddisk,cdrom>`
	Disk type (default: files ending in .vmdk/.raw/.qcow2/.img will use harddisk and files ending in .iso will use cdrom)

`-c <ide,scsi>, --controller <ide,scsi>`
	Disk controller type (default: determined by disk type and platform)
`-a ADDRESS, --address ADDRESS`
	Address of the disk, such as “1:0”. Requires that –controller be explicitly set. (default: use first unused address on the controller)
`-s SUBTYPE, --subtype SUBTYPE`
	Disk controller subtype such as “virtio” or “lsilogic”.

Common OVF Tool (COT)¶

Introduction¶

Examples¶

Installing COT¶

System requirements¶

Download COT¶

Install the COT libraries and script¶

Install helper programs¶

Using COT¶

Getting CLI help¶

Synopsis¶

Description¶

Options¶

Commands¶

Verifying and installing helper programs with cot install-helpers¶

Synopsis¶

Description¶

Options¶

Examples¶

Inspecting OVF contents with cot info¶

Synopsis¶

Description¶

Options¶

Updating version information with cot edit-product¶

Synopsis¶

Description¶

Options¶

Adding disks to an OVF with cot add-disk¶

Synopsis¶

Description¶

Options¶

General options¶

Disk-related options¶

Controller-related options¶

Descriptive options¶

Packaging additional files into an OVF with cot add-file¶

Synopsis¶

Description¶

Options¶

Customizing hardware profiles with cot edit-hardware¶

Synopsis¶

Description¶

Options¶

General options¶

Computational hardware options¶

Network interface options¶

Serial port options¶

Disk and disk controller options¶

Examples¶

Customizing OVF environment settings with cot edit-properties¶

Synopsis¶

Description¶

Options¶

General options¶

Property setting options¶

Embedding bootstrap configuration with cot inject-config¶

Synopsis¶

Description¶

Options¶

Deploying an OVF to create a VM with cot deploy¶

Synopsis¶

Description¶

Options¶

Hypervisors¶

Creating a VM on VMware vCenter/vSphere with cot deploy esxi¶

Synopsis¶

Description¶

Options¶

Examples¶

Contributing to COT¶

Follow coding guidelines¶

Logging level usage¶

Coding style¶

Add automated unit tests¶

Update documentation¶

Add yourself as a contributor¶

Credits¶

COT package reference¶

Virtual machine definition modules¶

Command modules¶

System requirements ¶

Download COT ¶

Install the COT libraries and script ¶

Install helper programs ¶

Verifying and installing helper programs with `cot install-helpers`¶

Inspecting OVF contents with `cot info`¶

Updating version information with `cot edit-product`¶

Adding disks to an OVF with `cot add-disk`¶

Packaging additional files into an OVF with `cot add-file`¶

Customizing hardware profiles with `cot edit-hardware`¶

Customizing OVF environment settings with `cot edit-properties`¶

Embedding bootstrap configuration with `cot inject-config`¶

Deploying an OVF to create a VM with `cot deploy`¶

Creating a VM on VMware vCenter/vSphere with `cot deploy esxi`¶

`COT` package reference¶

`COT.helpers` package reference¶