Knowledgebase

1. Determine the particulars of your platform.

   1. To determine what version of Red Hat-based operating system you are using, view the /etc/issue or/etc/redhat-release file.

      For example:
      
      # cat /etc/issue CentOS release 5.5 (Final) Kernel \r on an \m
      # cat /etc/redhat-release CentOS release 5.5 (Final)

   2. To determine if your OS is 32 bit or 64 bit, from the command line type the following command:

      uname –a or uname –m

      On a 32-bit Red Hat Enterprise Linux-based operating system, the output will be similar to the following example:

      uname -a
      Linux server 2.6.18-194.el5 #1 SMP Fri Apr 2 14:58:35 EDT 2010 i686 athlon i386 GNU/Linux
      uname -m
      i686

      On a 64-bit Red Hat Enterprise Linux-based operating system, the output will be similar to the following example:

      # uname -a
      Linux server 2.6.18-194.el5 #1 SMP Fri Apr 2 14:58:14 EDT 2010 x86_64 x86_64 x86_64 GNU/Linux
      #uname -m
      x86_64

2. Download the image customization tool appropriate for your architecture.

   1. On the VMware Web site, go to the Drivers & Tools tab on the Download VMware vSphere 4 page athttp://downloads.vmware.com/d/info/datacenter_cloud_infrastructure/vmware_vsphere/4_1#drivers_tools.

   2. Locate the vibddi tool for ESXi 4.1 and click Download.

3. As the root user, install the VMware vibddi tool.

   # rpm -ivh vmware-esx-vibddi-.i386.rpm

   In addition to installing the vibddi software, this command creates the /opt/vmware/vibddi/iso directory. You use this directory to store the customized ISO images that are created using the tool.

4. Verify that the rpm is installed with the command rpm –qa.

   For example:
   
   # rpm -qa | grep vibddi vmware-esx-vibddi-4.1.0-2.7.00000
   

Image Creation

With the tool installed, you can start creating customized ESXi images.

Prerequisites

The vibddi tool requires that you have an ESXi 4.1 ISO image available. This image provides the base content from which the customized image will be built.

Ensure that your shell path variable includes the /usr/sbin and /sbin directories.

If you plan to copy the customized ESXi image to a storage device to boot from, that storage device must have a minimum capacity of 1GB (1024MB).

To add device drivers with the image customization tool

1. In a temporary working directory, for instance /mnt, create a loopback mount of the ESXi ISO installer so that you can extract the compressed ESXi boot image.

2. 1. If a /mnt directory does not exist, create the /mnt directory:

      # mkdir /mnt

   2. To mount an ISO using the loop device method with the destination mount point set to /mnt, use the following command.

      # mount -o loop /opt/vmware/vibddi/iso/ /mnt

3. To confirm the ISO image is mounted issue the following command.

   # df -h /mnt
   Filesystem Size Used Avail Use% Mounted on
   /opt/vmware/vibddi/iso/VMware-VMvisor-Installer-4.1.0-348481.x86_64.iso
   305M 305M 0 100% /mnt

4. Extract the compressed ESXi boot image and uncompress it, rename the file appropriately, and unmount the loopback mount point, which is no longer needed.

   1. Copy the compressed ESXi dd image to a suitable location, for example, /mylocation.

      # cp /mnt/imagedd.bz2 /mylocation/

   2. Extract the ESXi DD image.

      # /usr/bin/bunzip2 /mylocation/imagedd.bz2

   3. Rename the imagedd file for convience.

      # mv /mylocation/imagedd /mylocation/

   4. Unmount the ISO from the loop device.

      # umount /mnt

   5. [Optional] Delete the mount point.

      # rmdir /mnt

      For example:
      # cp /mnt/imagedd.bz2 /mylocation/
      # bunzip2 /mylocation/imagedd.bz2
      # mv /mylocation/imagedd /mylocation/VMware-VMvisor-4.1.0-348481.x86_64.dd
      # umount /mnt

5. Verify your path variables

   1. Determine your shell.

      # echo $SHELL
      /bin/bash

      For example, if you use the bash shell from the output of $SHELL:
      echo $PATH
      /usr/kerberos/sbin:/usr/kerberos/bin:/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/root/bin

   2. If necessary, add /sbin and /usr/sbin to the path.

      For example:
      export PATH=$PATH:/sbin:/usr/sbin/

6. Query the ESXi image.

   # vibddi -i –q

   Using vibddi, you can view the contents of the ESXi image by using the -q (query) option. By default, the image includes the ESXi firmware and the VMware Tools ISO images. The remaining entries in the list of contents define API version levels for various system components.

   For example:
   # vibddi -i VMware-VMvisor-4.1.0-260247.x86_64.dd -q
   
   < vmware-esx-firmware (4.1.0-0.0.260247) >
   < CMPI-1.0 >
   < VMW_CMPI_CPP-1.0.5 >
   < vmkapi_1_1_0_0 >
   < vmknexus1kvapi-0-0 >
   < vmkepsecapi_1.0.0.0 >
   < DriverAPI-9.0 >
   < DriverAPI-9.1 >
   < vmware-esx-tools-light (4.1.0-0.0.260247) >

7. Download the ISO image for the device driver you want to add from the Drivers & Tools tab at the VMware download site, Alternatively, you can obtain a driver ISO from the device vendor.
   

8. Extract the offline bundle ZIP files by using a loopback mount. In your working directory, run the following commands:

   # mkdir /mnt
   # mount -o loop /mnt/
   # cp /mnt/offline-bundle/*.zip /mylocation/
   # umount /mnt

9. Delete the mount point (optional)

   # rmdir /mnt

10. Install packages from an offline bundle to the ESXi image and generate new installation media (ISO).

    # vibddi –i –o -g

    The vibddi command performs an in-place update of the ESXi dd image in the working directory and adds the contents of the offline bundle. The command also creates a new ESXi installation media ISO file in the/opt/vmware/vibddi/iso/custom directory that includes the offline bundle content. You can use these files to create a bootable storage device and DVD installation media.

    Note: To insert multiple drivers, repeat this command for each offline bundle that contains a driver you want.

    The following example shows the command and output for installing the Intel IGB driver

    # vibddi -i VMware-VMvisor-4.1.0-260247.x86_64.dd -o INT-intel-lad-ddk-igb-3.0.18-offline_bundle-396986.zip –g
    
    Setting up configuration for esxupdate
    This may take a few seconds...
    Checking bootbank filesystems (pre-install)
    Installing offline bundle: /vibddi/INT-intel-lad-ddk-igb-3.0.18-offline_bundle-396986.zip
    Update operation completed successfully
    Checking bootbank filesystems (post-install)
    Generating customized ISO: /opt/vmware/vibddi/iso/VMware-VMvisor-Installer-4.1.0-260247.x86_64.iso
    This may take a few minutes...
    Generated new ISO: /opt/vmware/vibddi/iso/custom/VMware-VMvisor-Installer-4.1.0-260247.iso

11. Run a query to confirm that the driver is in place.

    # vibddi -i

    In this example, the Intel IGB driver installed in step 10 appears as a new entry. Compare with the query result in step 6.

    #vibddi -i VMware-VMvisor-4.1.0-260247.x86_64.dd –q
    
    < vmware-esx-drivers-net-igb (400.2.4.10-1vmw.2.17.249663) >
    < vmware-esx-firmware (4.1.0-0.0.260247) >
    < CMPI-1.0 >
    < VMW_CMPI_CPP-1.0.5 >
    < vmkapi_1_1_0_0 >
    < vmknexus1kvapi-0-0 >
    < vmkepsecapi_1.0.0.0 >
    < DriverAPI-9.0 >
    < DriverAPI-9.1 >
    < vmware-esx-tools-light (4.1.0-0.0.260247) >

12. Create an installation DVD or bootable storage device from the ESXi image.

    Option	Action
    Create an installation DVD from the ESXi image	Write a DVD using the new  installation media located in the /opt/vmware/vibddi/iso/custom directory.
    Copy the ESXi image to a storage device to boot from	Write the DD image directly to a storage device and boot from it. # dd if= of=/dev/sdX bs=1M X is the letter to which the device is registered. The following is an example using dd to write the image to a USB device. # dd if=VMware-VMvisor-4.1.0-260247.x86_64.dd of=/dev/sdb bs=1M You can now boot your host from that storage device. For more information, see Determining a storage device to which to copy a 4.1 ESXi dd image (2005727).

    vibddi CLI

    The table lists the options available in vibddi.
     

    vibddi Options	Description	Accompanying Options
    -h	Print help information
    -i	The Visor DD to be manipulated	Always required
    -q	Query operation	-i
    -v	Install standalone VIB from file system	-i
    -m	Metadata URL	-i -b [ -p ]
    -b	Bulletin ID	-i -m [ -p ]
    -o	Install offline bundle from file system	-i
    -p	(Optional) Proxy server	-i -b -m
    -g	(Optional) Generate ThinESX CD ISOs for installing ESXi Installable to a hard drive rather than installing ESXi Embedded on a USB device	-i < -v | -o | -b -m [ -p ] >

     

    Common Issues and Troubleshooting Tips

    Tool for Device Drivers Only

    The tool is limited to customizing images with device drivers ( vmware-esx-drivers). The following VIBs cannot be used for customization:

    • vmware-esx-firmware
    • vmware-esx-tools-light
    • vmware-esx-viclient

    Location of Debug and Error Messages

    When running the vibddi tool, console output is a subset of the available information. All debug and error messages are stored in the following files:

    • /var/log/vibddi.log
    • /var/log/esxupdate.log

    Bootbank Error

    Issue

    The following error message is printed when running a vibddi operation:

    Create directory failed: /bootbank

    Solution

    Run the mount command to ensure no image partitions are mounted, and umount partitions if they are. Delete any directory from the following set that still exist:
    • /bootbank
    • /altbootbank
    • /locker

    vibddi Error Codes

    
    

    Code	vibddi Error
    0	Operation completed successfully
    1	Not invoked as root user
    2	Invalid arguments
    3	Unable to obtain lock file
    4	Invalid ESXi 4 target
    5	Dependency missing
    6	File not found
    7	File copy failed
    8	File chmod failed
    9	Read pipe failed
    10	Read file failed
    11	Write file failed
    12	Create directory failed
    13	No free loop device found
    14	Mount failed
    15	Bad data returned from fdisk command
    16	Data missing in configuration
    17	esxupdate operation failed
    18	ddfsck operation failed
    19	ThinESX/Recovery CD customization failed
    20	Invalid bootloader configuration
    21	Umount failed
    22	Executing external command failed

     

    Based on VMware KB 2003316