Skip to main content

External Backup

External Backup

External backup is currently the recommended best practice for backing up the entire database. It integrates easily with your existing system backup procedures and typically allows for a zero downtime backup. It is used primarily in conjunction with technology that provides the ability to quickly create a functional “snapshot” of a logical disk volume. Such technologies exist at various levels, from storage arrays, to operating systems, to simple disk mirroring. There are special considerations, discussed in this section, for systems on which snapshot technology is not available.

To ensure the integrity of the snapshot, InterSystems IRIS provides methods to freeze writes to databases while the snapshot is created. Only physical writes to the database files are frozen during the creation of the snapshot, allowing user processes to continue performing updates in memory uninterrupted. The snapshot is typically a snapshot of all file systems in use by the system. At a minimum, this includes all directories used by the InterSystems IRIS database in any way, such as the installation directory, database directories, journal and alternate journal directories, WIJ directory, and any directory containing external files used by the system. After writes are thawed, the snapshot may be backed up and then either rejoined to production or left online as a warm backup (depending on the specific technology used).


To avoid the problem of false reporting of errors when running integrity checks on databases while they are in use, you can integrate the integrity checks into procedures like those described in this section, so that databases are checked immediately after the file system snapshot is taken. (See Verifying Structural Integrity in the “Introduction to Data Integrity” chapter of this guide for information about checking database integrity.)

The following table lists the advantages and disadvantages of the external backup strategy:

Advantages Disadvantages
Allows zero downtime backups with no user interruption for most systems.
If writes are to be frozen for longer than 10 minutes, special consideration is required if you want to allow users to continue uninterrupted.
Integrates easily with existing backup procedures.

The class methods that perform the database freeze and thaw operations are Backup.General.ExternalFreeze() and Backup.General.ExternalThaw(), respectively. In addition to pausing writes, the freeze method also handles switching journal files and writing a backup marker to the journal. The journal file continues to be written normally while physical database writes are frozen. If the system were to crash while the physical database writes are frozen, data would be recovered from the journal as normal during startup.

To summarize, the external backup involves the following steps:

  1. Freeze writes to the database using the Backup.General.ExternalFreeze() method. Examples of the use of this method on various platforms are included in the class documentation.


    When the security configuration requires that the backup script supply database credentials, you can do this by redirecting input from a file containing the needed credentials. Alternatively, you can enable OS-level authentication and create an InterSystems IRIS account for the OS user running the script.

  2. Create a snapshot of the file system using an external snapshot utility.

  3. Resume database writes using the Backup.General.ExternalThaw() method.

  4. Copy the snapshot to the backup media.

See the Backup.General class documentation in the InterSystems Class Reference for platform-specific examples of these methods.

For systems where snapshot technology is not available, a slower filesystem copy may be used in the external backup approach, described above, by replacing the creation of the snapshot with a filesystem copy. This can be done in one of the following ways or, depending on your needs, Online Backup may be an alternative:

  • Zero Downtime: Specify a value for the ExternalFreezeTimeOut parameter when calling Backup.General.ExternalFreeze() and ensure that you have configured sufficient database cache to allow database updates to be buffered in memory for the duration of the freeze. In this case the system allows users to continue working for extended periods with physical writes frozen, up to the specified ExternalFreezeTimeOut. Journaling is critical to prevent data loss in the event that the system crashes while writes are frozen; in the event of a crash, system startup may take longer than usual. The Journal setting for Freeze on Error should be set to Yes (see the Journal I/O Errors section in the “Journaling” chapter of this guide for more information).

  • Some User Interruption: Allow the expected freeze time to default to 10 minutes, after which users are paused until Backup.General.ExternalThaw() is called.


When the instance being backed up is the primary failover member in a mirror (see the chapter “Mirroring” in the High Availability Guide), an external freeze must not suspend updates for longer than the specified ExternalFreezeTimeOut parameter of Backup.General.ExternalFreeze(). If this happens, the mirror may fail over to the backup failover member, thereby terminating the backup operation in progress.

When the backup is complete, you can use the Backup.General.ExternalSetHistory() method to add a the backup to the backup history. Note that this can trigger a journal purge, depending on the When to purge journal files > After this many successive backups setting on the Journal Settings page (the default is 2); for more information, see Configuring Journal Settings in the “Journaling” chapter of this guide.


InterSystems IRIS supports the Volume Shadow Copy Service (VSS) on Windows by acting as a writer on behalf of its databases. Copies of InterSystems IRIS databases included in a VSS shadow are physically consistent, although not logically consistent with respect to transactions, and therefore may be restored individually. To ensure the transactional integrity of these restored databases, journal files should also be restored. Only databases that are mounted at the time of VSS shadow creation are included in the VSS shadow.

The VSS writer for Caché can be started only by an administrator.

On Windows systems, the EnableVSSBackup parameter in the iris.cpf file is set to 1 (enabled) by default. At InterSystems IRIS startup, the message “InterSystems IRIS VSS Writer started” is written to the messages log. When you create a VSS shadow copy, InterSystems IRIS automatically calls Backup.General.ExternalFreeze() and Backup.General.ExternalThaw(), as indicated by messages in the messages log.