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.
- Remove files and disks from an OVF or OVA package
- 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
Installing COT¶
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.
Installing COT using pip
¶
Since COT is written in Python, it can be installed like any other Python package using the pip tool. For most users this is the recommended installation method.
sudo pip install cot
If you have already installed COT and wish to update to the latest available version:
sudo pip install --upgrade cot
Installing optional features¶
COT has a number of optional Python package dependencies that enable optional
features. If you want to use these features, you can instruct pip
to
install them as part of the COT installation process, or you can install them
separately after the fact.
Tab-completion of COT CLI parameters in
bash
, enabled with the argcomplete package.sudo pip install cot[tab-completion]
or
sudo pip install argcomplete
Note
After installing argcomplete by either method, you must configure your
bash
environment to enable it. Refer to the argcomplete documentation for the required steps.
Installing COT from source¶
If you wish to install bleeding-edge unreleased code or make code contributions of your own, you can install COT from source as described below.
Downloading 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
Installing 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 forkgenisoimage
) and/or xorriso to create ISO (CD-ROM) images for platforms that use ISOs to package the configuration. - 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.5.0+0.gaa8bcd9.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
- remove-file
- Remove a file from an OVF package
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 to /usr/local/bin
INFO: Successfully installed 'fatdisk'
INFO: Calling 'fatdisk --version' and capturing its output...
INFO: ...done
INFO: Installing 'vmdktool'...
INFO: vmdktool requires 'zlib'... installing 'zlib'
INFO: Calling 'dpkg -s zlib1g-dev' and capturing its output...
INFO: ...done
INFO: Compiling 'vmdktool'
INFO: Calling 'make CFLAGS="-D_GNU_SOURCE -g -O -pipe"'...
(...)
INFO: ...done
INFO: Compilation complete, installing to /usr/local
INFO: Calling 'make install'...
install -s vmdktool /usr/local/bin/
install vmdktool.8 /usr/local/man/man8/
INFO: ...done
INFO: Successfully installed 'vmdktool'
INFO: Calling 'vmdktool -V' and capturing its output...
INFO: ...done
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 product information with cot edit-product
¶
Synopsis¶
cot edit-product --help
cot <opts> edit-product PACKAGE [-o OUTPUT] [-p PRODUCT] [-n VENDOR]
[-v SHORT_VERSION] [-V FULL_VERSION]
[-u PRODUCT_URL ] [-r VENDOR_URL]
[-l APPLICATION_URL]
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 | |
-p PRODUCT, --product PRODUCT | |
Product name string, such as “Cisco IOS-XE” | |
-n VENDOR, --vendor VENDOR | |
Vendor string, such as “Cisco Systems, Inc.” | |
-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” | |
-u PRODUCT_URL, --product-url PRODUCT_URL | |
Product URL, such as “http://www.cisco.com/go/iosxrv“ | |
-r VENDOR_URL, --vendor-url VENDOR_URL | |
Vendor URL, such as “http://www.cisco.com“ | |
-l APPLICATION_URL, --application-url APPLICATION_URL | |
Application URL, such as “https://router1:530/“ |
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) |
Removing files from an OVF with cot remove-file
¶
Synopsis¶
cot remove-file --help
cot <opts> remove-file [-f FILE_PATH] [-i FILE_ID] PACKAGE
[-o OUTPUT]
Description¶
Remove a file from the given OVF. Will prompt for confirmation unless –force is set.
Options¶
- 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 |
File selection options¶
-f FILE_PATH, --file-path FILE_PATH | |
File name or path within the package | |
-i FILE_ID, --file-id FILE_ID | |
File ID string within the package |
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 ...]
[--delete-all-other-profiles]] [-c CPUS]
[-m MEMORY] [-n NICS]
[--nic-types TYPE [TYPE2 ...]]
[-N NETWORK [NETWORK2 ...]]
[-M MAC1 [MAC2 ...]]
[--nic-names NAME1 [NAME2 ...]]
[-s SERIAL_PORTS] [-S URI1 [URI2 ...]]
[--scsi-subtypes TYPE [TYPE2 ...]]
[--ide-subtypes TYPE [TYPE2 ...]]
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) | |
--delete-all-other-profiles | |
Delete all configuration profiles other than those specified with the –profiles option |
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-types <TYPE...> | |
Set the hardware type(s) for all NICs. (default: do not change existing NICs, and new NICs added will match the existing type(s).) | |
--nic-names <NAME1...> | |
Specify a list of one or more NIC names or patterns to apply to NIC devices. See Notes. | |
-N <NETWORK...>, --nic-networks <NETWORK...> | |
Specify a series of one or more network names or patterns to map NICs to. See Notes. | |
-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 |
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-subtypes <TYPE...> | |
Set resource subtype(s) (such as “lsilogic” or “virtio”) for all SCSI controllers. If an empty string is provided, any existing subtype will be removed. | |
--ide-subtypes <TYPE...> | |
Set resource subtype(s) (such as “virtio”) for all IDE controllers. If an empty string is provided, any existing subtype will be removed. |
Notes¶
The –nic-names and –nic-networks options support the use of a wildcard value to automatically generate a series of consecutively numbered names. The syntax for the wildcard option is ‘{‘ followed by a number to start incrementing from, followed by ‘}’. See examples below.
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
Wildcard example - without caring about how many NICs are defined in the input OVA, rename all of the NICs in the output OVA as ‘Ethernet0/10’, ‘Ethernet0/11’, ‘Ethernet0/12’, etc., and map them to networks ‘Ethernet0_10’, ‘Ethernet0_11’, ‘Ethernet0_12’, etc.
cot edit-hardware input.ova -o output.ova \
--nic-names "Ethernet0/{10}" \
--nic-networks "Ethernet0_{10}"
Combination of fixed and wildcarded names - 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}"
Customizing OVF environment settings with cot edit-properties
¶
Synopsis¶
cot edit-properties --help
cot <opts> edit-properties PACKAGE [-p KEY1=VALUE1 [KEY2=VALUE2 ...]]
[-c CONFIG_FILE]
[-t TRANSPORT [TRANSPORT2 ...]]
[-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 no arguments (other than optionally –output) 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. | |
-t <TRANSPORT...>, --transports <TRANSPORT...> | |
Set the transport method(s) for properties. Known values are ‘iso’, ‘vmware’, and ‘ibm’, or an arbitrary URI may be specified. |
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.
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 ...]]
[-S CONN1 [-S CONN2 ...]]
[-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. | |
-S <CONN1...>, --serial-connection <CONN1...> | |
Set connectivity for a serial port defined in the OVF. This argument may be repeated to specify more port connections. Each entry should be structured as ‘kind:value[,options]’. | |
-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, and creating the serial port as a telnet server listening on port 10022 of the host
cot deploy foo.ova esxi 192.0.2.100 -u admin -c 1CPU-2.5GB \
-S telnet://:10022,server
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"
Change Log¶
All notable changes to the COT project will be documented in this file. This project adheres to Semantic Versioning.
1.5.0 - 2016-06-06¶
Added
- #47 - Added
cot remove-file
subcommand. - #43 - add
cot edit-properties --transport
option to set environment transport type(s) - iso, VMWare Tools, etc.cot info
now has a new “Environment” section that displays the transport type
- #45 - support for multiple values for
--nic-types
,--ide-subtypes
, and--scsi-subtypes
incot edit-hardware
. - COT now recognizes the Cisco IOS XRv 9000 platform identifier
com.cisco.ios-xrv9000
. - #21 - subcommand aliases (Python 3.x only):
cot edit-product
aliases:cot set-product
,cot set-version
cot edit-properties
aliases:cot set-properties
,cot edit-environment
,cot set-environment
cot info
alias:cot describe
cot inject-config
alias:cot add-bootstrap
cot remove-file
alias:cot delete-file
- Support for tab-completion of CLI parameters using argcomplete.
Changed
cot edit-hardware
options--nic-types
,--ide-subtypes
, and--scsi-subtypes
are now validated and canonicalized by COT, meaning that:cot edit-hardware --nic-type virtio-net-pci
is now a valid command and will correctly create an OVF withResourceSubType
virtio
(notvirtio-net-pci
)cot edit-hardware --ide-subtype foobar
will now fail with an error
cot info
is now more self-consistent in how it displays property keys. They are now always wrapped in<
>
, whereas previously this was only sometimes the case.cot info --verbose
now displays file and disk ID strings under the “Files and Disks” section.
1.4.2 - 2016-05-11¶
Added
- COT now supports
xorriso
as another alternative tomkisofs
andgenisoimage
Fixed
- #42 -
cot deploy esxi
error handling behavior needed to be updated for requests release 2.8. - #44 - test case failure seen when running pyVmomi 6.0.0.2016.4.
Changed
1.4.0 - 2015-09-01¶
Added
- #24 -
cot deploy esxi
now creates serial ports after deployment using pyVmomi library.- Serial port connectivity must be specified either via entries in the OVF
(which can be defined using
cot edit-hardware ... -S
) or at deployment time using the new-S
/--serial-connection
parameter tocot deploy
. - The syntax for serial port connectivity definition is based
on that of QEMU’s
--serial
CLI option. - Currently only “telnet”, “tcp”, and “device” connection types are supported.
- Serial port connectivity must be specified either via entries in the OVF
(which can be defined using
- #38 -
cot edit-product
can now set product and vendor information. - flake8 validation now includes pep257 to validate docstring compliance to PEP 257 as well.
- Added changelog file.
- Added
COT.file_reference
submodule in support of #39.
Changed
- Split ESXi-specific logic out of
COT.deploy
module and into newCOT.deploy_esxi
module. - UT for
COT.deploy_esxi
now requiresmock
(standard library in Python 3.x, install via pip on Python 2.x).
Fixed
- #39 - avoid unnecessary file copies to save time and disk space.
1.3.1 - 2015-04-09¶
Fixed
- #30 -
cot install-helpers
can now installfatdisk
andvmdktool
under Python 3.
1.3.0 - 2015-03-27¶
Added
- Installation of helper programs is now provided by a
cot install-helpers
subcommand rather than a separate script. - COT now has man pages (
man cot
,man cot-edit-hardware
, etc.) The man pages are also installed bycot install-helpers
. - Improved documentation of the CLI on readthedocs.org as well.
Changed
- Refactored
COT.helper_tools
module intoCOT.helpers
subpackage. This package has an API (COT.helpers.api
) for the rest of COT to access it; the helper-specific logic (qemu-img, fatdisk, etc.) is split into individual helper modules that are abstracted away by the API. - Similarly, logic from
COT.tests.helper_tools
has been refactored and enhanced underCOT.helpers.tests
. - Renamed all test code files from “foo.py” to “test_foo.py” to facilitate test case discovery.
- CLI help strings are dynamically rendered to ReST when docs are built, providing cleaner output for both readthedocs.org and the manpages.
Removed
- COT no longer supports Python 3.2.
cot_unittest
is no more - usetox
orunit2 discover
to run tests.- As noted above, the installation script
check_and_install_helpers.py
no longer exists - this functionality is now provided by theCOT.install_helpers
module.
1.2.2 - 2015-02-19¶
Added
- Documentation built with Sphinx and available at http://cot.readthedocs.org
Changed
- CLI adapts more intelligently to terminal width (fixes #28)
- Submodules now use Python properties instead of get_value/set_value methods.
1.2.1 - 2015-02-03¶
Added
- Now PEP 8 compliant - passes validation by flake8 code analysis.
- Very preliminary support for OVF 2.x format
- Now uses tox for easier test execution and coverage.py for code coverage analysis.
- Code coverage reporting with Coveralls.
Changed
- Now uses colorlog instead of
coloredlogs
for CLI log colorization, as this fits better with COT’s logging model. - Greatly improved unit test structure and code coverage, including tests for logging.
1.2.0 - 2015-01-16¶
Added
- Greatly improved logging (#26). COT now defaults to logging level INFO,
which provides relatively brief status updates to the user. You can also
run with
--quiet
to suppress INFO messages and only log WARNING and ERROR messages,--verbose
to see VERBOSE messages as well, or--debug
if you want to really get into the guts of what COT is doing. - Now integrated with Travis CI for automated builds and UT under all supported Python versions. This should greatly improve the stability of COT under less-common Python versions. (#12)
Changed
- The CLI for
cot deploy
has been revised somewhat based on user feedback. - A lot of restructuring of the underlying code to make things more modular and easier to test in isolation.
Fixed
- Various bugfixes for issues specific to Python 2.6 and 3.x - these environments should now be fully working again.
1.1.6 - 2015-01-05¶
Added
- Added THANKS file recognizing various non-code contributions to COT.
Fixed
1.1.5 - 2014-11-25¶
Fixed
- Fixed issue #17 (
cot edit-hardware
adding NICs makes an OVA that vCenter regards as invalid) - Removed several spurious WARNING messages
1.1.4 - 2014-11-12¶
Added
- COT can at least be installed and run under CentOS/Python2.6 now, although the automated unit tests will complain about the different XML output that 2.6 produces.
Changed
- Vastly improved installation workflow under Linuxes supporting
apt-get
oryum
- included helper script can automatically install all helper programs exceptovftool
. Fixes #9.
Fixed
1.1.3 - 2014-10-01¶
Added
cot edit-hardware
added--nic-names
option for assigning names to each NICcot info
now displays NIC names.
Fixed
- Improved installation documentation
- Some improvements to IOS XRv OVA support
1.1.2 - 2014-09-24¶
Added
- Take advantage of QEMU 2.1 finally supporting the
streamOptimized
VMDK sub-format. - Can now create new hardware items without an existing item of the same type (issue #4)
Changed
- Clearer documentation and logging messages (issue #8 and others)
- Now uses versioneer for automatic version numbering.
Fixed
- Fixed several Python 3 compatibility issues (issue #7 and others)
1.1.0 - 2014-07-29¶
Added
cot deploy esxi
subcommand by Kevin Keim (@kakeim), which usesovftool
to deploy an OVA to an ESXi vCenter server.
Changed
- Removed dependencies on
md5
/md5sum
/shasum
/sha1sum
in favor of Python’shashlib
module. - Nicer formatting of
cot info
output
Fixed
- Miscellaneous fixes and code cleanup.
1.0.0 - 2014-06-27¶
Initial public release.
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
- Open a pull request
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¶
We try to keep COT’s code base compliant with Python coding standards including
PEP 8 and PEP 257. We use the flake8 and pep257 tools to verify this
as part of our test automation. To run coding style analysis independently
of the other test automation, you can run tox -e flake8
, or you can
install these tools and run flake8
directly:
cot/$ sudo pip install --upgrade flake8
cot/$ sudo pip install --upgrade pep257
cot/$ sudo pip install --upgrade flake8-pep257
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
py33: commands succeeded
py34: commands succeeded
pypy: commands succeeded
flake8: commands succeeded
docs: commands succeeded
stats: 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.
Open a pull request¶
COT follows Vincent Driessen’s A successful Git branching model. As such,
please submit feature enhancement and non-critical bugfix requests to merge
into the develop
branch rather than master
.
Credits¶
We would like to thank:
- For evangelization, user feedback and bug reports:
- Arun Arunkumar
- Mark Coverdill
- Myles Dear
- Jonathan Muslow
- Rick Ogg
- David Rosenfeld
- Rafal Skorka
- 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.deploy_esxi |
Module for deploying VMs to ESXi, vCenter, and vSphere. |
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. |
COT.remove_file |
Module for removing files from VM definitions. |
Helper library modules¶
COT.data_validation |
Various helpers for data sanity checks. |
COT.file_reference |
Wrapper classes to abstract away differences between file sources. |
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, genisoimage, or xorriso 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. |