Backup Freeze/Thaw batch script pitfalls for VMWare (and solutions)

Hey everyone.

I came across some issues when setting up Freeze and Thaw batch scripts for use with VMWare in a Windows ecosystem, and I wanted to share what I found in the hopes it can help others. This was undertaken in an environment using Healthconnect 2019.1.x.

IRIS not up (2)

It seems that the sample script from the documentation in my my case would tell me that the environment was not running (despite it running). To correct this, I provided the filepath to the Mgr location as so:

c:\InterSystems\HealthConnect\bin\irisdb -s"C:\InterSystems\HealthConnect\Mgr" -U%%SYS ##Class(Backup.General).ExternalFreeze() <C:\InterSystems\BackupScripts\login.scr

It could be because I had more than one installation of Healthconnect on this environment, however it persisted after an uninstall of the other instance and reboot.

Script Running

The second issue I faced was the getting the scripts to run when the backup was being taken. After some digging, I found that VMWare will run every script in the folder "C:\Program Files\VMware\VMware Tools\backupScripts.d" in alphabetical order passing in the command "freeze",  and then will run every script in reverse order using the command "thaw". In my case I needed to create this folder within the "VMWare Tools" directory.

To avoid managing multiple files and restricting what command can be run against them, I combined freeze and thaw into a single script, and added an if statement to the start of the single batch file to route to the freeze or thaw:

if "%1" == "freeze" goto doFreeze
if "%1" == "thaw" goto doThaw

Script Errorlevels

If the freeze is successful, irisdb.exe will return the errorlevel as 5. However, VMWare (and some others) will read a non-zero return as an error. Therefore, I needed to overwrite the exitcode depending on the errorlevel returned as it otherwise stops the quiescent backup running:

:FreezeOK
echo SYSTEM IS FROZEN
rem Error levels from freeze do not match standard convention, so we return 0 when successful.
EXIT /b 0

:FreezeFAIL
echo SYSTEM FREEZE FAILED
EXIT /b 1

note: I used 1 for the error purely because it was non-zero.

Final result

Putting this all together has given me the following:

@echo off
rem VMTools should pass in either freeze or thaw.
if "%1" == "freeze" goto doFreeze
if "%1" == "thaw" goto doThaw

echo Nothing Matched. Exiting...
EXIT /b

:doFreeze
rem Call external freeze and provide credential file stored in separate folder.
c:\InterSystems\HealthConnect\bin\irisdb -s"C:\InterSystems\HealthConnect\Mgr" -U%%SYS ##Class(Backup.General).ExternalFreeze() <C:\InterSystems\BackupScripts\login.scr
rem note that we need to check errorlevel from highest to lowest here....
if errorlevel 5 goto FreezeOK
if errorlevel 3 goto FreezeFAIL
rem If here, errorlevel did not match an expected output.
rem Assume Failure.
echo errorlevel returned unexpected value
goto FreezeFAIL

:FreezeOK
echo SYSTEM IS FROZEN
rem Error levels from freeze do not match standard convention, so we return 0 when successful.
EXIT /b 0

:FreezeFAIL
echo SYSTEM FREEZE FAILED
EXIT /b 1

:doThaw
c:\InterSystems\HealthConnect\bin\irisdb -s"C:\InterSystems\HealthConnect\Mgr" -U%%SYS ##Class(Backup.General).ExternalThaw()
EXIT /b 0

Improvements/Next steps

The doThaw block is pretty weak as it assumes success, and this could be a good opportunity to write to a log and record any failures. In addition, I will be adding in a call to ##Class(Backup.General).ExternalSetHistory() to ensure that the environment correctly records when backups have been taken and trigger journal purges.