Community developed software packages are typically ESXi drivers for hardware that is not supported by VMware (or 3rd party hardware vendors) out-of-the-box. Other examples are: Custom firewall rules (like the one that allows remote NTP queries) or scripts/binaries that add custom functionalities to ESXi.
Requirements
The scripts run on Windows XP or newer Windows versions (both 32-bit or 64-bit).
Installation Instructions
Download the latest version of the Packaging Tools (see Download section below). They are distributed as a signed self-extracting archive (created with 7-zip). Unpack the archive to a directory of your choice.
Usage Instructions
Step 1: Create your TGZ file
As a first step you need to create a gzip compressed tar archive (tar.gz or tgz) of all the files that make up your software package. It is necessary that
- all file paths in the archive are relative to the root (/) directory of the ESXi system, and
- all directories included in file paths must be explicitly added to the archive on their own
The easiest way to achieve that is to create an empty directory (on the ESXi or Linux system that you used for development), create the needed directory structure (starting at the root) in there and copy all files you want to include into the proper sub directories.
Here is an example of the required commands. For this example we assume that we want to build a driver package that consists of the following three files:
/etc/vmware/driver.map.d/e1001e.map
/usr/lib/vmware/vmkmod/e1001e
/usr/share/hwdata/driver.pciids.d/e1001e.ids
# cd /tmp
# mkdir build
# cd build
# mkdir -p etc/vmware/driver.map.d
# cp /etc/vmware/driver.map.d/e1001e.map etc/vmware/driver.map.d
# mkdir -p usr/lib/vmware/vmkmod
# cp /usr/lib/vmware/vmkmod/e1001e usr/lib/vmware/vmkmod
# mkdir -p usr/share/hwdata/driver.pciids.d
# cp /usr/share/hwdata/driver.pciids.d/e1001e.ids usr/share/hwdata/driver.pciids.d
You can then create the tgz file with
# tar cvzf ../e1001e.tgz *
When used with the v (=verbose) option the tar command will output the files that it added to the archive:
etc/
etc/vmware/
etc/vmware/driver.map.d/
etc/vmware/driver.map.d/e1001e.map
usr/
usr/lib/
usr/lib/vmware/
usr/lib/vmware/vmkmod/
usr/lib/vmware/vmkmod/e1001e
usr/share/
usr/share/hwdata/
usr/share/hwdata/driver.pciids.d/
usr/share/hwdata/driver.pciids.d/e1001e.ids
And this is exactly what it should look like. Please note that if you just add the individual files to the archive but not the directories you will risk a boot failure with a "Boot image corrupt" message once you install this package on a host.
So what have we got now? The tgz file that you created this way can be added to an ESXi 5.0 installation ISO with my ESXi-Customizer script, and if you install a machine with that customized ISO it will include the package.
But you can not add a tgz package to an already installed ESXi 5.0 system ... So let's take it a step further!
Step 2: Build a VIB file with tgz2vib5.cmd
What is a VIB file? VIB stands for VMware Installation Bundle. A VIB file includes a file archive like the one we created in Step 1, an XML file (descriptor.xml) with descriptive metadata and an electronic signature file (sig.pkcs7).
To create a VIB file from our tgz file run tgz2vib5.cmd:
The GUI is pretty self-explanatory, but here are some guidelines for using the right options and entering suitable metadata.
TGZ repacking options:
VIB description data: This is part of the metadata that will be stored in the file descriptor.xml.
If you are packaging an ESXi 5.0 hardware device driver I suggest that you follow these recommendations:
Pause execution for manual editing of descriptor.xml: Below you see a hardcopy of the descriptor.xml file that tgz2vib5.cmd will produce for the given example. You will notice that it includes much more attributes than the four that you were asked for. The remaining attributes describe e.g. dependencies to other packages, whether the installation requires maintenance mode or can be done live, etc.
tgz2vib5.cmd fills in the values here that are needed for a device driver package. If you want to create a package for something different - e.g. a custom firewall rule that does not require maintenance mode to be installed -, then you can manually edit the descriptor.xml file and provide the correct attributes. This is what this option is for.
So what have we got now? Like TGZ files the VIB file that you created with tgz2vib5.cmd can be added to an ESXi 5.0 installation ISO with my ESXi-Customizer script, but ...
... it can also be installed into a running ESXi 5.0 system by using the following commands inside an ESXi shell (or via the vSphere remote CLI):
The second command installs the package that needs to be locally accessible by ESXi. Alternatively you can provide a http-URL to download the vib file from a web site.
Now, let's take packaging another step further ...
Step 3: Build an Offline Bundle with vib2zip.cmd
What is an Offline Bundle? Basically it is a package containing one or multiple VIB files and additional metadata. The idea behind that is to create a depot of software packages. Before we dive deeper into this here is how you can create your own Offline bundle.
Run the vib2zip.cmd script:
All VIB files that you want to be included in the Offline bundle must be copied into the same directory (which is referred to as the source VIB directory here). If you will add only one VIB file it makes perfect sense to use the same metadata attributes for the Offline bundle that you also used for the VIB file. Otherwise you should just choose anything else that makes sense here.
With an Offline bundle you have two additional attributes available:
So what have we got now? Like TGZ and VIB files Offline bundles can be added to an ESXi 5.0 installation ISO with my ESXi-Customizer script. Like VIB files Offline bundles can be used to install a contained software package into a running ESXi 5.0 system by using the following commands inside an ESXi shell (or via the vSphere remote CLI):
So, what is unique to Offline bundles? You can
Support
# mkdir build
# cd build
# mkdir -p etc/vmware/driver.map.d
# cp /etc/vmware/driver.map.d/e1001e.map etc/vmware/driver.map.d
# mkdir -p usr/lib/vmware/vmkmod
# cp /usr/lib/vmware/vmkmod/e1001e usr/lib/vmware/vmkmod
# mkdir -p usr/share/hwdata/driver.pciids.d
# cp /usr/share/hwdata/driver.pciids.d/e1001e.ids usr/share/hwdata/driver.pciids.d
You can then create the tgz file with
# tar cvzf ../e1001e.tgz *
When used with the v (=verbose) option the tar command will output the files that it added to the archive:
etc/
etc/vmware/
etc/vmware/driver.map.d/
etc/vmware/driver.map.d/e1001e.map
usr/
usr/lib/
usr/lib/vmware/
usr/lib/vmware/vmkmod/
usr/lib/vmware/vmkmod/e1001e
usr/share/
usr/share/hwdata/
usr/share/hwdata/driver.pciids.d/
usr/share/hwdata/driver.pciids.d/e1001e.ids
So what have we got now? The tgz file that you created this way can be added to an ESXi 5.0 installation ISO with my ESXi-Customizer script, and if you install a machine with that customized ISO it will include the package.
But you can not add a tgz package to an already installed ESXi 5.0 system ... So let's take it a step further!
Step 2: Build a VIB file with tgz2vib5.cmd
What is a VIB file? VIB stands for VMware Installation Bundle. A VIB file includes a file archive like the one we created in Step 1, an XML file (descriptor.xml) with descriptive metadata and an electronic signature file (sig.pkcs7).
To create a VIB file from our tgz file run tgz2vib5.cmd:
 |
| TGZ2VIB5 v1.1 GUI |
TGZ repacking options:
- If you have followed the instructions from step 1 it is safe to choose "Do not touch" here.
- If you have not created the tgz file yourself you might want to choose "Force repacking", because this will repack the file and ensure that the complete directory structure is included (thus preventing the infamous "Boot image corrupt" failures).
- The last option "Force repacking and pause for adv. editing" will first unpack the tgz archive, then pause the script execution to let you manually edit the included files or even add new files to it, before it repacks the files into a new tgz package. Use this option only if you know what you are doing!
VIB description data: This is part of the metadata that will be stored in the file descriptor.xml.
If you are packaging an ESXi 5.0 hardware device driver I suggest that you follow these recommendations:
- For the name attribute use the name of the associated Linux device driver and prepend a prefix that denotes the driver's device type: net- for a network interface driver, scsi- for a SCSI controller driver, ata- and sata- for (S)ATA controller drivers.
- For the version attribute use the version of the associated Linux device driver (1.3.10a in this example) and append a unique build number (-1 in the example) that will help to distinguish multiple builds of the same source code version.
- For the vendor attribute fill in the vendor's name (meaning the producer of the device)
- In the description field write down what devices the driver can be used for. This is also the place to give credits to yourself or adding any other information that might be helpful for the users of this driver package.
Pause execution for manual editing of descriptor.xml: Below you see a hardcopy of the descriptor.xml file that tgz2vib5.cmd will produce for the given example. You will notice that it includes much more attributes than the four that you were asked for. The remaining attributes describe e.g. dependencies to other packages, whether the installation requires maintenance mode or can be done live, etc.
tgz2vib5.cmd fills in the values here that are needed for a device driver package. If you want to create a package for something different - e.g. a custom firewall rule that does not require maintenance mode to be installed -, then you can manually edit the descriptor.xml file and provide the correct attributes. This is what this option is for.
 |
| descriptor.xml file created by tgz2vib5 |
... it can also be installed into a running ESXi 5.0 system by using the following commands inside an ESXi shell (or via the vSphere remote CLI):
# esxcli software acceptance set --level=CommunitySupportedThe first command is necessary for the system to accept packages that have the acceptance level "CommunitySupported" and do not have a valid electronic signature (like the ones produced by tgz2vib5.cmd).
# esxcli software vib install -v /path/to/vib-file
The second command installs the package that needs to be locally accessible by ESXi. Alternatively you can provide a http-URL to download the vib file from a web site.
Now, let's take packaging another step further ...
Step 3: Build an Offline Bundle with vib2zip.cmd
What is an Offline Bundle? Basically it is a package containing one or multiple VIB files and additional metadata. The idea behind that is to create a depot of software packages. Before we dive deeper into this here is how you can create your own Offline bundle.
Run the vib2zip.cmd script:
 |
| VBI2ZIP 1.0 GUI |
With an Offline bundle you have two additional attributes available:
- For the KB-URL I suggest that you provide a URL of a place were you can find further information on the software package and/or can even ask questions about it. In the example I use a link to a post on the VM-Help forums.
- For Contact you might enter your own Email address if you are willing to answer questions via Email. However, like KB-URL this is optional!
So what have we got now? Like TGZ and VIB files Offline bundles can be added to an ESXi 5.0 installation ISO with my ESXi-Customizer script. Like VIB files Offline bundles can be used to install a contained software package into a running ESXi 5.0 system by using the following commands inside an ESXi shell (or via the vSphere remote CLI):
# esxcli software acceptance set --level=CommunitySupportedWith the -n option of the install command you select a single VIB package from the Offline bundle by its name attribute (net-e1001e in our example).
# esxcli software vib install -d /path/to/zip-file -n vib-name
So, what is unique to Offline bundles? You can
- import them into vCenter Update Manager (to automate the update process), and
- you can use them to create customized ESXi 5.0 installation ISO files in a way that is provided and fully supported by VMware: with the Image Builder snap-in for PowerCLI.
You can learn more about Image Builder in the VMware vSphere 5.0 online documentation.
Licensing
- The ESXi5 Community Packaging Tools are licensed under the GNU GPL version 3 (see the included file COPYING.txt).
- They are distributed with and make use of several tools that are freely available, but are partly under different licenses (see the included file tools\README.txt for details.)
- Please check the known bugs section here first to see if your issue is covered there.
- If you have trouble using the scripts then please send an email to ESXi5-CPT@v-front.de. Be sure to include the log file(s). Otherwise I might just ignore your message.
- None so far.
Changes / History
v1.0 (2012-02-12)
- first release
