Manually Installing and upgrading VMware Tools on existing hosts

Products

VMware vSphere ESXi

Issue/Introduction

VMware Tools ISO images on ESXi hosts are typically managed through the ESXi installer, vSphere Update Manager (VUM), or vSphere Lifecycle Manager (vLCM). However, you can also install and update these images manually.

This article provides instructions on how to:

Manually install or upgrade VMware Tools ISO images on existing ESXi hosts.
Manual steps to complete the install or upgrade without rebooting the VMware ESXi hosts.

Additionally, this guide will help you resolve the following issues:

Error: The required VMware Tools ISO image does not exist or is inaccessible. Vix 21001
VMware Tools incorrectly reporting as "Up to date" after updating the host's ISO files to a newer version.

Environment

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

Cause

The error message indicates that the virtual machine cannot find the required installation file, likely due to a corrupted or misconfigured installation source.

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 moving the productLocker to 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 see the the current ProductLocker location, ssh to the esxi host and run the below commands:

# 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)

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

Update the VMware Tools repository content, by following any one of the options:

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

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 6 and following) are for first-time setup of the vmtools repository on a shared datastore or when the location of the vmtools repository changes.
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)
Update the ProductLocker symbolic link (/productLocker) with of the following methods
1. Reboot the VMware ESXi host, or
2. Follow the reboot-less procedure below “Updating the ProductLocker symbolic link without rebooting the VMware ESXi hosts” .

Updating the ProductLocker symbolic link without rebooting the VMware ESXi hosts

Invoke updateProductLockerLocation vSphere API with /vmfs/volumes/<datastore-name-or-volume-id>/vmtools-repository-name> as the argument. This 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.
Open the updateProductLockerLocation method.
Enter the path in the Value field.
Click on "Invoke Method" to apply the setting:

NOTE: 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=host-<ID>&method=updateProductLockerLocation
```
In the example this would be: https://vcenter_fqdn/mob/?moid=host-####&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.

As a result, VMs on impacted esxi hosts cannot install/upgrade VMware Tools.

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