CBT warnings for Hyper-V backups run with Unitrends agent version 8.1.0-3 and higher

SUMMARY

In Unitrends releases 8.1 and higher, the Unitrends Windows agent leverages a Hyper-V CBT driver that greatly increases backup performance for virtual machines residing on hosts running Hyper-V versions 2012 and 2012 R2. If the driver is not installed on the host, backups complete with warnings. This article explains how to resolve these warnings.

ISSUE

In Unitrends releases 8.1 and higher, the Unitrends Windows agent leverages a Hyper-V CBT driver that greatly increases backup performance for virtual machines residing on hosts running Hyper-V versions 2012, 2012 R2 and (as of RecoveryOS 10) Hyper-v 2016. When the Client Agent installer detects one of these Hyper-v versions, the CBT driver is automatically installed along with the Client Agent.

By default, Unitrends expects to use the CBT driver when performing Hyper-v Host based virtual backups. In some rare cases where the Microsoft MSI install/uninstall/update process does not complete as expected, the CBT driver may not get removed or installed correctly. If the CBT driver is not detected during the backup process, host based virtual backups fall back to using the hash-scan method and complete with warnings if CBT was not prior used.  If CBT was prior used for backups, and cannot be used at this time, the backup will fail.  

This article provides instructions for installing the CBT driver, and if needed, how to manually disabling/enabling of the hash-scan and/or CBT driver.

RESOLUTION

It is recommended that you use the CBT driver to benefit from faster backups. If there is an issue with the installation of the CBT driver, backups will fail with a warning until the driver is installed or the scan method is changed manually. 

By design, the backup product in current releases expects the CBT driver to be used.   If prior backups in chain have used the CBT driver, and a new backup cannot, the product can fall back to using the hash-scan method but only after a new full is performed.  Some wish to prevent this method forcing CBT to always be used and this can be set.  Some customers, especially those who may not have followed Microsoft Hyper-V cluster deployment or architecture requirements may have issues with the CBT driver when guests fail over between nodes and may choose to disable it in favor of the hash scan method.  All of these options are provided below.  

Reinstall the CBT driver (without agent re-install)

In some rare cases manual CBT driver update will not function, and a complete agent reinstall may be necessary. Generally rebooting your server first and re-trying CBT install alone resolves many issues and the below process may be necessary to ensure successful CBT use.  Also note some antivirus or security programs may interfere with driver installation and those applications may need to be disabled during installation.  

1. Use an elevated Command Prompt (Run as Administrator) and run the uninstaller located in c:\PCBP\win2012.dir\mm-dd-yyyy,x.x.x.x directory. Exit the command prompt when finished.
2. Uninstall the Unitrends Client Agent using Program and Features (Add/Remove for older OSes).
3. Rename the C:\PCBP\ directory to C:\PCBP.old and the C:\unicbt directory to C:\unicbt.old (or delete them both)
   NOTE: If you have problems deleting them, reboot the Hyper-v Host and then try again.
4. Install the latest Unitrends Client Agent (usually located in \windows_agents\) or you can download the from our Support Downloads page.
5. To ensure the CBT driver installation was successful, use an elevated Command Prompt (Run as Administrator) and run file c:\PCBP\win2012.dir\IsCBTDriverInstalled.bat and view the output posted to the IsCBTDriverInstalled.log file. In addition, the directory C:\unicbt should now have been recreated.
6. If successful, run the next File Level backup for the Hyper-v Hosts as a Full/Master, and run Fulls for the Guest VMs. Follow the instructions on "How do I perform a 1-Time Full/Master using the new HTML5 Web Administrative Interface?" in KB 5580.
7. If you receive an access error when trying to install the CBT driver: 

• Use an elevated Command Prompt (Run as Administrator) and run the uninstall.bat file located in c:\PCBP\win2012.dir\mm-dd-yyyy,x.x.x.x directory
• Then, execute the following command: .\Install.bat /i

1. Log in to the host for which you want to disable the hash-scan method. 
2. Access the command line via Administrative CMD prompt and enter the following command to access the agent directory:  cd /pcbp.
3. To view the contents of the master.ini file, run the following command:  notepad Master.ini.  The contents of the Master.ini display in notepad.
4. Scroll to the bottom and under [Hyper-V], set the following parameter (or add the value if it is not present):  CBTDriverEnabled=False.
5. Save the file. (note this file may be prevented from saving if not running notepad as administrator)
6. Restart the BP Agent.
7. From now on, the Agent will use the hash-scan method for backups and they will complete without warnings.

1. Log in to the host for which you want to disable the hash-scan method. 
2. Access the command line and enter the following command to access the agent directory:  cd /pcbp.
3. To view the contents of the master.ini file, run the following command:  notepad Master.ini.  The contents of the Master.ini display in notepad.
4. Scroll to the bottom and under [Hyper-V], set the following parameter (or add the value):  HashEnabled=False. 
5. Save the file. (note this file may be prevented from saving if not running notepad as administrator)
6. Restart the BP Agent.
7. From now on, the Agent will attempt to use the CBT driver, but if it can not, it will fail the job immediately.

CAUSE

The CBT agent may fail to install or updated based on several factors.  CBT installation requires determination the server is a Hyper-V server, which may not succeed if PowerShell yper-V components are not installed properly, hyper-V services are not running, the server is under extreme load strain or is experiencing other environment performance issues, or if security applications or the permissions of the user running the install packages prevents the installation.  In these cases manual remediation may be required.