The Complete Guide to ESXCLI Installation and VIB

A great number of responsibilities belong to vSphere administrators in a datacenter team as the hosts are one of the foundation stones for all the other systems. They need to ensure that they are working according to the baselines and provide the best possible SLA. Enforcing a supported configuration and up to date infrastructure comes with the task of managing drivers, patches and software extensions on the hosts.

Running hosts with outdated or unsupported Firmware and Driver combinations can lead to incredibly unstable systems which in turn will cause all sorts of headaches like PSOD, IO devices disconnecting randomly, you name it… Ensuring supported and up to date packages is actually the first step VMware support engineers take when responding to a Support Request (SR).

In this blog, we will describe what these packages look like for vSphere hosts and how to interact with them. We will also demonstrate how to install and update packages, where to find them, how to know which one to use…

vSphere Installation Bundle

VIB is a term that comes up quite a lot in the VMware world, but what is it exactly?

A “vSphere Installation Bundle” is a package, or archive, that contains the necessary files to install the payload on a vSphere host. It is comparable to an RPM for Red-Hat systems or even an APK for Android. Its purpose is to simplify the distribution and installation of drivers, patches and third-party extension modules. It is not to be confused with a Patch which is a collection of VIBs.

vSphere Installation Bundles don’t necessarily come from VMware. Third-Party companies propose their own packages to extend the capabilities of vSphere in order to support their own solution or optimize the interactions between them.

A VIB is made up of 3 different components:

• File Archive: Contains the actual files to be installed on the system (driver, patch or extension). It has no extension.
• Descriptor file (descriptor.xml): Contains metadata information about the package like dependencies, requirements, compatibility, whether or not maintenance mode or reboot is required…
• Signature file (sig.pkcs7): Specifies the acceptance level of the package. The acceptance level is set at the host level and shows the amount of certification of that VIB by VMware (VMwareCertified, VMwareAccepted, PartnerSupported, CommunitySupported).

Below is a screenshot of a VIB file for a 10Gbps network card driver (ixgben) where you can see the 3 files.

Software depot and Image profiles

Although it is not directly related to what we are doing, I think it will be useful to cover these 2 terms to better understand the overall concept and what’s to come in the next chapters.

As we mentioned previously, a VIB is a small file that contains one driver or a piece of software to expand ESXi’s capabilities, which makes it the smaller entity.

Image profiles

An image profile is an ESXi image that contains a collection of VIBs. PowerCLI includes “image builder” cmdlets to create your own ISO with specific VIBs. Image profiles are usually used by vendors to distribute custom or OEM ISOs of ESXi including the correct and supported drivers for the hardware installed in their servers.

Software depots

A software depot is simply a location where VIBs and image profiles are stored and hierarchically organized, just like a Red Hat repository that contains all sorts of RPM files. They come in 2 different forms:

• Online: Accessible with an HTTP URL that can be public or internal. The main VMware depots are preconfigured in vSphere Update Manager but the largest tech vendors also offer public depots that contain their certified drivers and extensions.
• Offline: ZIP files that can be imported in VUM or installed in one batch on a host. Once the depot is added in VUM, you can pick some or all of the packages that are in it to create a baseline. If you install a depot using ESXCLI you will install all the packages in it.

Where to get them

Drivers

You will quickly realize that there are many tools for the same job. In this blog, we won’t get into the dirty details of which version of a driver to use as this could be the topic of a blog in itself.

The rule of thumb, however, is to always install a driver version that is in the VMware HCL (Hardware Compatibility List). Just like with a Windows OS, those depend on the hardware, the major version of the OS and the firmware version in use. Sometimes you will not want to install the latest version of the driver on purpose because it has been found to be the cause of issues. Sometimes you won’t even get any support from VMware until you have updated your firmware and drivers as it is the first thing they check.

You can find the driver files on the website of the vendor (Intel, Broadcom…) where you will usually find the “Async” drivers (developed by the vendor, e.g. ixgbe).

The other way (recommended) to get drivers is to use the HCL. Just find your hardware, select the version of ESXi and click the “+” sign to reveal a link where you can download the file. There you will retrieve the “Native” driver (developed by VMware, e.g. ixgben).

ESXi Patches

Most of the time the patches are downloaded by vSphere Update Manager (VUM) or Update Download Manager Service (UMDS) in some instances. However, in this blog we focus on ESXCLI so we need to be able to download the patches manually. Note that some administrators might need to retrieve them manually if vCenter is isolated from the internet and there is no possibility to get a proxy access to a UMDS server.

Select ESXI in the product field and choose the correct version. From the list that is displayed, you can download one or more patches.

Extensions

This type of packages is delivered in a variety of ways, all of which are specific to the product it serves. For example, the VIBs for NSX are stored in the NSX manager appliance and are normally installed transparently as part of the deployment process.

Other extensions from third-party vendors require that you download them from their website. A few examples are PernixData (a company later bought by Nutanix) who offered a VIB that would give the possibility to use SSD drives as a cache tier to accelerate the performances of traditional storage, or storage providers like EMC’s PowerPath module that extends the multi-pathing possibilities of vSphere to work more efficiently with their SAN boxes.

ESXCLI, what and how

Now that we have described what we are trying to install, let’s have a look at the command we are going to use to install it.

ESXCLI is a command set that provides the ability to manage and troubleshoot a great number of aspects of ESXi. It is not to be confused with localcli which is reserved for use with the technical support when hostd is unavailable, and shouldn’t be used if not required to by VMware.

It can be used in the ESXi shell, in an SSH session, in vCLI and even in PowerCLI which many people aren’t aware of. In this blog, we will demonstrate the former and latter.

How to install a driver with ESXCLI

ESXi drivers are usually a single VIB to install, as opposed to vSphere patches that contain many of them. In this example, I used a random driver of the brand “Areca” (which I’d never heard of) that I found on the HCL.

The bundle that you download will be in the zip format. The files that you can use to install the driver are inside that zip file. There you will find another zip file called a software depot (described previously) that can theoretically contain several VIBs and you will also find the VIB file itself that only contains the driver.

Once the driver is downloaded, copy it to the host using WinSCP or upload it to a datastore. In this example, I did the former and placed it in /tmp.

SSH / shell

List the installed VIBs

Let’s start by listing the VIBs installed on the system. The list gives us the name, version, vendor, acceptance level and the install date.

Esxcli software vib list

Install the package with a depot file (-d parameter)

Here we install the driver using the software depot that comes as a ZIP file. You can use the name (–depot) or the short parameter (-d).

Esxcli software vib install –d /tmp/arcmsr-1.40.00.09-offline_bundle-10120452.zip

OR

Esxcli software vib install –-depot=/tmp/arcmsr-1.40.00.09-offline_bundle-10120452.zip

As you can see this driver installation requires a reboot. After the reboot, we can check that the package is installed. Note that if an older version was already installed it would be removed and replaced by the new one.

Install the package with a VIB file (-v parameter)

We can also use the VIB file directly for the same result. You can use the name (–viburl) or the short parameter (-v).

esxcli software vib install -v /tmp/scsi-arcmsr-1.40.00.09-1OEM.550.0.0.1331820.x86_64.vib

OR

esxcli software vib install –viburl=/tmp/scsi-arcmsr-1.40.00.09-1OEM.550.0.0.1331820.x86_64.vib

Remove a package

Note that you can uninstall a vib if you need to.

esxcli software vib remove -n scsi-arcmsr

OR

esxcli software vib remove –vibname=scsi-arcmsr

PowerCLI

We can use esxcli in PowerCLI with the Get-ESXCLI cmdlet. It works exactly the same way as the one in the shell, except it has to be written “the PowerShell” way. The results will be exactly the same as it was in the SSH or shell session. The advantage of this method is that it can be easily scripted and ran quickly against several hosts without fiddling with SSH sessions.

Learn more about PowerCLI with our eBook “The Aspiring Automator’s Guide”.

List the installed VIBs

As you can see the output matches the one in the shell. Note that I added “| Format-Table” to make it look similar.

(get-esxcli -VMHost “192.168.174.131” -V2).software.vib.list.invoke()

Install the package with the depot file (-d parameter)

The command’s parameters must be a collection of objects using the named parameters. They are passed as the property of the “Invoke()” method.

(get-esxcli -VMHost “192.168.174.131” -V2).software.vib.install.invoke(@{depot=”/tmp/arcmsr-1.40.00.09-offline_bundle-10120452.zip“})

Install the package with a VIB file (-v parameter)

(get-esxcli -VMHost “192.168.174.131” -V2).software.vib.install.invoke(@{viburl=”/tmp/scsi-arcmsr-1.40.00.09-1OEM.550.0.0.1331820.x86_64.vib“})

Remove a package

(get-esxcli -VMHost “192.168.174.131” -V2).software.vib.remove.invoke(@{vibname=”scsi-arcmsr“})

How to install host patches with ESXCLI

Host patches are usually installed in vSphere Update Manager but it is possible to do it manually using ESXCLI. In this example, my test ESXi host was running vSphere 6.7 Update 3 on the build 14320388. I downloaded a patch with a fair amount of bulletins in it as shown earlier.

In the earlier example, I copied the driver files to the /tmp folder using WinSCP. In this one, I stored the zip file of the ESXi patch on a datastore named “test” to make it a little different.

We use the same command to install the patch with the “–d” parameter for “depot”. Notice how the output is far more generous as this depot includes a lot of vibs. Unlike the driver’s that only contained one. I won’t do it with PowerCLI as I think you got the drill from the driver demonstration.

Esxcli software vib install –d /vmfs/volumes/test/ESXi670-201912001.zip

The host should now display the build associated with the patch you downloaded and installed. Here we can see that it changed from 14320388 to 15160138.

Summary

vSphere’s versatility provides several ways to do things and each serves a specific use case. Although administrators will make the choice of using vSphere Update Manager most of the time, ESXCLI comes in handy in many situations like troubleshooting or when vCenter is unavailable. It is important to understand how it works and what can be done with it.

Do you often use ESXCLI? What are usually the use cases for it? Let us know in the comment section.