How to build a customized ESXi installation image for your whitebox server

My ESXi-Customizer tool has come a long way... Originally built in 2011 it was a great tool for building customized VMware ESXi installation images, it was downloaded over 200k times since then and helped a lot of people who had one quest: getting ESXi installed and running on their whitebox (unsupported) hardware. This year it was even mentioned in a VMware KB article ... However, please do NOT use it anymore! Because ...

Since quite a while there is a much better way to build customized ESXi images, and that is my ESXi-Customizer-PS PowerCLI script. I'm writing this post not only to explain how easy it is to create a customized ESXi installation image for your whitebox server with this script, but also to convince the last nonbelievers that it works much better than my legacy ESXi-Customizer tool.

As usual I will back up a bit before I come to the point ;-)


So why is the VMware supplied ESXi Image not working on your white box and what can we do about it?

VMware vSphere is a product that clearly targets serious businesses that run their workloads on enterprise grade hardware, and that in turn means it lacks support for consumer grade hardware that you would use at home and in small labs.

There are two critical types of devices that need driver support in ESXi:

1. The Network Interface Card (NIC): If that is not supported then ESXi will refuse to install right away.

A while ago I already wrote a detailed post about How to get your unsupported NIC to work with ESXi 5.x and 6.0. If you are plagued by the "No Network Adapters" error then read this post. If you are lucky it will help you to find a suitable community supported driver for your NIC in the V-Front Online Depot.

2. The Hard Disk Controller: Consumer grade computer mainboards always have SATA controllers built in, and these are also available as affordable add-in cards. Most of the SATA controllers are able to implement RAID functionality (i.e. combining two or more hard disks into one volume for increased availability and/or performance), but only with the help of a suitable driver for the OS that runs on them. For Windows those drivers are generally available, but not for VMware ESXi.
Luckily you can also run SATA controllers in a generic mode called AHCI: That does not provide any RAID capabilities, but is also supported by ESXi. However, out of the box the ESXi sata-ahci driver supports only a limited set of SATA controllers, although in theory it should support any SATA controller that runs in AHCI mode.

So if ESXi is unable to detect any of your hard disks although you already have configured your SATA controller to use AHCI mode (look for related options in your computer's BIOS setup) then my sata-xahci package may help you. It persuades ESXi to use its builtin sata-ahci driver for additional devices that are originally not supported: The blog post How to make your unsupported SATA AHCI controller work with ESXi 5.x and 6.0 explains that in more detail and includes a table of devices that my sata-xahci packages adds support for. If your device is in that table then you're all set. If not then follow the instructions in the blog post to find out the PCI ID of your device and shoot me an e-mail. I will then add it to the package.


Build the ESXi image that is right for you!

Now that you have
  a) identified the NIC driver (if any) that you need and
  b) whether you need the sata-xahci package or not
the only other thing you need is VMware PowerCLI and my ESXi-Customizer-PS script. Follow these steps:

1. On your Windows machine download and install PowerCLI.
2. Download the ESXi-Customizer-PS script into a directory on your hard disk (e.g. C:\Scripts).
3. Open a PowerCLI session by using the PowerCLI shortcut on your desktop.
4. In the PowerCLI session window call my script using its full file path name and parameters added like this:

C:\Scripts\ESXi-Customizer-PS-v2.4.ps1 -v60 -vft -load net55-r8168,sata-xahci

This example would build a customized ESXi 6.0 installation ISO (use -v55 if you want to build ESXi 5.5 instead) that includes the net55-r8168 NIC driver and the sata-xahci package from the V-Front Online Depot. If you do not need a NIC driver or the sata-xahci package then just omit it. If you need another NIC driver package then just use its name instead of net55-r8168.

You can as well add any of the other useful ESXi packages that are available in the V-Front Online Depot by putting their names separated by commas after the -load switch.

All the remaining work will be done automatically by the script: With the help of the PowerCLI Imagebuilder snap-in it will download the ESXi source files from the VMware Online Depot and the additional community supported drivers from the V-Front Online Depot and will merge it all together into your customized ESXi installation ISO!


ESXi-Customizer-PS Frequently Asked Questions

1) Why is the script so much better than the legacy tool?

Well, there are a lot of reasons:

• It uses the only VMware supplied and supported method to build a customized ESXi image: PowerCLI Imagebuilder
• You don't need to have an ESXi ISO already available - Imagebuilder downloads that from the VMware Online Depot. In a lot of cases you do not even need to manually download community supported drivers - the script will get them from the V-Front Online Depot.
• The script will always build the latest available patch level of the ESXi version that you select (unless you don't want that ... see below). No need for further patching after you used the custom image to install your machine.
• It can add packages from any existing Online Depot and from local files (VIB files and Offline bundles), all together in one single run.
• The legacy tool (ESXi-Customizer) is dead. I mean really dead ... like the parrot in one of my favorite the Monty Python sketches. 

2)  How can I modify an existing ESXi image?

If you have that image only in ISO format then not at all. But if you have it in Offline bundle (zip) format then you can use that as input for the script (using the -iZip switch). Most hardware vendors (e.g. HP) supply their customized ESXi installation images in both formats, so if you want to add something to such a vendor image then just use the zip file.

If you really only have an ISO file available I could also answer with a counter question: Why do you not just rebuild that from scratch and add to it whatever you want?

3) How can I avoid the script downloading the whole ESXi system again and again when running it multiple times?

Well, we are talking about less than 400 MB of data that is downloaded from the VMware Online Depot to build an ESXi image from scratch. But when you use a metered connection that is still a lot, so this is a valid question. You can avoid repeated downloads of the ESXi sources by exporting the vanilla ESXi mage into a zip bundle, e.g. for ESXi 6.0:

C:\Scripts\ESXi-Customizer-PS-v2.4.ps1 -v60 -ozip

... and using the zip bundle as input for your further customizations, e.g.:

C:\Scripts\ESXi-Customizer-PS-v2.4.ps1 -izip ESXi-6.0.0-201xxxxxxxx-standard.zip -vft -load net55-r8168,sata-xahci

4) I don't want to build an ISO of the latest patch level, but of an older one (e.g. ESXi 5.5 Update 2). Can I do this?

Yes, in fact you can build every patch level that was ever published for ESXi versions 5.0, 5.1, 5.5 and 6.0. When you use the command line switch -sip (for Select ImageProfile) the script will pause and let you choose a specific one from all the Imageprofiles (= patch levels) that are available in the VMware Online Depot. On my ESXi Patch Tracker pages you can look up which Imageprofile corresponds to what patch level. E.g. for ESXi 5.5 Update 2 you must choose ESXi-5.5.0-20140902001-standard.

5) Can I safely use a regular VMware patch bundle to update an ESXi host that was built with a customized image?

Yes, you can. Either with VMware Update Manager (VUM) if you have that available or via the command line in an ESXi shell with esxcli software profile update. The ESXi Patch Tracker Help page provides you with detailed instructions (see section 3.).


Last words of the year ...

Do you have a question about the ESXi-Customizer-PS script that was not covered here and not on its project page (where you can also find a lot of usage examples)? Then please ask it in the comments and I will add it here.

This will be my last blog post in 2015, so I want to take this opportunity to wish you all a Merry Christmas and a happy successful new year 2016!

And remember: Save the kittens and forget about ESXi-Customizer ;-)

---

This post first appeared on the VMware Front Experience Blog and was written by Andreas Peetz. Follow him on Twitter to keep up to date with what he posts.

---

---