Australian cloud for business software — built and run in Sydney since 2003

+61 2 8282 5656
support@netleverage.com
Talk to an engineer
Talk to an engineer
NetLeverage
NetLeverage

Linux VM Backups: Filesystem Freeze and Thaw Scripts

Technical article
Backup & Recovery

Direct answer: a quiesced VMware snapshot of a Linux VM asks VMware Tools to freeze the guest filesystems. That gives a filesystem-consistent copy: the filesystem's own transactions are complete and its data is flushed. It says nothing about the application's own transactions. A database restored from that copy may still recover correctly through its documented crash recovery, but only if everything it needs (for example data files plus write-ahead log, on every volume involved) was captured together. If you need more than that, use the application's own documented backup method, or a VMware Tools pre-freeze script that follows the vendor's procedure and a thaw branch designed to undo it, including after a failed freeze. Then prove it with script logs and a restore test, not with the word "quiesced" in a job report.

Why it matters

Three levels of consistency are easy to confuse:

Level What it means What produces it
Crash-consistent Disk contents as if power was cut at that moment A snapshot without quiescing
Filesystem-consistent The filesystem's own transactions are complete and flushed; an application file can still hold a half-finished application-level update A quiesced snapshot on Linux
Application-consistent The application was prepared and captured using its own documented backup semantics (for example a backup mode, a flush-and-lock, or a native dump). Recoverability through documented crash recovery is a separate property The application's backup method, or a script that calls it around the freeze

The open-vm-tools project describes its quiescing feature as allowing the host "to capture file-system-consistent guest snapshot" (open-vm-tools README), with no application-level claim. "Quiesced" in a Linux backup report describes the filesystem, not the database.

How it works

The filesystem freeze. The fsfreeze manual page says a freeze lets ongoing filesystem transactions complete, halts new writes and other modifying calls, and writes dirty data, metadata and log information to disk. Any process that tries to write blocks until the filesystem is unfrozen (fsfreeze(8)). The page lists btrfs, ext2/3/4, f2fs, jfs, nilfs2, reiserfs and xfs as supporting freeze, and says the list may be incomplete. Those are filesystem transactions. An application that writes a record in several steps can be part-way through its own update when the freeze happens.

What VMware Tools does. When a quiesced snapshot is requested, the VMware Tools vmbackup plugin attempts to freeze the guest filesystems (Broadcom KB 421195). The open-vm-tools README lists the vmbackup plugin, quiescing of guest filesystems, and execution of pre-freeze and post-thaw scripts as separate features (open-vm-tools README).

The script order. Broadcom documents the order VMware Tools uses on Linux (Broadcom KB 313544):

Before the freeze: 1. The legacy script /usr/sbin/pre-freeze-script, if present. 2. Every script in /etc/vmware-tools/backupScripts.d/, in alphabetical order, with freeze as the first argument.

After the thaw: 1. Every script in /etc/vmware-tools/backupScripts.d/, in descending alphabetical order, with thaw or freezeFail as the first argument. 2. The legacy script /usr/sbin/post-thaw-script, if present.

The same article notes that the installer neither creates nor removes backupScripts.d, that the directory must contain only executable scripts (other files can make quiescing fail), and that VMware Tools must be installed. The reverse order on thaw unwinds layered steps in the opposite order.

Application consistency needs the application's own procedure

Database vendors document what a snapshot of their files needs. Two examples, both illustrations rather than procedures for your system:

  • PostgreSQL says a frozen snapshot of the volume holding the data directory produces files "as if the database server was not properly shut down", so the server replays the write-ahead log (WAL) on start. PostgreSQL calls this acceptable if the WAL files are included. So a filesystem-consistent snapshot can be a valid recovery input for PostgreSQL, through crash recovery. The same page warns that when data files and WAL, or tablespaces, sit on different filesystems, the snapshots must be simultaneous, and says to read your filesystem documentation carefully before trusting the technique in that case (PostgreSQL 18: File System Level Backup).
  • MySQL 8.4 documents, under "Making Backups Using a File System Snapshot", a sequence written for a Veritas file system snapshot: a client runs FLUSH TABLES WITH READ LOCK, the snapshot is taken from another shell, and the first client then runs UNLOCK TABLES. The manual adds that similar snapshot capabilities may exist in other file systems such as LVM or ZFS (MySQL 8.4: Database Backup Methods). It does not describe a VMware snapshot or a VMware Tools script. Note that the lock belongs to that client session, so a script cannot simply run the statement and exit. The same page describes mysqldump --single-transaction as an online backup for InnoDB tables that takes no table locks.

The application's own documentation, at the version you run, decides what "consistent" means for that application. Neither example is a complete production hook script.

How to check what you have (read-only)

These checks read state only. Run them inside the guest unless noted.

  1. Tools service state. Check the status of the VMware Tools daemon (vmtoolsd) with your distribution's service manager; the unit name varies by package. VMware Tools must be running for quiescing scripts to work (KB 313544).
  2. Scripts in place. List /etc/vmware-tools/backupScripts.d/ and check for /usr/sbin/pre-freeze-script and /usr/sbin/post-thaw-script. Record each file, its owner and whether it is executable. A non-executable file in the directory is a documented failure cause (KB 313544).
  3. Filesystems holding application data. Use findmnt to list mount points and filesystem types, and compare them with the application's data and log locations. If the application spans several filesystems, apply the PostgreSQL caution above.
  4. Script outcome evidence. A script that writes a timestamped line on freeze, thaw and freezeFail, like the logging example in KB 421195, gives you a record to compare with the backup job times.
  5. Compare with the backup job record. A matching freeze and thaw entry for the job time is positive evidence that the scripts ran. A missing entry is not proof that they did not run: the log may not have been written, rotated away, unreadable to you, or outside the window you selected. Without matching evidence, record application quiescing for that job as unverified.
  6. Host side. In vmware.log, Broadcom shows quiesce state changes (ToolsBackup: changing quiesce state) and the timeout message Timed out while quiescing the virtual machine (KB 421195). Read it through your normal host access.

None of these proves the backup is restorable; only a restore test completing the application's own recovery does.

Freeze and thaw failure handling

A freeze can fail or time out. Broadcom documents a case on ESXi 7.0.x and 8.0.x with open-vm-tools where, under heavy I/O, the freeze times out after a default 15 minutes even though the filesystem is in fact frozen. Further writes may then be attempted and both VMware Tools and the VM can become unresponsive (KB 421195). Broadcom's guest log example shows Error trying to perform OP_FREEZE on filesystems and a filesystem that "appears locked or frozen by another process", and the same article shows an Oracle cluster monitor triggering a deliberate kernel panic during the freeze.

Broadcom states a fix is planned for a future VMware Tools version and lists three workarounds: use pre-freeze and post-thaw scripts to stop the heavy-I/O workload during quiescing, use an agent-based backup inside the VM, or move the schedule to a time of low I/O. Check the article for your Tools version before relying on it.

That case matters for script design: if Tools or the VM hangs, a freezeFail branch may never run. A thaw branch is a design requirement you must validate, not something VMware Tools guarantees. Design requirements that follow:

  • Every action taken on freeze should be undone on both thaw and freezeFail, and that path should be rehearsed in an isolated copy, including a forced failure.
  • Bound the freeze-time work. Writes block while filesystems are frozen (fsfreeze(8)). Any application lock or stop the script takes needs its own time limit and release.
  • Have an independent recovery plan for the case where neither branch runs: who notices, how the application is checked, and how a held lock or stopped service is released. Agree it with the application owner before the script goes into production.
  • Log each branch with a timestamp, and do not let a script depend on writing to a filesystem that is about to be frozen.

What to choose and why

Situation Reasonable choice
Stateless or file-serving VM A quiesced snapshot may be enough. Confirm with a restore test.
Database whose vendor documents crash recovery from a simultaneous snapshot A quiesced snapshot that captures every volume involved, plus a restore test that completes the vendor's recovery
Database with a documented lock-and-snapshot procedure A pre-freeze script that follows it, a thaw and freezeFail branch that reverses it, and a rehearsed failure path. Lab first.
Database whose files span filesystems, or no snapshot procedure The vendor's own backup tool or dump, scheduled before the image backup, with its output backed up
VM under sustained heavy I/O at backup time Follow KB 421195: move the schedule, stop the heavy workload by script, or use an agent-based method

What not to do

  • Do not run fsfreeze --freeze by hand on a production server to "test" quiescing. Writers block until the filesystem is unfrozen. Test freezes and scripts in an isolated copy.
  • Do not put configuration files, notes or disabled scripts in backupScripts.d. Broadcom documents that non-executable files there can cause quiescing failure.
  • Do not report "quiesced" as "application-consistent" on Linux without script evidence and a restore test.

Limitations

  • Script locations and order come from Broadcom KB 313544, whose environment field lists vSphere 6.x releases. KB 421195 (ESXi 7.0.x and 8.0.x) uses the same backupScripts.d location. Confirm against current Broadcom documentation for your Tools version.
  • The database passages are illustrations from PostgreSQL 18 and MySQL 8.4 documentation. The MySQL passage is written for a Veritas file system snapshot.
  • The original MySQL URL on dev.mysql.com returned HTTP 403 to an independent reviewer; this article cites the same MySQL 8.4 manual on Oracle's documentation host.
  • No script, freeze or snapshot in this article has been lab tested.

Acceptance checklist

  • [ ] Each Linux VM's required consistency level (crash, filesystem, application) written down
  • [ ] Tools service confirmed running; script directory contents and permissions recorded
  • [ ] Application data and log locations mapped to filesystems
  • [ ] Scripts handle freeze, thaw and freezeFail, bound any lock or stop, and log each branch with a timestamp
  • [ ] Failure path rehearsed in an isolated copy, and a recovery plan for a hung freeze agreed with the application owner
  • [ ] Next scheduled backup shows matching freeze and thaw entries; any job without them recorded as unverified
  • [ ] A restore of the application data completed the application's own recovery

Sources

Displayed dates as shown when accessed on 30 October 2026.

Related articles

Learning notes

  1. A Linux quiesced snapshot is filesystem-consistent. Application consistency needs the application's own documented preparation and capture; a filesystem-consistent copy may separately be recoverable through the application's documented crash recovery, which is a different property.
  2. VMware Tools runs backupScripts.d scripts alphabetically on freeze and in reverse on thaw or freezeFail.
  3. A freezeFail branch is a design requirement to rehearse, not a guarantee.
  4. A missing script log entry means "unverified", not "did not run".
  5. Only a restore test proves the application can recover.