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 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()Opens in a new tab and Backup.General.ExternalThaw()Opens in a new tab, 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 set up external backup, write a script that performs the following steps:

  1. Freeze writes to the database using the Backup.General.ExternalFreeze()Opens in a new tab 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()Opens in a new tab method.


    In the event the Backup.General.ExternalThaw()Opens in a new tab method does not resume the write daemon and unfreeze the instance, you can issue the irisstat command with the -W option to do so. (This option will not unfreeze the write daemon from any hang or suspension caused by anything other than a backup.)

  4. Copy the snapshot to the backup media.

  5. When the backup is complete, you can use the Backup.General.ExternalSetHistory()Opens in a new tab method to record this backup in the backup history. Note that recording the backup 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.

See Backup.GeneralOpens in a new tab 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()Opens in a new tab 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 Journal I/O Errors 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()Opens in a new tab is called.


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


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 InterSystems IRIS can be started only by an administrator.

On Windows systems, 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()Opens in a new tab and Backup.General.ExternalThaw()Opens in a new tab, as indicated by messages in the messages log.


If you use VSS, make to use vSphere snapshot option Quiesce guest file system. This option invokes calls the VSS callbacks, which will freeze the database before the snapshot and thaw the database after the snapshot. The messages log will show VSS Writer: OnFreeze and VSS Writer: OnThaw.

In contrast, without this option, vSphere performs only a memory snapshot and the messages log does not contain these messages.

FeedbackOpens in a new tab