Portal Home > Knowledgebase > VMware Knowledge Base > Adding third-party device drivers to ESXi 4.1

Adding third-party device drivers to ESXi 4.1

Details

In some cases you might not be able to install and boot ESXi because your hardware requires device drivers that are not contained in the ESXi installation media.

To enable you to customize your ESXi 4.1 image to include drivers specific to the needs of your organization, VMware provides thevibddi image customization tool. With this tool you can create ESXi installation media that contain drivers for particular network adapters or storage devices, for example.

For drivers that you can use for customization, see the drivers listed in the Drivers & Tools section of vmware.com. Use drivers identified for 4.1 or 4.x only.

Solution

Using the vibddi Tool to Add Device Drivers to the ESXi 4.1 Image

So that ESXi can boot on systems with hardware components that require third-party drivers, you must add the drivers to an ESXi 4.1 installer ISO image. You can use the vibddi tool to add device drivers in the form of VIBs, online bulletins, or offline bundles to an ESXi 4.1 image to create a custom ISO image that contains the added drivers. This article describes the process using offline bundles.

Note: Only device drivers may be added using vibddi. Core system components cannot be modified with the vibddi tool.

Installation


Prerequisites

You must create an environment for running the image customization tool.

The tool requires a Red Hat Enterprise Linux 5-based Linux platform. You can use either a 32-bit or 64-bit distribution, but the corresponding vibddi RPM for that particular architecture must be installed.

Python 2.4 is required. You can use Python 2.5 with the 32-bit version of the tools only. For example:

DistributionPython Version
Red Hat Enterprise Linux 5.x 32 bitPython 2.4 / Python 2.5
Red Hat Enterprise Linux 5.x 64 bitPython 2.5
CentOs 5.x 32 bitPython 2.4 / Python 2.5
CentOs 5.x 64 bit
Python 2.4

 

Various versions of Python can be found on http://python.org/download/releases/ or might be available with your operating system distribution media.

The vibddi rpm has the following software package dependencies defined:

  • coreutils
  • perl
  • python
  • tar
  • gzip
  • bzip2
  • mkisofs
  • util-linux
  • openssl
  • findutils
  • sed

If these packages are not available, the rpm will not install.

Disk space considerations:

  • 305MB free space for the VMware ESXi ISO Installer
  • 210MB free space for the compressed ESXI dd image
  • 900MB free space for your uncompressed ESXi dd image
  • 305MB free space for each customized iso you want to build
  • 7.1MB free space for the vibddi tool

You must have root privileges to install and use the vibddi tool.

To install the image customization tool

  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.

    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

  2. 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

  3. 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

  4. 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/

  5. 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) >

  6. 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.

  7. 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

  8. Delete the mount point (optional)

    # rmdir /mnt

  9. 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

  10. 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) >

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

    OptionAction
    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 OptionsDescriptionAccompanying Options
    -hPrint help information
    -iThe Visor DD to be manipulatedAlways required
    -q
    Query operation-i
    -vInstall standalone VIB from file system-i
    -mMetadata URL-i -b [ -p ]
    -bBulletin ID-i -m [ -p ]
    -oInstall 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


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

     

    Based on VMware KB 2003316


Also Read

Language: