Database Consistency Check and Repair on VMware Horizon 6 – Simplified!

In a typical networked solution, especially based on Client Server architecture model, we cannot avoid certain conditions, which will leave some part of pending operation becomes  incomplete due to network latency , temporary disconnect or related issues. Such incomplete operations often will not harm the product usage, but may leave its footprint by one or more stale data or settings. When such things happens on a VMware Horizon environment,  its databases can become out-of sync, leaving stale entries about Virtual Desktops.

In VMware Horizon Server, the Virtual desktop information is stored across following three databases:

  1. ADAM Databases on Connection Servers
  2. Composer Database
  3. vCenter Database

These three databases together constitute the information of Linked Clone Virtual desktops. (For Full Clone desktops, Composer Database is not applicable). Even in an error free infrastructures, there are chances that these databases can become out of sync. Those are such situations but not limited to

  •  A vCenter Administrator accidentally renames a lined clone VM or its parent VM via vCenter
  • The parent VM or linked clone VMs are moved across inventory folders by mistake
  • Accidental deletion of linked clone VM(s) or its parent VM by vCenter Administrator
  • Some temporary network connectivity failure during database update, that leaves one or more databases in an inconsistent state.

Now, manually editing the composer database or ADAM database is not recommended and is risky in many aspects. To automate this clean-up actions by avoiding the manual database modification, there was a fling  released last year named ViewDbChk

Now the Latest release of Horizon View has this tool integrated, and does not need to download it from VMware Labs. In this blog I am detailing the integrated tool and its usage.

The ‘ViewDbChk’ Tool

The integrated tool is located under Path “C:\Program Files\VMware\VMware View\Server\tools\bin>” on the connection server machine, and the command file is “viewdbchk.cmd”. The tool uses its  corresponding .jar file located on the same folder


This command is intended to use for operations like finding desktops, enable and disable pools, scanning for errors and removing error VMs and stale entries. The options of the commands are case sensitive whereas values for each options are not case sensitive. The values does not support any wild card characters.

There are total seven types of operations, that currently supported. Each of these operations and its usages are explained below:

1. Finding a Desktop Pool

This command allows to find the Desktop Pool details using its pool  ID. Only Pool ID is supported. Searching with Display Name will not give any results unless both are same.

ViewDbChk --findDesktop --desktopName  [--verbose]

The search is confined only in LDAP, and returns details like Desktop pool Name, Type, VM Folder location, pool status and provisioning status. The pool type value will be one of following which means…

  • STICKY_LC_TYPE : Automated Linked Clone Desktop; dedicated user assignment
  • AUTO_LC_TYPE : Automated Linked Clone Desktop; floating user assignment
  • STICKY_TYPE : Automated Full Clone Desktop; dedicated user assignment
  • AUTO_TYPE : Automated Full Clone Desktop; floating user assignment

2. Disabling a Desktop Pool

The clean-up operation by ViewDbChk is done by removing stale VM entries, ADAM entries, and ‘out of sync’ database entries. Since such modifications are sensitive, the pool must set to ‘disabled’ mode for a safe clean-up action. Using ViewDbChk this pre-requisite can be achieved through below syntax:

ViewDbChk --disableDesktop --desktopName  [--verbose]

Optionally by using “–verbose”, the command lists number of desktops in the pool and VM names.

3. Enabling a Desktop Pool

This functions exactly same as that of Enable option in View Administrator console page. As stated above, for clean-up operations through ViewDbChk, the pool must be in disabled mode. Upon completion on such operation, this command can be used to bring the pool to enabled state.

ViewDbChk --enableDesktop --desktopName  [--verbose]

Optionally by using “–verbose”, the command list number of desktops in the pool and VM names.

4. Finding a Machine

Similar to operation #1 above, the details of a machine (i.e. the VM in a desktop pool) can be identified with its name. The output will display all details of VM as well as its pool. First, the pool details are displayed as like explained in “Finding a Desktop Pool” and then the tool connects to corresponding vCenter Server and fetch all the VM details.

ViewDbChk --findMachine --desktopName  --machineName  [--verbose]

The result includes VM’s MOID, VM name, Creation date, machine ID, Clone ID, VM folder and VM State. The output of VM State is very important here. We can assume that a machine is healthy and its configuration is intact by looking for its “Ready” state. Other than this state, if it shows error then it can be considered for removal.

5. Removing a Machine

If a machine (desktop VM) is identified as stale entry and considered for removal, it can be removed safely using below command. The pre-requisite is to disable the pool, and if not met, the command automatically prompts for the confirmation for disabling the pool & provisioning.  Further after removal operation, command automatically seeks confirmation for enabling the pool back and enable pool provisioning back.

ViewDbChk --removeMachine --machineName  [--desktop name ] [--force] [--noErrorCheck] [--verbose]

If you are very sure about the remove operation, and if you wish to proceed by skipping the confirmation prompts, you may use “–force” so that, disabling and enabling back will happen without any confirmation prompts.

By default while removing a VM from desktop pool, the tool checks for errors. And if no error is found (VM state is ‘Ready’), then output displays a message saying “machine XYZ does not have any errors…” and skips the VM remove action. In such case, if the VM needs a force removal  “–noErrorCheck” can be leveraged.

If applicable, removal operation automatically takes care of removal of ThinApp entitlements and archival of User Data Disks (persistent disks)

6. Scanning all Desktop Machines and performing automatic repair

You can scan entire system for stale entries and error state VMs and perform the cleanup automatically, by using the option “–scanMachines”. This is a powerful yet simple way to remove any error state entries and machines automatically. If not specified exclusively, the command will scan all configured desktop pools and report VM states.

ViewDbChk --scanMachines [desktopName ] [--limit ] [--force] [--verbose]

Use “desktopName” option to scan within a desktop pool. The “–force” option works same as explained in section 5.

Though the command identifies all the the error machine entries, by default it will attempt to clean-up only one machine. This is because the ‘maximum deletes’ limit is set to “1” by default. To override this, increase the limit by “–limit” option

7. Tool Help

To list all the available tool options and syntax, the tool has in-built help.  Optionally, you can get help for a specific command option by using “–commandName”

ViewDbChk --help [--commandName] [--verbose]

Additional Notes

Use of this tool is recommended only after ensuring necessary backup of the system and/or  consulting with VMware Service Professional.

Permalink to this article: