vib – Page 4

Creating Custom VIBs For ESXi 5.0 & 5.1 with VIB Author Fling

09.28.2012 by William Lam // 40 Comments

VMware Labs just released a really cool new Fling called VIB Author which is a tool that allows you to easily create custom VIBs for your ESXi 5.x hosts. If you have tried to create custom ESXi firewall rules or add custom scripts to your ESXi host, you may have noticed they are not persisted after a system reboot and you had to play all sorts of games to get the files to persist. The VIB Author tool now solves that problem and you can even take your custom VIB and integrate them into an Auto Deploy Image Profile using Image Builder. Before you jump right in, be sure to read over the important note in the documentation before getting started.

So how does the VIB Author tool work?

You will need to provide two pieces of input: payload which is set of files you wish to include in your VIB and the descriptor.xml which contains the metadata for your files. From that, VIB Author can produce either a VIB and/or an offline bundle (can be used with Image Builder).

VIB Author is distributed only as an RPM and you will need to install the VIB Author tool on a 32-bit Linux system (sorry, no 64-bit support). In my home setup, I went with CentOS 6.2 i386 as it was free to download & easy to setup or you may choose go with SUSE Linux Enterprise 11 SP2 which is the recommended platform per the documentation.

To install the RPM, run the following command:

rpm -ivh vmware-esx-vib-author-5.0.0-0.0.844296.i386.rpm

In the example below, I will show you how to create a custom VIB that contains several different configurations:

Custom Firewall Rule
Custom Startup script (adds a static route)
Custom Files (ghettoVCB)

Disclaimer: The example below is not officially supported by VMware, please thoroughly test this in a development environment before using in production.

Here is the directory structure for the example that we will be going through:

Step 1 - Create your stage directory structure which we will then populate with your payload files as well as the descriptor.xml file.

mkdir -p stage/payloads/payload1

Step 2 - Create your descriptor.xml file which should be placed in the stage directory. For more details on the parameters within the descriptor.xml, please take a look at the documentation.

Here is an example of my descriptor.xml file:

<vib version="5.0">
  <type>bootbank</type>
  <name>virtuallyghetto</name>
  <version>5.0.0-0.0.1</version>
  <vendor>virtuallyGhetto</vendor>
  <summary>Custom VIB from virtuallyGhetto</summary>
  <description>Adds custom firewall rule, ghettoVCB script and static routes to ESXi host</description>
  <relationships>
    <depends>
    </depends>
    <conflicts/>
    <replaces/>
    <provides/>
    <compatibleWith/>
  </relationships>
  <software-tags>
  </software-tags>
  <system-requires>
    <maintenance-mode>false</maintenance-mode>
  </system-requires>
  <file-list>
  </file-list>
  <acceptance-level>community</acceptance-level>
  <live-install-allowed>true</live-install-allowed>
  <live-remove-allowed>true</live-remove-allowed>
  <cimom-restart>false</cimom-restart>
  <stateless-ready>true</stateless-ready>
  <overlay>false</overlay>
  <payloads>
    <payload name="payload1" type="vgz"></payload>
  </payloads>
</vib>

Step 3 - Create the directory structure and store the files you wish to include under payload1. Ensure the the directory structure matches the absolute path of how you want the files to appear on the ESXi host. For example, if you wish to create a file call foo in /etc/vmware/foo then your directory structure should look like stage/payloads/payload1/etc/vmware/foo

Note: In the documentation, there is a list of default supported paths, if you venture off of this supported list, then you will need to issue the -f flag when creating your VIB as well as installing your VIB on your ESXi host

So for our examples we have the following files:

stage/payloads/payload1/etc/vmware/firewall/virtuallyghetto.xml
This one should be pretty straight forward, we are just creating a custom ESXi firewall rule and you will need to place your configuration file under /etc/vmware/firewall, please take a look at this article for more details on creating your own firewall rules.

stage/payloads/payload1/etc/rc.local.d/999.addStaticRoute.sh
This is a custom shell script that adds a static route to an ESXi host upon bootup under /etc/rc.local.d. There maybe other startup scripts that could be executed and you do not want to conflict with any system defaults. I recommend you label yours with a high number such as 999 to ensure it is one of the last scripts to execute.

stage/payloads/payload1/opt/ghettoVCB/{ghettoVCB.conf,ghettoCB-restore.sh,ghettoVCB.sh}
This is a custom set of files that I would like to store in ESXi under /opt directory and the files are my free ghettoVCB backup script.

Here is a copy of my directory structure (stage.zip) which can be used as a reference.

Step 4 - Now we ready to create our VIB and/or offline bundle by specifying our stage directory as input. In this example, we will generate both a VIB as well as an offline bundle containing the same contents. Run the following command:

vibauthor -C -t stage -v virtuallyghetto.vib -O virtuallyghetto-offline-bundle.zip -f

Note: Since we added some files outside of the default supported paths, we also need to specify the -f flag to force the creation.

We can also extract information about our VIB by using the -i option in VIB Author, to do so, run the following command:

vibauthor -i -v virtuallyghetto.vib

Finally, we are now ready to copy the VIB over to our ESXi host and install our custom VIB.

To install VIB run the following command:

esxcli software vib install -v /vmfs/volumes/[datastore-name]/virtuallyghetto.vib -f

To install the offline bundle run the following command:

esxcli software vib install -d /vmfs/volumes/[datastore-name]/virtuallyghetto-offline-bundle.zip -f

Note: You need to specify the -f flag to force the installation since we created files in an unsupported path. I have been able to test the VIB and offline bundle installation on both ESXi 5.0 as well as ESXi 5.1

To confirm we have succesfully installed our custom VIB, we can query it by running the following command:

esxcli software vib list | grep virtuallyghetto

So there you have it, in just a few steps, you can create your own custom VIBs!

VMware officially releases vibddi for vSphere 4.1

09.18.2011 by William Lam // Leave a Comment

There were several product releases last week that got a lot of buzz on the inter-tube:

However, VMware actually released an additional product last week which snuck under the radar, vibddi.

I actually wrote about this unsupported and undocumented utility last year: How to inject custom drivers into an ESXi 4.1 image using vibddi? vibddi (pronounced vib d-d-i) stands for VIB (vSphere Installation Bundle) Disk Dump Image and it is a utility to help users easily customize ESXi images with custom drivers. This utility first appeared in the vSphere Auto Deploy appliance and it looks like VMware has finally released it as an official tool to support vSphere 4.1 image customization. You also may have heard about the new Image Builder tool with the release of vSphere 5, the origins of that utility actually came from vibddi.

If you are still using vSphere 4.1 and need to inject or modify drivers, I would highly recommend you take a look at the tool as it is extremely simple to use. For more details, please check out the new VMware KB article 2003316 documenting the details of the utility or my blog post. If you are using vSphere 5, you will need to use Image Builder as vSphere 4.1 is not supported and vice-a-versa with ESXi 5 with vibddi.

Note: There are some changes in the latest vibddi utility compared to the one found in the vSphere Auto Deploy such as injecting custom kickstart configuration file or license file. If you rely on these features, you may want to use the older version or manually update these after the system build.

How to inject custom drivers into an ESXi 4.1 image using vibddi?

11.28.2010 by William Lam // 11 Comments

Over the holiday break, I spent some time cleaning up some of the development virtual machines in our ghettoDatacenter. I came across the VMware Auto Deploy appliance that I deployed awhile back ago. I did not think I had a use for it since we already have an automated deployment system using PXE and kickstart. Auto Deploy was launched relatively recently from the VMware Flings lab. It was originally slated for release as part of vSphere 4.1 but during the transition from the BETA to RC, it was dropped and never made it into the GA release of vSphere 4.1

I decided to give the documentation one last read before deleting and to my surprise, I stumbled across an interesting gem, vibddi. vibddi (pronounced vib d-d-i) stands for VIB (vSphere Instalaltion Bundle) Disk Dump Image, which is actually a Perl utility that was created to help customize ESXi images more easily.

If you ever had a need to customize an ESXi image and inject custom drivers or configurations, you know it can be long and complex process. There are many tutorials on the internet including a recent post by Eric Sloof on injecting drivers into an ESXi installer. vibddi is meant to expedite the process and make it much simpler to inject custom drivers into an ESXi image.

****Disclaimer Since this tool is not very well documented and it is most likely not officially supported by VMware, please use test and validate the images generated prior to using in an production environment Disclaimer****

To run vibddi, you need to use sudo. Here are the available options:

[[email protected] ~]$ sudo vibddi -h
Password:

vibddi: Query and update vibs on a VMvisor dd image or device

Usage:
vibddi -h --- Print this

vibddi -i -q --- Query vibs installed on the image

vibddi -i -c --- Check bootbank filesystems on the image

vibddi -i -v [ -g ] [ -n ] --- Update the image with a single vib

vibddi -i -m -b [ -p ] [ -g ] [ -n ] --- Update the image with an online bulletin

vibddi -i -o [ -g ] [ -n ] --- Update the image with an offline bundle

vibddi -i -e [ -a ] --- Export boot modules from the image

vibddi -i -t --- Add/Remove a VMkernel option

vibddi -i -x --- Transform image to ThinESX format

vibddi -i -l --- Install a license file (vmware.lic) on the image

vibddi -d -q --- Query vibs installed on the device

vibddi -d -c --- Check bootbank filesystems on the device

vibddi -d -v [ -n ] --- Update the device with a single vib

vibddi -d -m -b [ -p ] [ -n ] --- Update the device with an online bulletin

vibddi -d -o [ -n ] --- Update the device with an offline bundle

vibddi -d -e [ -a ] --- Export boot modules from the device

vibddi -d -t --- Add/Remove a VMkernel option

vibddi -d -x --- Transform image to ThinESX format

vibddi -f -k --- Add a customized kickstart file to the ThinESX/Recovery CD ISO

Where:
VMvisor-dd - The VMvisor dd image that is going to be customized

VMvisor-dev - The VMvisor device that is going to be updated

vib-path - The local file path to the vib

metadata-URL - The URL to the metadata.zip file (Ex. http://www.oem.com/depot/metadata.zip)

bulletin-ID - The bulletin ID to install

bundle-path - The local file path to the offline bundle

proxy (OPTIONAL) - Proxy used to download vib, for update operation only

-g (OPTIONAL) - Generate customized ThinESX/Recovery CD ISOs

-n (OPTIONAL) - Bypass signature check, for update operation only

export-path - Directory to export boot modules

alternate-conf (OPTIONAL) - Alternate export configuration file

kernel-opt - VMkernel option

license-path - vmware.lic file (Format: 00000-00000-00000-00000-00000)

iso-path - The local file path to the ThinESX/Recovery CD ISO

kickstart-path - The local file path to the kickstart file

Here are a few examples of using the vibddi tool:

Mount ESXi 4.1 ISO to extract the DD image:

[[email protected] scratch]$ sudo mount -o loop VMware-VMvisor-Installer-4.1.0-260247.x86_64.iso /mnt/iso/

Unzip the DD image and extract to current directory:

[[email protected] scratch]$ sudo bunzip2 -c /mnt/iso/imagedd.bz2 > imagedd

You now should have the DD image called imagedd located in your current working directory.You can name the file anything you want, but I'm using the suggested name as noted in the Auto Deploy documentation.

To list vibs installed on the image, you'll use the following command:

sudo vibddi -i [imagedd] -q

Here is an example of the vibs installed with default installation of ESXi 4.1:

To inject the image with an offline bundle, you'll use the following command:

sudo vibddi -i [imagedd] -o [offline_bundle] -n

Note: The -n flag should be used when performing updates as it bypasses the signature checks, else you will get an error.

Here is an example of injecting the Cisco Nexus 1000 Virtual Ethernet Module offline bundle as part of the default ESXi 4.1 installation:

We can confirm the Cisco VEM is part of the default image by running the query command again:

To inject the image with a single VIB, you'll use the following command:

sudo vibddi -i [imagedd] -v [vib] -n

Here is an example injecting the Cisco Nexus 1000 Virtual Ethernet Module VIB as part of the default ESXi 4.1 installation:

To inject VMkernel boot parameters, you'll use the following command:

sudo vibddi -i [imagedd] -t [vmkernel_option]

Note: Here is a list of a few VMkernel options documented by Dave Mishchenko. The -t argument only accepts one VMkernel option at a time. If you want to updated more than one option, you will need to run the command for each VMkernel option.

With a default installation of ESXi 4.1, there are no VMkernel options defined. To see whether or not these have been defined, you will need to login to Tech Support Mode and view boot.cfg:

~ # cat bootbank/boot.cfg
kernel=b.z
kernelopt=
modules=k.z --- s.z --- c.z --- oem.tgz --- license.tgz --- m.z --- state.tgz --- vpxa.vgz --- aam.vgz
build=4.1.0-260247
updated=1
bootstate=0

Here is an example of injecting the following two VMkernel options: noACPI and nopowerManagement:

To inject a license file, you'll use the following command:

sudo vibddi -i [imagedd] -l [license_file]

Note: The license file must contain a single entry using the following format - 00000-00000-00000-00000-00000

Here is an example of injecting license file:

To inject a custom kickstart configuration, you'll use the following command:

sudo vibddi -f [esxi-iso-path] -k [kickstart_file]

Here is an example of injecting a custom kickstart file:

Note: This actually injects a custom ks.cfg into the ESXi .iso which can then be used to deploy an ESXi host including the custom configurations found in the kickstart file. A brand new .iso will be created in the current working directory which includes the timestamp of kickstart injection as part of its filename.

We now can loop mount the new .iso and verify the custom kickstart has been injected:

Note: I'm using the sample ks.cfg found on Kendrick Colemans's site.

You can also extract certain items from the DD image, you'll use the following command:

sudo vibddi -i [imagedd] -e [export-path]

Here is an example of extracting the entire DD image to a temporarily directory:

To check the bootbank filesystem, you'll use the following command:

sudo vibddi -i [imagedd] -c

Here is an example of verifying bootbank filesystem:

Once the imagedd has been updated with all the drivers, you will need to compress the image back to .bz2 using bzip2. From here, you will have two options: A) copy the modified imagedd.bz2 over to your PXE/TFTP server used for automated kickstart installation B) Create a new ESXi .iso, there are a bunch of tutorials online such as here and here.

If you need to troubleshoot or would like to view the process of vibddi, you can take a look at the logs stored in /var/log/vibddi.log. You can also see the injection process which includes both informational and debugging logs in /var/log/esxupdate.log.

As you can see, this tool is extremely useful for injecting and customizing ESXi images. Hopefully one day VMware will officially release this tool and make it available on both UNIX/Linux and Windows platform so that everyone can benefit. For now, if you want to use vibddi, you will need to download and use Auto Deploy appliance. Looks like I'll be keeping this appliance around 😉