Backup procedure

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

1. 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 have to stop the Perforce service during any part of the backup procedure.

2. Ensure that the checkpoint has been created successfully before backing up any files. If a disk crash occurs, it is important to know that the checkpoints you’ve been backing up are complete.

   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.

3. 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. The .md5 file 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.

4. 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 and partitioned clients in automated builds

   There is no use case for backing up the following:

   • db.* files
   • server.locks directory
   Note

   There are rare cases 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:

   • users obliterating files during backup, or
   • users submitting files on Windows servers during the file backup portion of the process

   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. Therefore, 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.

   Tip

   The version files to back up might be in one of the following:

   • The directory with the same name as each depot containing submitted files in the P4ROOT - this is the default.

   • The absolute path defined in the depot spec

   • The location set by the server.depot.root configurable, if it is set, which is the case with a package installation that uses the configure-helix-p4d.sh shell script. This script:

     • can be used to set the the server.depot.root configurable to a location such as /depots/archives and to verify the location, use the p4 configure show server.depot.root command

     • sets journalPrefix to ../journals, the location for checkpoints and rotated journals

     • sets up a nightly checkpoint by default. The crontab runs helix-p4d-maintenance.sh at 4am system time. This script checkpoints any servers with MAINTENANCE=true in the p4dctl config file. It also removes any checkpoints and rotated journals older than 14 days. See Helix Core Server Control (p4dctl).

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