Backup procedure

If your site is very large (gigabytes of db.* files), creating a checkpoint might take a substantial amount of time. Therefore, consider:

only creating a checkpoint at the end of each work week, while rotating the journal file during your nightly backup
performing checkpoints on a separate instance of your Helix Core p4d Server database. See the Support Knowledgebase article, Offline checkpoints.

The instructions on this page are basic. If your organization has a large data set, and you want zero-downtime checkpoints and near-zero downtime upgrades, ask Perforce Consulting about the Helix Core Server Deployment Package (SDP) at https://swarm.workshop.perforce.com/projects/perforce-software-sdp/.

If your site is using Helix Core Server Extensions, see Backup and restore in Helix Core Extensions Developer Guide.

Windows and db.* file locking

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 of the Helix Core Server database.

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 its database files. Therefore, if a user attempts to perform an operation that would update a database 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.

Location of versioned files

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

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).

Optional for backup

It is optional to back up:

log files
readonly clients - see Read-only and partitioned clients in automated builds

There is no need to back up:

db.* files
server.locks directory

Consider stopping the server before checkpointing

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.

Steps for nightly backup

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

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.
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.
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.
When 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
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.

Recommended weekly verify

By running p4 verify, you can confirm whether the archive files and shelved files on the server are correct. Regular use of p4 verify is good practice because it enables you to:

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

We recommend that administrators perform p4 verify weekly, rather than nightly. For large installations, the verification of files:

takes considerable time to run
puts the server under heavy load, which can impact the performance of other Helix Server commands

To verify archive files

$ p4 verify //...

$ p4 verify -q //... where the -q (quiet) option produces output only if errors are detected

To verify shelved files, use the ‘-S’ option

$ p4 verify -S //...

$ p4 verify -q -S //... where the -q (quiet) option produces output only if errors are detected

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