Backup procedures

To back up your Helix Server installation, perform the following steps as part of your nightly backup procedure.

1. Verify the integrity of your server by using the p4 verify command:

   $ p4 verify //...

   or

   $ p4 verify -q //...

   The -q (quiet) option produces output only if errors are detected.

   By running p4 verify before the backup, you verify that the archive data on the server is correct and has not been damaged since the files were submitted.

   Regular use of p4 verify is good practice because it enables you to:

   • locate any corruption before a backup,
   • determine whether or not the files restored from your backups following a crash are in good condition
   Note

   For large installations, p4 verify might take some time to run. Furthermore, the server is under heavy load when p4 verify is verifying files, which can impact the performance of other Helix Server commands. Administrators of large sites might choose to perform p4 verify on a weekly basis, rather than a nightly basis.

   For more about the p4 verify command, see Verifying files by signature.

2. Make a checkpoint by invoking p4d with the -jc (journal-create) flag, or by using the p4 admin command. Use one of the following:

   On the host, where you might have a script that runs daily and also manages checkpoint files:

   $ p4d -jc

   or, on the client that is physically separate from the host:

   $ p4 admin checkpoint

   Because p4d locks the entire database when making the checkpoint, you do not generally have to stop the Perforce service during any part of the backup procedure.

   Note

   If your site is very large (gigabytes of db.* files), creating a checkpoint might take a considerable length of time.

   Under such circumstances, you might want to defer checkpoint creation and journal truncation until times of low system activity. You might, for instance, archive only the journal file in your nightly backup and only create checkpoints and roll the journal file on a weekly basis.

3. Ensure that the checkpoint has been created successfully before backing up any files. (After a disk crash, the last thing you want to discover is that the checkpoints you’ve been backing up for the past three weeks were incomplete!)

   Verifying either of the following:

   • p4d -jc (or p4 admin checkpoint) returns the value of 0
   • the current journal file is truncated

   You can also use the command p4d -jv to verify the integrity of a checkpoint.

4. Confirm that the checkpoint was correctly written to disk by comparing the MD5 checksum of the checkpoint with the .md5 file created by the checkpoint process.

   The checksum in the .md5 file corresponds to the checksum of the file as it existed before any compression was applied, and assumes UNIX-style line endings even if the service is hosted on Windows.

   If your checkpoint file was created with the -z compression option, you might need to decompress it and account for line ending differences. On Windows, after decompressing a checkpoint, Windows line endings must be re-added before calculating the .md5 sum.

5. Once the checkpoint has been created successfully, back up:

   • the checkpoint file and its .md5 file
   • the rotated journal file. If the checkpoint is n, the rotated journal is journal.n-1. See also Journal files.
   • the license file
   • the versioned files
   Tip

   OPTIONAL for backup:

   • log files
   • readonly clients - see Using read-only clients in automated builds

   There is no use case for backing up the following:

   • db.* files
   • server.locks directory
   Note

   There are rare instances (for instance, users obliterating files during backup, or submitting files on Windows servers during the file backup portion of the process) in which your versioned file tree can change during the interval between the time the checkpoint was taken and the time at which the versioned files are backed up by the backup utility.

   Most sites are unaffected by these issues. Having Helix Server available on a 24/7 basis is generally a benefit worth this minor risk, especially if backups are being performed at times of low system activity.

   If, however, the reliability of every backup is of paramount importance, consider stopping the Perforce service before checkpointing, and restart it only after the backup process has completed.

   Note

   On Windows, if you make your system backup while the Perforce service is running, you must ensure that your backup program doesn’t attempt to back up the db.* files.

   If you try to back up the db.* files with a running server, Windows locks them while the backup program backs them up. During this brief period, Helix Server is unable to access the files; if a user attempts to perform an operation that would update the file, the server can fail.

   If your backup software doesn’t allow you to exclude the db.* files from the backup process, stop the server with p4 admin stop before backing up, and restart the service after the backup process is complete.

6. If you have used the p4 serverid command to identify your server with a server.id file, the server.id file (which exists in the server’s root directory) must be backed up.