Installing and upgrading the latest version of VMware Tools on existing hosts

Products

VMware vSphere ESXi

Issue/Introduction

While VMware Tools ISO images on ESXi hosts are typically managed via the VMware ESXi installer, vSphere Update Manager (VUM), or vSphere Lifecycle Manager (vLCM), they can also be installed and updated manually.

For more information about upgrading VMware Tools using vSphere Lifecycle Manager on vSphere 7.0, see Upgrade the VMware Tools Version of Virtual Machines

This article provides:

Manual steps to install or upgrade to the latest version of VMware Tools ISO image files for existing VMware ESXi Hosts.
Manual steps to complete the install or upgrade without rebooting the VMware ESXi hosts.

This article also helps in resolving the errors or issues:

The required VMware Tools ISO image does not exist or is inaccessible. Vix 21001
VMware Tools reported as “up to date” after updating the VMware ESXi hosts VMware Tools ISO image files to a newer version.

Environment

VMware ESX 9.x
VMware ESXi 8.x
VMware ESXi 7.x

Resolution

Understanding ProductLocker

The VMware ESXi installer, vSphere Update Manager (VUM), and vSphere Lifecycle Manager (vLCM) manage VMware Tools ISO image files in the default /locker/packages/vmtoolsRepo partition. It is strongly advised against manually updating the contents of this default repository. Doing so can cause conflicts with automated lifecycle management operations. This article focuses on placing the productlocker on a different location.

The /productLocker symbolic link determines the active VMware Tools repository. Its target is controlled by the UserVars.ProductLockerLocation advanced setting, found in:

ESXi Host Web UI: Host > Manage > Advanced Settings
vCenter Web UI: Host > Configure > Advanced System Settings (search for UserVars.ProductLockerLocation)

By default /productLocker points to /locker/packages/vmtoolsRepo. However, when a ramdisk cache is in use, /productLocker may point to /tools.

To show the the current ProductLocker location from and ESXi shell or SSH session:

# ls -l /productLocker
# readlink /productLocker

Installing or updating VMware Tools repository on a datastore

These steps should be used when the VMware Tools repository is (or will be) located on a datastore.
ProductLocker should be configured before powering on VMs on the host. Installing or upgrading VMware Tools might fail for VMs powered on before configuring ProductLocker. For more information, see Installing or upgrading VMware Tools might fail for VMs powered on before configuring ProductLocker (2147383).

When installing VMware Tools repository on a datastore for the first time, you first need to create a directory to use as the root of the repository.
The datastore location for the repository and the directory must be only for use as the VMware Tools ISO images repository (i.e.: not a Virtual Machine folder or home)

1. Create the VMware Tools repository on the datastore, and adjust the permissions:

# mkdir /vmfs/volumes/<datastore-name-or-volume-id>/<vmtools-repository-name>
# chmod 700 /vmfs/volumes/<datastore-name-or-volume-id>/<vmtools-repository-name>

2. If the VMware Tools repository has content, it is recommended to empty it rather than overwriting existing files.

# rm -rf /vmfs/volumes/<datastore-name-or-volume-id>/<vmtools-repository-name>/*

3. Download and extract the VMware Tools packages from Broadcom Support

Note: VMware Tools packages on Broadcom Support contain metadata files and signatures along with ISO images files must be completely extracted without missing files. Missing files during extraction might lead to unexpected errors during VMware Tools install, upgrade, and version status reporting.

4. Update the VMware Tools repository content (pick one of):

Option 1

Copy the “vmtools” and “floppies” sub-directories from the extracted directory to the VMware Tools repository.

# cp -r /path-to-package-extracted-dir/vmtools /vmfs/volumes/<datastore-name-or-volume-id>/vmtools-repository-name>/
# cp -r /path-to-package-extracted-dir/floppies /vmfs/volumes/<datastore-name-or-volume-id>/vmtools-repository-name>/

Option 2

Selectively update the VMware Tools ISO images files. To provide VMware Tools to Windows VMs take the following files from the (latest) VMware-Tools-windows zip and put them into the respective folders "vmtools" and "floppies":

vmtools/isoimages_manifest.txt
vmtools/isoimages_manifest.txt.sig
vmtools/windows.iso
vmtools/windows.iso.sha
vmtools/windows.iso.sig
vmtools/windows_avr_manifest.txt
vmtools/windows_avr_manifest.txt.sig
floppies/pvscsi-Windows8.flp
floppies/pvscsi-Windows2008.flp
floppies/pvscsi-WindowsVista.flp

Option 3

If you want to provide VMware Tools for legacy Linux guest operating systems as well, additionally take the following files from the (latest) VMware-Tools-core zip and put them into the "vmtools" folder.

vmtools/linux.iso
vmtools/linux.iso.sha
vmtools/linux.iso.sig
vmtools/linux_avr_manifest.txt
vmtools/linux_avr_manifest.txt.sig

4. Set the required permissions for the files:

# chmod -R 700 /vmfs/volumes/<datastore-name-or-volume-id>/vmtools-repository-name>/*

Note: All steps here-on (step 5 and following) are for first-time setup of the vmtools repository on a shared datastore or when the location of the vmtools repository changes.

5. Configure ProductLocker to use the new VMware Tools ISO images repository location. To update the UserVars.ProductLockerLocation setting to the VMware Tools ISO images repository location using a method below.

From ESXi shell:

# esxcli system settings advanced set -o /UserVars/ProductLockerLocation -s  /vmfs/volumes/<datastore-name-or-volume-id>/vmtools-repository-name>

ESXi Host Web UI:

Host > Manage > Advanced Settings

vCenter Web UI:

Host > Configure > Advanced System Settings (search for UserVars.ProductLockerLocation)

6. Update the ProductLocker symbolic link (/productLocker) with of the following methods

Reboot the VMware ESXi host,
or
Follow the reboot-less procedure below “Updating the ProductLocker symbolic link without rebooting the VMware ESXi hosts” section below that matches the VMware ESXi Host version.

Note: Using this approach is not recommended for ESXi hosts that are provisioned using Auto Deploy. For more information on configuring host profile for hosts provisioned with Auto Deploy, see VMware Tools for hosts provisioned with Auto Deploy (2004018).

Updating the ProductLocker symbolic link without rebooting the VMware ESXi hosts

1. Invoking updateProductLockerLocation vSphere API with /vmfs/volumes/<datastore-name-or-volume-id>/vmtools-repository-name> as the argument, updates the /productLocker symlink
  
  Log into the vCenter MOB at https://vcenter_fqdn/mob . Login with the [email protected] account, then browse to [content > rootFolder > childEntity > hostFolder]. Follow the path under childEntity until you arrive at the host.
2. Open the updateProductLockerLocation method.
3. Click on "Invoke Method" to apply the setting:

Alternatively you can open the API directly using the Host ID. For this, select the host in vSphere Client. The URL will include the ID as shown in the picture below:

Use this ID to open the following URL:
https://vcenter_fqdn/mob/?moid=<ID>&method=updateProductLockerLocation

In the example this would be:
https://vcenter_fqdn/mob/?moid=host-18022&method=updateProductLockerLocation

Click on "Invoke Method" to apply the setting:

Additional Information

After rebooting the VMware ESXi host, the productLocker location is not added to the security policies for the VMs.

Following VMware ESXi host reboot, the entry for the productLocker in the VMware ESXi security policies will be updated to the new path. This update can fail if the datastore becomes accessible later than expected in the VMware ESXi host boot process. As a result, VMs security policies do not have the updated productLocker location and the VMware Tools repository is not accessible to the running VMs.

To detect the issue, Inspect the security policies:

# secpolicytools -d | grep $(basename $(readlink /productLocker)) | cut -d' ' -f2 | head -n1

This should return an entry matching the configured path to VMware Tools repository in the form:

-r <absolute-path-to-vmtoolsRepo-on-datastore> r

If the above path does not match, you need to reload the security policies:

# secpolicytools -p

Any running VM will need to be vMotion’d to a different host and back, or shutdown (reset will not work) and then powered on for the change to take effect. VM powered on after the security policies are updated will have the correct VMware Tools repository access.

Note: The datastore being slow to become accessible during VMware ESXi host reboot should be investigated, it could be linked to a storage or other resource issues in the environment.