Snapshot backups with Volume Shadow Copy Service (VSS) writer

Beginning with HCL Domino 12.0.2, Domino provides a native Windows VSS writer for snapshot backups. VSS writers are designed for application-aware VSS snapshots.

You can use any backup application that supports full VSS functionality to create a Domino-aware snapshot. When a backup application requests a snapshot with the auto-recovery option enabled (VSS default option VSS_VOLSNAP_ATTR_AUTORECOVER), Domino writes backup delta information directly into the snapshot to bring all databases to a consistent state. The resulting snapshot is recoverable directly from the snapshot and does not require restore and activation from Domino. In a disaster recovery scenario, the snapshot can be the best restore option to bring the Domino data directory to a consistent state. It is still advisable and convenient to use restore through Domino.

Without the auto recovery option, VSS backup performs a standard snapshot in which Domino writes delta files separately to be merged into the snapshot later. Even without auto-recovery enabled, VSS writer functionality is recommended because it provides simplified snapshot integration for Windows.

A server task, backupvss, provides VSS writer integration. When the task starts, it registers Domino as a VSS writer for the Domino data directory. backupvss triggers the backup task automatically when a backup application requests a VSS snapshot.


The requirements for VSS writer backup are as follows:
  • Domino 12.0.2 or higher.
  • Windows 2019 or Windows 2022 server.
  • All databases located on a single disk. Mount points and database and directory links pointing to a different disk are not supported.
  • On a partitioned server, only one partition can be configured for VSS writer backup.

Backup flow when VSS writer is used

  1. The backup application requests a VSS snapshot.
  2. The VSS back-end queries all applications to determine if the application needs to be involved in the snapshot.
  3. If the Domino data directory is requested, the Domino VSS writer (backupvss) signals interest.
  4. The VSS back-end requests all backup writers to perform a freeze operation.
  5. backupvss starts backup -vss to bring all databases into backup mode and when done signals freeze completion.
  6. The VSS back-end creates a snapshot.
  7. When the snapshot is in place, the VSS back-end sends a post thaw event to all applications.
  8. Domino skips the post thaw event and waits for the Post snapshot event to unfreeze all databases.
  9. If the snapshot is enabled for auto recovery, the VSS back-end mounts the backup in the Post snapshot event and merges delta information into the snapshot. It also marks all databases as recovered.
  10. The VSS back-end terminates the post snapshot event, logs output, and terminates the backup task.
  11. The VSS back-end returns control to the backup application to back up the snapshot.

Running the backupvss task

To provide VSS writer functionality, run backupvss continually on a Domino server. Add the task to the ServerTasks setting in the server notes.ini file or configure the task to run in a start-up program document.

When the task is loaded, console messages indicate that the Domino Backup VSS plug-in is started and that the Domino Backup writer is a listed writer:
BackupVSS: Domino Backup VSS plug-in started
vssadmin list writers
Writer name: 'Domino Backup Writer' 
   Writer Id: {dee12323-b0ce-4f3d-8d3a-68062f1c53cc} 
   Writer Instance Id: {4739ebf2-949b-49e9-ab98-86cb70ae40f2} 
   State: [1] Stable 
   Last error: No error 
The following parameters are available for backupvss:
  • -v (verbose logging)
  • -d (debug logging)

Backup configuration

No configuration is required for auto-recovery enabled backups. If auto-recovery backups are not enabled for your backup application, configure database backup to copy any delta files that occur during a snapshot. The most straightforward option is to use a standard file backup operation to back up delta files to another disk that is backed up separately, such as a system disk or DAOS disk. Domino backup brings all databases in to backup mode and writes backup results and inventory data into dominobackup.nsf.

Restore configuration

Restore integration depends on the selected backup target. If your backup solution is Veeam, restore integration for Veeam provided as of Domino 12.0.1 continues to work for VSS writer integration.

Snapshot restore operations usually mount the snapshot to the server and a restore script finds the databases in the mounted snapshot. The restore server task and restore scripts must be configured accordingly.

Veeam Backup & Replication integration is the reference implementation for backup and restore. For more information, see the Veeam documentation on the HCL Domino Backup open source site. Veeam supports end-to-end restore integration including multi-database restore with optimized mount operations.

Veeam auto-recovery requirements

Veaam as the back-end VSS writer has the following requirements for auto-recovery:
  • Vsphere VM backup with VMware tools installed on Windows
  • OS level Veeam agent on Windows
  • Because Hyper-V does not generally support auto recovery backup, basic VSS snapshot and delta files must be stored separately during backup.