Pre- and post-backup scripts provide fine-grained control over what happens inside a guest virtual machine (VM) immediately before a snapshot is taken (to quiesce the database) and immediately after it completes (to resume normal operations). Common use cases include quiescing databases to ensure data integrity, dumping application logs, performing file or directory cleanups, stopping and restarting services, or triggering any custom operation your workflow requires.

By integrating custom scripts with VMware's snapshot lifecycle, you achieve application-consistent backups. This process ensures your applications and databases are in a clean, recoverable state, avoiding a crash-consistent state where in-flight transactions or incomplete operations could cause issues.

Prerequisites

Before configuring pre- and post-backup scripts, ensure your environment meets the following requirements.

VMware Tools version 10.2 or higher must be installed and running on the guest VM.
The Enable VMware Tools quiescing setting must be toggled ON in your VMware backup policy.

📝 Note
If quiescing is disabled in the policy, scripts will not execute, even if they are configured on the VM. The backup will be in a crash-consistent state.

All proxies within the assigned pool must be updated to a version that supports pre/post scripts (7.1.2 or later). The configured script directory path must exist identically across all proxies in the pool.
You must assign valid Guest OS Credentials to the VM so the backup proxy can copy files to and from the guest OS.

❗ Important

If any of the requirements are not met, the Pre-Post Backup Scripts option on the Configure for Backup page is disabled.

How script execution works

When a backup is triggered, the backup proxy coordinates script execution directly with VMware Tools inside the guest VM.

The backup lifecycle

1. Check and validate the scripts

The backup proxy looks for your custom scripts on the proxy server. If the script folder is missing or empty, the behavior depends on your settings:

If Skip backup if script is missing is checked, the backup process stops immediately to prevent your data from being backed up in an unsafe state.
If left unchecked, the backup continues but will finish with a Successful with Errors warning to let you know the scripts did not run.

2. Copy to the VM

If the scripts are found, the backup proxy uses the VM's login credentials to securely log into the guest operating system and copies scripts from the proxy directory to the guest VM's native VMware directory:

On Linux: /etc/vmware-tools/backupScripts.d/
On Windows: C:\Program Files\VMware\VMware Tools\backupScripts.d\

3. Freeze, freezeFail, and Thaw (snapshot orchestration)

VMware Tools triggers the scripts based on the snapshot state using specific arguments:

freeze: It runs your script first to safely pause the application or lock the database so no new data is written.

The system takes a quick, perfect point-in-time picture (snapshot) of your frozen data.

thaw: It runs your script again to unlock the database and resume normal operations.
freezeFail: If the snapshot accidentally fails halfway through, this emergency script runs to safely unlock your database so your application doesn't get stuck.

4. Clean Up and Save

The backup proxy deletes the copied scripts from the guest VM's directory (regardless of job success or failure) and uploads the snapshot data to the cloud. Your backup is complete!

Execution Order

If your scripts directory contains multiple scripts, for example, 01-webapp.sh and 02-database.sh:

Freeze phase: Scripts execute in lexicographic (filename) order: 01-webapp.sh runs first, followed by 02-database.sh.
Thaw phase: Scripts execute in reverse order (Last-In, First-Out): 02-database.sh runs first, followed by 01-webapp.sh.

This ensures dependent components are frozen and thawed in the correct sequence.

Timeout and Retry behavior

VMware Tools allows a maximum of 60 seconds by default for all scripts combined to complete. If they time out, the snapshot fails with a Quiesce Error and an alert is raised on the Management Console.
To increase this limit, modify the tools.conf file on the guest VM and restart the VMware Tools service. For example,
[vmbackup]
# Increase timeout (e.g., 300 seconds = 5 minutes)
quiesce.timeout = 300

If quiescing fails, the backup job retries up to three times. If a valid pre-post script is present, it will run prior to each retry attempt (maximum of three times).

Configuring pre and post scripts

Script configuration is managed at the VM backupset level, not the backup policy level. You can apply these settings using four methods:

During Initial VM Configuration: Specify the script directory path and execution rules during the first-time setup wizard. For more information, see Manually configure VMware virtual machines for backup.
VM Reconfiguration: Modify settings for an existing VM. Reconfiguring creates a new internal entry; old, unused configurations are cleaned up automatically. For more information, see How to reconfigure VMware virtual machines configured for backup.
Auto-Configuration Rules: Define script paths within auto-config rules. Any VM discovered and mapped by this rule will automatically inherit these settings. Updating a rule retroactively updates all VMs currently governed by it. For more information, see Automatically configure VMware virtual machines for backup.
Bulk Edit: Apply a uniform script configuration to multiple VMs simultaneously.
- Bulk Disable: Prompts a confirmation warning and removes script settings entirely from selected VMs.
- Mixed Proxy Fallback: If a selection includes older proxies that lack script support, the configuration is only applied to VMs on supported proxies; unsupported proxies are skipped.
  For more information, see How to change Pre and Post Scripts.

Configuration settings

The following configuration settings are available for all the above methods:

Pre-Post Backup Scripts	Toggle to enable or disable script execution for the selected VMs.
For Windows VM Script Directory	Path to the folder on the backup proxy containing scripts for Windows guest VMs.
For Linux VM Script Directory	Path to the folder on the backup proxy containing scripts for Linux guest VMs.
Script Settings
Skip backup if script is not present at the specified location	When enabled, the backup will be skipped if the scripts directory does not exist or is empty on the proxy.
Skip backup if script execution fails	When enabled, the backup will be skipped if a script returns a non-zero exit code.

Script writing guidelines

Best Practices

Your script must contain conditional blocks for freeze, thaw, and freezeFail to prevent databases from hanging in a permanently locked state if a snapshot fails.
Only .sh files (Linux) and .bat files (Windows) are supported. All other file extensions are ignored.
Ensure correct permissions.
- Linux: The guest OS credentials assigned to the VM must have permissions to execute the script.
- Windows: Scripts must be executable by the LocalSystem account.

Sample script: PostgreSQL quiescing

#!/bin/bash
if [[ $1 == "freeze" ]]
then
       # set log directory
       log="/var/log/vpostgres_backup.log"
       # set and log start date
       today=`date +%Y\/%m\/%d\ %H:%M:%S`
       echo "${today}: Start of creation consistent state" >> ${log}
       # execute freeze command.
       # This command can be modified as per the database command
       cmd="echo \"SELECT pg_start_backup('${today}', true);\" | sudo -i -u postgres psql >> ${log} 2>&1"
       eval ${cmd}
       # set and log end date
       today=`date +%Y\/%m\/%d\ %H:%M:%S`
       echo "${today}: Finished freeze script" >> ${log}
elif [[ $1 == "thaw" ]]
then
       echo "This section is executed when the Snapshot is removed"
       log="/var/log/vpostgres_backup.log"
       # set and log start date
       today=`date +%Y\/%m\/%d\ %H:%M:%S`
       echo "${today}: Release of backup" >> ${log}
       # execute release command
       cmd="echo \"SELECT pg_stop_backup();\" | sudo -i -u postgres psql >> ${log} 2>&1"
       eval ${cmd}
       # set and log end date
       today=`date +%Y\/%m\/%d\ %H:%M:%S`
       echo "${today}: Finished thaw script" >> ${log}
elif [[ $1 == "freezeFail" ]]
then
       echo "This section is executed when the Quiescing Fails."
else
       echo "No argument was provided"
Fi

Frequently Asked Questions (FAQs)

What happens if a script fails or returns a non-zero exit code?

If Skip backup if script execution fails is enabled, the backup job stops and is marked as skipped. If disabled, the backup will continue without pre-post scripts.

Can two scripts run simultaneously or have the same execution order?

No. Scripts execute sequentially in alphanumeric (lexicographic) order by filename. Two files cannot share the same filename in a single folder. If you have 01-script.sh and 01-script2.sh, 01-script.sh will completely finish before 01-script2.sh begins.

Are these scripts backed up?

Yes. Active scripts are bundled with the backup data. When you perform a VM restore, the scripts active at the time of that backup are restored directly back onto the VM filesystem.

What happens to existing backups if I don't configure scripts?

Existing backup routines remain completely unaffected. They will continue running as standard crash-consistent or native OS-quiesced backups without operational changes.

What happens if script cleanup fails on the guest VM after a script execution error?

Scenario

1. Pre/post scripts are configured on a VM.

2. Skip backup if script fails is disabled.

3. During backup, a script execution fails (non-zero exit code).

4. Since Skip backup if script fails is disabled, the system attempts to recover. It tries to clean up (delete) the scripts that were copied to the guest VM's backupScripts.d directory.

5. The cleanup itself fails, for example, due to a guest OS permission issue, VMware Tools error, or the guest VM becoming unresponsive.

In such a scenario, the backup is marked as failed, as a quiesced snapshot cannot proceed if scripts are still present in the backupScripts.d directory on the guest VM.