WilliamLam.com

Automating ESXi 5 Kickstart Tips & Tricks

07.13.2011 by William Lam // 58 Comments

There are some minor changes with kickstarting ESXi 5.0 but the majority of your existing ESXi 4.1 kickstart configurations can be re-used with a few modifications. One of my goals during the vSphere 5.0 beta was to automate as much of the configurations of an ESXi host as possible within the kickstart process. I also converted as many of the legacy esxcfg-* commands as I could over to the enhanced esxcli namespaces as the esxcfg-* commands will eventually be deprecated in favor of esxcli. Hopefully the tips & tricks and the example kickstart configuration file will be useful in aiding the transition to ESXi 5.0.

As usual, before diving in and creating an ESXi 5.0 kickstart configuration, make sure you spend some time going over the documentation provided by VMware, specifically the ESXi Installable and vCenter Server Setup Guide. If you would like to get a sense for what a ESXi 5.0 kickstart could look like, please jump to the bottom of this post to get a complete working example displaying the various types of configurations.

Tip #1

If you want to have your ESXi pxelinux configuration boot up to a kickstart configuration file, you have two methods of specifying this with ESXi 5.0.

The first is using the defualt installer method which specifies a new boot.cfg configuration file to contain all the boot parameters.

Here is an example of what the pxelinux default configuration file would look like:

Here is an example of what the boot.cfg looks like:

As you can see the default boot.cfg that is included in the ESXi 5.0 installer in the same directory as all the modules needed to boot up ESXi.

The second method is specifying the kickstart configuration file in the actual pxeboot file versus in a seperate boot.cfg file. This is similar to the old method of doing things, but you will have to also include all the entries that are in the boot.cfg if you decide to go down this route.

Here is an example of specifying ks.cfg in pxelinux default file:

Notice the "pxebooting ks=" stanza used to specify the ks.cfg configuration file and list of modules in boot.cfg. If you need to append additional parameters such as "IPAPPEND 1", you will need to add "+++" (three plus characters) at the very end of the module list separated with a new line for your additional entries. If you forget the "+++" symbols, you will not be able to successfully boot up the installer and an error will be thrown.

The default method of relying on the boot.cfg is the recommended approach. You can still append custom kernel parameters such as "IPAPPEND 1" which will still be in the pxelinux file, but your kickstart entry will now be part of the boot.cfg configuration file. Below is an example of the above configuration but leveraging the additional boot.cfg configuration file.

Here is an example of what the pxelinux file should look like:

As you can see, we still need to specify the "+++" to include additional parameters, but the pxelinux file is much cleaner now.

Here is an example of what the boot.cfg should look like:

As you can see, all we needed to do is append the following line "kernelopt=ks=http://172.30.0.108/esxi5/ks.cfg" which specifies the source to the kickstart configuration file.

Tip #2

This is not really a new tip, but definitely make use of the "dryrun" mode in the ks.cfg and reviewing the esxi_install.log and hostd.log for any errors. The logs will only persist upon the first reboot, if you specify a secondary reboot for whatever reason, these logs will be lost. If you would like to automate the copying of the installation logs to help debug/troubleshoot, you can copy them to a local VMFS. Here is a quick snippet that can be used (This assumes your local VMFS will have the name with the following format $(hostname -s)-local-storage-1):

cp /var/log/hostd.log "/vmfs/volumes/$(hostname -s)-local-storage-1/firstboot-hostd.log"
cp /var/log/esxi_install.log "/vmfs/volumes/$(hostname -s)-local-storage-1/firstboot-esxi_install.log"

Tip #3

VMware has once again and hopefully for the last time, changed what was known as Busybox Console, Unsupported Mode, Tech Support Mode to ESXi Shell. In doing so, the old vim-cmd to enable both local (TSM) and remote (SSH) to ESXi Shell needs to be updated.

To enable local ESXi Shell (previously known as Tech Support Mode) you will need to run the following commands to enable and start ESXi Shell.

vim-cmd hostsvc/enable_esx_shell
vim-cmd hostsvc/start_esx_shell

To enable remote ESXi Shell (previously known as TSM SSH) you will need to run the following commands to enable and start remote ESXi Shell for SSH support.

vim-cmd hostsvc/enable_ssh
vim-cmd hostsvc/start_ssh

Note: During the beta, there was actually an intermediate name for this which was known as ESX Shell but through our feedback, we had recommended ESXi Shell so that users do not confuse old classic ESX with ESXi and this may or may not change from the actual vim-cmd's

Tip #4

The --level XX that would specify when a %firstboot script would execute is no longer supported and deprecated in ESXi 5.0. By default all %firstboot script will automatically execute after all default ESXi start up scripts have finished running. The location of the %firstboot scripts are in /etc/rc.local.d/001.fireboot_001

Tip #5

You should be able leverage the new changes in esxcli to configure majority of your ESXi 5.0 hosts, the are various examples below in the example kickstart. There are still a few things that are currently not included in esxcli such as configuring NTP, host licensing, ESXi Shell, SSH, and a few others that rely on vim-cmd or some minor hacks. VMware recommends you start to get familiar with esxcli, as the old esxcfg-* will eventually be deprecated and removed in future vSphere releases and be completely replaced with esxcli.

Tip #6

You now have the ability to configure multiple syslog hosts with ESXi 5.0 but also the ability to control individual loggers such as for vmkernel, hostd, vpxa, fdm, etc. Here is an example of changing the default syslog rotation from 10 to 20 and specifying two syslog hosts:

esxcli system syslog config set --default-rotate 20 --loghost syslog1.primp-industries.com:514,syslog2.primp-industries.com:1514

Note: The new syslog facility supports tcp,udp and tcps but there is a syntax bug on how to specify normal tcp, udp and or tcps.

By default, TCP is assumed and you can specify that using the following formats:

syslog1.primp-industries.com:514
tcp://syslog1.primp-industries.com:514

To specify UDP, you will need to use the following syntax:

udp://syslog1.primp-industries.com:514

To specify TCPS, you will need to use the following syntax:

ssl://syslog1.primp-industries.com:514

To view the individual syslog types, you can run the following command:

esxcli system syslog config logger list

To update the individual syslog types, you can run the following command:

esxcli system syslog config logger set --id=fdm --rotate=20 --size=2048

Tip #7

In ESXi 4.1, to enable the SSH security banner, you had to make some minor hacks. With ESXi 5, there is not an official sshd_config and you can configure the security banner by editing /etc/issue. You can also edit the motd under /etc/motd.

Tip #8

To create custom firewall rules, take a look at the blog post here.

Tip #9

Here is post on how to create custom bootable ESXi ISO along with specifying static IP Address using kernel boot options.

Tip #10

Here is a post on how you can automate host cache configuration.

Tip #11

If you are going to SSH out of an ESXi host at any point (%post, %firstboot) ensure that you enable sshClient via the ESXi firewall else you will get a connection denied. To enable the ESXi firewall use the following command:

esxcli network firewall ruleset set --ruleset-id sshClient --enabled yes

Note: If you're doing this during %post section, hostd is not running and you will need to use "localcli" to enable the firewall which by-passes hostd.

Tip #12
Here is a post on how to Disable LUN During ESXi Installation.

Tip #13

Here is a post on Removing Previous Local Datastore Label for Reinstall in ESXi 5

Tip #14

Here is a post on How to Deploy an OVF/OVA in the ESXi Shell

Tip #15

How to persist custom firewall rules in ESXi 5, take a look at these two articles here and here

Tip #16

Here is a post on Configuring ESXi Power Management Policy Using the CLI

Tip #17

Here's an article about creating custom VIB for ESXi 5.0

Here is a complete working example of an ESXi 5.0 kickstart that can help you convert your existing ESX(i) 4.x to ESXi 5.x

# Sample kickstart for ESXi 5.1
# William Lam
# www.virtuallyghetto.com
#########################################

accepteula
install --firstdisk --overwritevmfs
rootpw vmware123
reboot

%include /tmp/networkconfig

%pre --interpreter=busybox

# extract network info from bootup
VMK_INT="vmk0"
VMK_LINE=$(localcli network ip interface ipv4 get | grep "${VMK_INT}")
IPADDR=$(echo "${VMK_LINE}" | awk '{print $2}')
NETMASK=$(echo "${VMK_LINE}" | awk '{print $3}')
GATEWAY=$(localcli network ip route ipv4 list | grep default | awk '{print $3}')
DNS="172.30.0.100,172.30.0.200"
HOSTNAME=$(nslookup "${IPADDR}" "${DNS}" | grep Address | grep "${IPADDR}" | awk '{print $4}')

echo "network --bootproto=static --addvmportgroup=false --device=vmnic0 --ip=${IPADDR} --netmask=${NETMASK} --gateway=${GATEWAY} --nameserver=${DNS} --hostname=${HOSTNAME}" > /tmp/networkconfig

%firstboot --interpreter=busybox

# enable VHV (Virtual Hardware Virtualization to run nested 64bit Guests + Hyper-V VM)
grep -i "vhv.enable" /etc/vmware/config || echo "vhv.enable = \"TRUE\"" >> /etc/vmware/config

# enable & start remote ESXi Shell  (SSH)
vim-cmd hostsvc/enable_ssh
vim-cmd hostsvc/start_ssh

# enable & start ESXi Shell (TSM)
vim-cmd hostsvc/enable_esx_shell
vim-cmd hostsvc/start_esx_shell

# supress ESXi Shell shell warning - Thanks to Duncan (http://www.yellow-bricks.com/2011/07/21/esxi-5-suppressing-the-localremote-shell-warning/)
esxcli system settings advanced set -o /UserVars/SuppressShellWarning -i 1

# ESXi Shell interactive idle time logout
esxcli system settings advanced set -o /UserVars/ESXiShellInteractiveTimeOut -i 3600

# Change the default ESXi Admins group "ESX Admins" to a custom one "Ghetto ESXI Admins" for AD
vim-cmd hostsvc/advopt/update Config.HostAgent.plugins.hostsvc.esxAdminsGroup string "Ghetto ESXi Admins"

# Users that will have full access to DCUI even if they don't have admin permssions on ESXi host
vim-cmd hostsvc/advopt/update DCUI.Access string root,william,tuan

# Block VM guest BPDU packets, global configuration
esxcli system settings advanced set -o /Net/BlockGuestBPDU -i 1

# copy SSH authorized keys & overwrite existing
wget http://air.primp-industries.com/esxi5/id_dsa.pub -O /etc/ssh/keys-root/authorized_keys

# disable SSH keys - uncomment the next section
# sed -i 's/AuthorizedKeysFile*/#AuthorizedKeysFile/g' /etc/ssh/sshd_config

# rename local datastore to something more meaningful
vim-cmd hostsvc/datastore/rename datastore1 "$(hostname -s)-local-storage-1"

# assign license
vim-cmd vimsvc/license --set AAAAA-BBBBB-CCCCC-DDDDD-EEEEE

## SATP CONFIGURATIONS ##
esxcli storage nmp satp set --satp VMW_SATP_SYMM --default-psp VMW_PSP_RR
esxcli storage nmp satp set --satp VMW_SATP_DEFAULT_AA --default-psp VMW_PSP_RR

###########################
## vSwitch configuration ##
###########################

#####################################################
# vSwitch0 : Active->vmnic0,vmnic1 Standby->vmnic2
#       failback: yes
#       faildectection: beacon
#       load balancing: portid
#       notify switches: yes
#       avg bw: 1000000 Kbps
#       peak bw: 1000000 Kbps
#       burst size: 819200 KBps
#       allow forged transmits: yes
#       allow mac change: no
#       allow promiscuous no
#       cdp status: both

# attach vmnic1,vmnic2 to vSwitch0
esxcli network vswitch standard uplink add --uplink-name vmnic1 --vswitch-name vSwitch0
esxcli network vswitch standard uplink add --uplink-name vmnic2 --vswitch-name vSwitch0

# configure portgroup
esxcli network vswitch standard portgroup add --portgroup-name VMNetwork1 --vswitch-name vSwitch0
esxcli network vswitch standard portgroup set --portgroup-name VMNetwork1 --vlan-id 100
esxcli network vswitch standard portgroup add --portgroup-name VMNetwork2 --vswitch-name vSwitch0
esxcli network vswitch standard portgroup set --portgroup-name VMNetwork2 --vlan-id 200
esxcli network vswitch standard portgroup add --portgroup-name VMNetwork3 --vswitch-name vSwitch0
esxcli network vswitch standard portgroup set --portgroup-name VMNetwork3 --vlan-id 333

# configure cdp
esxcli network vswitch standard set --cdp-status both --vswitch-name vSwitch1

### FAILOVER CONFIGURATIONS ###

# configure active and standby uplinks for vSwitch0
esxcli network vswitch standard policy failover set --active-uplinks vmnic0,vmnic1 --standby-uplinks vmnic2 --vswitch-name vSwitch0

# configure failure detection + load balancing (could have appended to previous line)
esxcli network vswitch standard policy failover set --failback yes --failure-detection beacon --load-balancing portid --notify-switches yes --vswitch-name vSwitch0

### SECURITY CONFIGURATION ###
esxcli network vswitch standard policy security set --allow-forged-transmits yes --allow-mac-change no --allow-promiscuous no --vswitch-name vSwitch0

### SHAPING CONFIGURATION ###
esxcli network vswitch standard policy shaping set --enabled yes --avg-bandwidth 100000 --peak-bandwidth 100000 --burst-size 819200 --vswitch-name vSwitch0

#####################################################
# vSwitch1 : Active->vmnic3,vmnic4 Standby->vmnic5
#       failback: no
#       faildectection: link
#       load balancing: mac
#       notify switches: no
#       allow forged transmits: no
#       allow mac change: no
#       allow promiscuous no
#       cdp status: listen
#       mtu: 9000

# add vSwitch1
esxcli network vswitch standard add --ports 256 --vswitch-name vSwitch1

# attach vmnic3,4,5 to vSwitch0
esxcli network vswitch standard uplink add --uplink-name vmnic3 --vswitch-name vSwitch1
esxcli network vswitch standard uplink add --uplink-name vmnic4 --vswitch-name vSwitch1
esxcli network vswitch standard uplink add --uplink-name vmnic5 --vswitch-name vSwitch1

# configure mtu + cdp
esxcli network vswitch standard set --mtu 9000 --cdp-status listen --vswitch-name vSwitch1

# configure portgroup
esxcli network vswitch standard portgroup add --portgroup-name NFS --vswitch-name vSwitch1
esxcli network vswitch standard portgroup add --portgroup-name FT_VMOTION --vswitch-name vSwitch1
esxcli network vswitch standard portgroup add --portgroup-name VSPHERE_REPLICATION --vswitch-name vSwitch1

### FAILOVER CONFIGURATIONS ###

# configure active and standby uplinks for vSwitch1
esxcli network vswitch standard policy failover set --active-uplinks vmnic3,vmnic4 --standby-uplinks vmnic5 --vswitch-name vSwitch1

# configure failure detection + load balancing (could have appended to previous line)
esxcli network vswitch standard policy failover set --failback no --failure-detection link --load-balancing mac --notify-switches no --vswitch-name vSwitch1

### SECURITY CONFIGURATION ###
esxcli network vswitch standard policy security set --allow-forged-transmits no --allow-mac-change no --allow-promiscuous no --vswitch-name vSwitch1

# configure vmkernel interface for NFS traffic, FT_VMOTION and VSPHERE_REPLICATION traffic
VMK0_IPADDR=$(esxcli network ip interface ipv4 get | grep vmk0 | awk '{print $2}')
VMK1_IPADDR=$(echo ${VMK0_IPADDR} | awk '{print $1".51."$3"."$4}' FS=.)
VMK2_IPADDR=10.10.0.2
VMK3_IPADDR=10.20.0.2
esxcli network ip interface add --interface-name vmk1 --mtu 9000 --portgroup-name NFS
esxcli network ip interface ipv4 set --interface-name vmk1 --ipv4 ${VMK1_IPADDR} --netmask 255.255.255.0 --type static
esxcli network ip interface add --interface-name vmk2 --mtu 9000 --portgroup-name FT_VMOTION
esxcli network ip interface ipv4 set --interface-name vmk2 --ipv4 ${VMK2_IPADDR} --netmask 255.255.255.0 --type static
esxcli network ip interface add --interface-name vmk3 --mtu 9000 --portgroup-name VSPHERE_REPLICATION
esxcli network ip interface ipv4 set --interface-name vmk3 --ipv4 ${VMK3_IPADDR} --netmask 255.255.255.0 --type static

# Configure VMkernel traffic type (Management, VMotion, faultToleranceLogging, vSphereReplication)
esxcli network ip interface tag add -i vmk2 -t Management
esxcli network ip interface tag add -i vmk2 -t VMotion
esxcli network ip interface tag add -i vmk2 -t faultToleranceLogging
esxcli network ip interface tag add -i vmk3 -t vSphereReplication

# Configure VMkernel routes
esxcli network ip route ipv4 add -n 10.20.183/24 -g 172.30.0.1
esxcli network ip route ipv4 add -n 10.20.182/24 -g 172.30.0.1

# Disable IPv6 for VMkernel interfaces
esxcli system module parameters set -m tcpip3 -p ipv6=0

### MOUNT NFS DATASTORE ###
esxcli storage nfs add --host 172.51.0.200 --share /volumes/Primp/primp-6 --volume-name himalaya-NFS-primp-6

### ADV CONFIGURATIONS ###
esxcli system settings advanced set --option /Net/TcpipHeapSize --int-value 30
esxcli system settings advanced set --option /Net/TcpipHeapMax --int-value 120
esxcli system settings advanced set --option /NFS/HeartbeatMaxFailures --int-value 10
esxcli system settings advanced set --option /NFS/HeartbeatFrequency --int-value 20
esxcli system settings advanced set --option /NFS/HeartbeatTimeout --int-value 10
esxcli system settings advanced set --option /NFS/MaxVolumes --int-value 128

### SYSLOG CONFIGURATION ###
esxcli system syslog config set --default-rotate 20 --loghost vcenter50-3.primp-industries.com:514,udp://vcenter50-3.primp-industries.com:514,ssl://vcenter50-3.primp-industries.com:1514,udp://vcenter50-3.primp-industries.com:514,udp://vcenter50-3.primp-industries.com:514,ssl://vcenter50-3.primp-industries.com:1514,ssl://vcenter50-3.primp-industries.com:1514

# change the individual syslog rotation count
esxcli system syslog config logger set --id=hostd --rotate=20 --size=2048
esxcli system syslog config logger set --id=vmkernel --rotate=20 --size=2048
esxcli system syslog config logger set --id=fdm --rotate=20
esxcli system syslog config logger set --id=vpxa --rotate=20

### NTP CONFIGURATIONS ###
cat > /etc/ntp.conf << __NTP_CONFIG__
restrict default kod nomodify notrap noquerynopeer
restrict 127.0.0.1
server 0.vmware.pool.ntp.org
server 1.vmware.pool.ntp.org
__NTP_CONFIG__
/sbin/chkconfig ntpd on

### FIREWALL CONFIGURATION ###

# enable firewall
esxcli network firewall set --default-action false --enabled yes

# services to enable by default
FIREWALL_SERVICES="syslog sshClient ntpClient updateManager httpClient netdump"
for SERVICE in ${FIREWALL_SERVICES}
do
 esxcli network firewall ruleset set --ruleset-id ${SERVICE} --enabled yes
done

# backup ESXi configuration to persist changes
/sbin/auto-backup.sh

# enter maintenance mode
esxcli system maintenanceMode set -e true

# copy %first boot script logs to persisted datastore
cp /var/log/hostd.log "/vmfs/volumes/$(hostname -s)-local-storage-1/firstboot-hostd.log"
cp /var/log/esxi_install.log "/vmfs/volumes/$(hostname -s)-local-storage-1/firstboot-esxi_install.log"

# Needed for configuration changes that could not be performed in esxcli
esxcli system shutdown reboot -d 60 -r "rebooting after host configurations"

How to Enable Support for Nested 64bit & Hyper-V VMs in vSphere 5

07.12.2011 by William Lam // 66 Comments

With the release of vSphere 5, one of the most sought out feature from VMware is the ability to run nested 64bit and Hyper-V guest virtual machines in a virtual ESXi instance. Previous to this, only 32bit virtual machines were supported as the VT-x/AMD-V Hardware Virtualization CPU instructions could not be virtualized and presented to the virtual ESX(i) guest. This feature is quite useful for home and lab setups in testing new features or studying for VMware certifications and running multiple vESX(i) instances.

You will still be required to have a 64bit capable system and CPU and you will need to be running ESXi 5.0, this will not work for ESX(i) 4.x or older.

The above diagram depicts the various levels of inception where pESXi is your physical ESXi 5.0 hosts. We then create a vESXi 5.0 host which will contain the necessary Hardware Virtualization CPU instructions to support a 64bit nested guest OS which I've created as another ESXi host called vvESXi.

Note: You will not be able to run a 4th level nested 64bit VM (I have tried by further passing the HV instructions in the nested guest) and it will just boot up and spin your CPUs for hours.

This feature by default is disabled in ESXi 5.0, to enable this virtualized HV (Hardware Virtualization) you will need to add the following string vhv.allow = "TRUE" to /etc/vmware/config of your Physical ESXi 5.0 host

Once the configuration change has been made, the feature goes into effect right away. A reboot of the system is not necessary. To verify, you should now be able to power on a 64bit guest OS and see that the HV instructions bits are being passed into the guestOS which will then allow you to run a nested 64bit guestOS. You can also verify by looking in the vmware.log file of the virtual machine and grep for the string "monitorControl.vhv" and if you see the following message, then Virtualized HV is not enabled.

In the past to run a virtual ESX(i) instance, a few advanced .vmx configuration entries were needed as documented here. With ESXi 5.0, if you are using virtual hardware version 8, then you do not need to make any additional changes. If you are using hardware version 4 or 7, then you will need to add a few changes to the VM's configuration file.

Creating vESXi 5.0 Instance using Hardware Version 8:

1. To create a virtual ESXi 5.0 instance, start off by just creating a standard RHEL5/6 64bit VM using the vSphere Client

2. Once the VM has been created, edit the settings of the VM and change over to the "Options" and now have the ability to select a new guestOS type: VMware ESXi 5.x or VMware ESXi 4.x under the "Other" section.

Note: I'm not sure why these two additional guestOS type is not available from the default creation menu, but are available after the initial VM shell is created.

3. You are now ready to install ESXi 5.0 in this new vESXi host and then you can create and power on nested 64bit guestOS within that vESXi instance as denoted from the picture below

Creating vESXi 5.0 Instance using Hardware Version 4/7:
1. To create a virtual ESXi 5.0 instance, start off by just creating a standard RHEL5/6 64bit VM using the vSphere Client

2. Now you will need to add the following advanced .vmx parameter: monitor.virtual_exec = "hardware" which can be done through the vSphere Client and/or editing the .vmx parameter manually.

3. Next you will need to add some cpuid bits, depending if you are running an Intel or AMD CPU, the respective entries are required:

Intel Hosts:

cpuid.1.ecx = "----:----:----:----:----:----:--h-:----"

AMD Hosts:

cpuid.80000001.ecx.amd = "----:----:----:----:----:----:----:-h--"
cpuid.8000000a.eax.amd = "hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh"
cpuid.8000000a.ebx.amd = "hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh"
cpuid.8000000a.edx.amd = "hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh"

4. You are now ready to install ESXi 5.0 in this new vESXi host and then you can create and power on nested 64bit guestOS within that vESXi instance

By using a VM that is hardware version 8, you can easily automate the creation of vESXi 5.0 instance by changing the guestOS string in the .vmx parameter to "vmkernel" and the above configurations other than "vhv" string needed for either an Intel or AMD system are automatically configured.

For proper networking connectivity, also ensure that either your standard vSwitch or Distributed Virtual Switch has both promiscuous mode and forged transmit enabled either globally on the portgroup or distributed portgroup your nested ESXi hosts are connected to.

Creating a vHyper-V Instance on physical ESXi 5.0:
1. To create a virtual Hyper-V instance, start off by creating a Windows 2008 Server R2 64bit VM using the vSphere Client

2. If you are using Hardware Version 7, you will need to follow the instructions in "Creating vESXi 5.0 Instance using Hardware Version 4/7" to add the additional parameters to the VM. If you are using Hardware Version 8, you just need to change the guestOS type to VMware ESXi 5.0

3. You need to add one additional .vmx parameter which tells the underlying guestOS (Hyper-V) that it is not running as a virtual guest which in fact it really is. The parameter is hypervisor.cpuid.v0 = FALSE

4. You are now ready to install Hyper-V in a virtual machine and you can also spin up nested 64bit guestOSes in this virtual Hyper-V instance.

As you can see, now you can even run Hyper-Crap, err I mean Hyper-V as a virtualized guest under ESXi 5.0. I did not get a chance to try out Xen, but I'm sure with the ability to virtualize the Hardware Virtualization instructions, you should be able to run other types of hypervisors for testing purposes.

This is a really awesome feature but note that this is not officially supported by VMware, use at your own risk.

The Dreaded fault.RestrictedVersion.summary Error

06.28.2011 by William Lam // 9 Comments

The question about the fault.RestrictedVersion.summary error message comes up pretty often on the VMTN community forums, specifically for new users of VMware vSphere. This particular error message is usually generated when trying to use one of the VMware SDK toolkits such as the vCLI, PowerCLI, VI Java, etc. or directly interfacing with the vSphere API for automation. The reason for this error message is due to the use of the free vSphere Hypervisor license (formally known as free ESXi).

Here is an example of the error trying to use vCLI to put an ESXi host into maintenance mode:

Here is an example of the error trying to use PowerCLI to power on a virtual machine:

Though the message is not easy to decipher for new users, it is a VMware license restriction placed on the vSphere Hypervisor license edition. Users only have the ability to perform read-only operations against the vSphere API which includes all the vSphere toolkits/management tools such as the vCLI, vMA, PowerCLI, VI Java, etc. Any operations that requires the change of state such as powering on a virtual machine or putting an ESXi host into maintenance mode is considered a write operation and is NOT allowed using the vSphere Hypervisor license type. When using the vSphere Client to manage an ESXi host, users have complete read and write access to these types of operations, they just can not be automated using the vSphere APIs or the various SDKs.

I personally think the error message should be updated to be a bit more clear and state that this particular license type (free ESXi) does not allow for any changes using the APIs. There is a small VMware KB article regarding the configuration of Jumbo Frames using the vCLI, but as you can see this error is not just applicable to vCLI but across the vSphere API/toolkits.

Now there are three types of licenses I consider an ESXi host can be configured and we'll walk through each of them. In the following example, I will be using the vSphere SDK for Perl script licenseManagement.pl to demonstrate the various license types which is allowed since it is only querying the license information which is a read operation to the APIs.

1. Evaluation License - When you first install vSphere Hypervisor (free ESXi) and before applying your free license key, the host is automatically configured to be in this mode. In the evaluation state (60 days), you are basically licensed with ALL features just as if you have paid for the highest license type which is Enterprise Plus. You have full read and write access to the vSphere API and all the various vSphere toolkits for 60 days as part of the eval, once the 60 days are up, you will be configured just like the free version of ESXi.

Here is an example of querying the license information for an evaluation ESXi host:

If we take a look at the License section using the vSphere Client, we'll see all the features included with this particular license type:

2. Free License - This is the free license that is provided from VMware once you have registered and downloaded vSphere Hypervisor (free ESXi)

Here is an example of querying the license information on a free ESXi host:

Notice the editionKey which is the first column and the name of the license in the second column which is "vSphere 4 Hypervisor" which represents the use of the free edition/license of ESXi. Both of these string text can also be used in conjunction to determine programmatically that you are running the free edition of ESXi.

If we take a look at the vSphere Client we also notice the list of features is quite small compared to the evaluation version:

3. All other licenses - This is all other vSphere edition license available which includes Essentials, Essentials Plus, Standard, Advanced, Enterprise and Enterprise Plus. For more details about the various license editions, please take a look a the vSphere Edition Comparison chart.

There is not a specific license feature that allows for the read and write access to the vSphere API and toolkits but by using any of the paid editions, you automatically have complete full read and write access to the vSphere APIs and the various vSphere toolkits.

Here is an example of querying the licensing information on a host with Enterprise Plus license type:

Here is an example of the features available via the vSphere Client:

So now you can easily check the vSphere edition you are running to determine whether or not you have the ability to use some of the awesome vSphere toolkits and management tools to automate your vSphere infrastructure which I highly recommend you do.