Enabling or disabling Changed Block Tracking (CBT) on virtual machines

Products

VMware vSphere ESXi

Issue/Introduction

This article provides steps to enable or disable Changed Block Tracking (CBT) on a virtual machine.

Backup products such as VMware vSphere Data Recovery, Veeam, Unitrends, Commvault and more take advantage of CBT for incremental backups if CBT is enabled in the virtual machine. For more information on CBT, see Changed Block Tracking (CBT) on virtual machines (1020128).

Symptoms:
Changed Block Tracking (CBT) feature of VMware which facilitates taking incremental backups on virtual machines running on VMware ESX/ESXi.
CBT identifies and tracks block changes since the last backup, and stores these changes as logs for tracking the backups.

When backing up a virtual machine, you see the error:

One or more VM disks have incorrect changed block tracking configuration.

The backup job shows the errors:

Disk "Hard disk #" has incorrect changed block tracking configuration

One or more VM disks have incorrect changed block tracking configuration

When trying to consolidate snapshots:

Unable to access file since it is locked. An error occurred while consolidating disks. One of the disks in this virtual machine is already in use by a virtual machine or by a snapshot. (In this case, the files will be there and there will be no locks present in the VM folders.)

Environment

VMware vSphere ESXi 6.0
VMware vSphere ESXi 6.5
VMware vSphere ESXi 6.7
VMware vSphere ESXi 7.0.x
VMware vSphere ESXi 8.0.x

Resolution

To enable or disable CBT on a virtual machine, perform the appropriate steps given for enabling or disabling:

Note: Ensure that the virtual machine is powered off before performing these steps.

To enable CBT in a virtual machine:

Power off the virtual machine.
Right-click the virtual machine and click Edit Settings.
Click the Options tab.
Click General under the Advanced section and then click Configuration Parameters. The Configuration Parameters dialog opens.
Click Add Row.
Add the ctkEnabled parameter and then set its value to true.
Click Add Row, add scsi0:0.ctkEnabled, and set its value to true.

Note: scsi0:0 in scsi0:0.ctkEnabled indicates the SCSI device assigned to the hard disk that is added to the virtual machine. Every hard disk added to the virtual machine is given a SCSI device that appears similar to scsi0:0, scsi0:1, or scsi 1:1. CBT is enabled (or disabled) individually on each disk.
Power on the virtual machine.
In the home directory of the virtual machine, verify that each disk having CBT enabled has also a vmname-ctk.vmdk file.

To disable CBT, it is recommended that there are no snapshots on the VM, but you can disable it even if it has snapshots. For more information, see:

To disable CBT:

Power off the virtual machine.
Right-click the virtual machine and click Edit Settings.
Click the Options tab.
Click General under the Advanced section and then click Configuration Parameters. The Configuration Parameters dialog opens.
Set the ctkEnabled parameter to FALSE for the ctkEnabled setting for the VM and for each SCSI disk(s).
Remove the .vmsd file along with any ctk.vmdk files in the VM folder(s). You can create a subfolder and move them there or just delete them.
Power on the virtual machine.

Note: Ensure that there are no snapshots on the virtual machine before enabling change tracking. If you create snapshots before enabling CBT, the QueryChangedDiskAreas API might not return any error or the data returned by QueryChangedDiskAreas might be incorrect.

Additional Information

You can use these PowerCLI commands to disable and then enable CBT without powering off the virtual machine. This can be useful when one or more of the disks of the virtual machine is extended past a 128Gb boundary. See QueryChangedDiskAreas API returns incorrect sectors after extending virtual machine VMDK file with Changed Block Tracking (CBT) enabled. You can comment out the enable or disable commands in the script when appropriate for other uses

$vm="VM_Name"

$vmtest = Get-vm $vm| get-view

$vmConfigSpec = New-Object VMware.Vim.VirtualMachineConfigSpec

#disable ctk

$vmConfigSpec.changeTrackingEnabled = $false

$vmtest.reconfigVM($vmConfigSpec)

$snap=New-Snapshot $vm -Name "Disable CBT"

$snap | Remove-Snapshot -confirm:$false

# enable ctk

$vmConfigSpec.changeTrackingEnabled = $true

$vmtest.reconfigVM($vmConfigSpec)

$snap=New-Snapshot $vm -Name "Enable CBT"

$snap | Remove-Snapshot -confirm:$false

For steps to do a full reset of CBT data, see Resetting Changed Block Tracking for VMware vSphere virtual machines (2139574).