Perforce Public Knowledge Base - Offline Checkpoints
Reset Search
 

 

Article

Offline Checkpoints

« Go Back

Information

 
Problem

The checkpoint operation locks all Perforce database files and makes your server inaccessible for the duration of the process. As your Perforce server grows in size, the length of time it takes to create the checkpoint can become long enough to interfere with users' work, particularly in environments where development occurs near 24/7. The off-line checkpoint procedure detailed below dramatically reduces the time your server is unavailable due to checkpoint operations.

Solution

The off-line checkpoint process entails creating a second instance of your Perforce database, and then performing checkpoints on this second, off-line database instance. By taking checkpoints off-line, users are no longer blocked from accessing the primary (production) server during lengthy checkpoint operations.

You need to create the off-line instance of the Perforce Server on a different disk volume than the production server instance to reduce unfavorable performance effects. The off-line server can also be set up on a separate host machine to completely isolate your production server instance.

A prerequisite to setting up an off-line checkpoint process is choosing a location for your off-line Perforce database files. In the examples below, D:\Offline_P4ROOT is used as the off-line Perforce Server root location.

Seeding the off-line server

The off-line checkpoint process begins by seeding an off-line server with a current production server checkpoint. Seeding the off-line server entails first taking a checkpoint on your production Perforce server, copying this checkpoint to the off-line location, then restoring the checkpoint in the off-line location. For example:

  1. Checkpoint the production server:
     
         p4 -p MASTER-HOST:MASTER-P4PORT admin checkpoint
        
    OR:
     
         p4d -r C:\P4ROOT -jc
         

    The p4d command above assumes the default running journal location. If your server configuration uses the P4JOURNAL environment variable or the -J option to p4d to relocate or rename the running journal file, you must use the -J option to p4d to tell the checkpoint command where the running journal file is located. For example, if the running journal were located at "D:\perforce_journals\journal":

         p4d -r C:\P4ROOT -J D:\perforce_journals\journal -jc
     
    

    Using p4 admin checkpoint to take the checkpoint does not require the user to know the location of the running journal file.

  2. Copy the checkpoint to the offline location:

         copy C:\P4ROOT\checkpoint.NNN D:\Offline_P4ROOT\checkpoint.NNN
     
  3. Restore the checkpoint in the off-line location:

         p4d -r D:\Offline_P4ROOT -jr checkpoint.NNN

Note: Should the off-line server instance ever become corrupt or out-of-sync with the production server, you can restart the process by re-seeding the offline server with a fresh checkpoint from the production server, as outlined above.

Taking off-line checkpoints

Once the off-line server has been seeded, you keep its contents updated by one of the following methods:

  1. Using the p4 pull command (requires Perforce Server 2010.2 or later).

  2. Using the p4 replicate command (requires Perforce Server 2009.2 or later).

  3. Manually restoring truncated journal files from the production server.

The optimal solution is to use p4 pull with a 2011.1 or later Perforce Server as this allows for automated updating of replica metadata and scheduling of checkpoints on the replica that are triggered by journal rotation on the master.

Option 1: Use p4 pull

The content in the off-line server will be as current as the latest master journal transaction successfully replicated and applied to the off-line server. See the related Knowledge Base article, Perforce Metadata and Archive Replication, for further details on the use of p4 pull. Note, the use of p4 pull requires the replica server be running so you may need to obtain a duplicate server license; this can be obtained by filling out the online duplicate server request form or contacting Perforce Support.

Perforce Server Version 2011.1 and later

When run against a replica server, the p4 admin checkpoint command schedules a checkpoint for the next journal rotation detected on the master. The commands to take an offline checkpoint are as follows:

  1. Schedule the checkpoint on the replica server:

    p4 -p REPLICA-HOST:REPLICA-P4PORT admin checkpoint
    The "pull" command will perform the checkpoint at the next rotation of the journal on the master.

    A stateCKP file is written to the P4ROOT directory of the replica server recording the scheduling of the checkpoint:

    $ cat stateCKP 
    Checkpoint scheduled at 1351198286 (2012/10/25 13:51:26 -0700 PDT ); opts: 
    

    Removing the stateCKP file cancels the currently scheduled checkpoint if replica journal processing has not already detected a journal rotation on the master. The stateCKP file is removed when the replica begins the scheduled checkpoint after journal rotation is detected on the master.

  2. Rotate the journal on the master server

    p4 -p MASTER-HOST:MASTER-P4PORT admin journal 

    The journal rotation on the master creates a journal trailer note in the rotated journal:

     @nx@ 3 1351198744 @31@ 0 0 0 0 0 @@ @@ @@ @@ @@ 

    The replica reads this line as part of its normal journal processing and triggers the checkpoint to start on the replica.

Perforce Server Version 2010.2

With Perforce Server version 2010.2, you take an offline checkpoint by running the following command:

p4d -r D:\Offline_P4ROOT -jd checkpoint.mmddyyyy

Note the use of the -jd flag which instructs the server to not truncate the journal or increment the journal counter when creating a checkpoint. If the -jc flag is used on the off-line server, the journal counter will be incremented and will cause problems with subsequent replication with p4 pull.

Option 2: Use p4 replicate

The content in the off-line server will be as current as the latest master journal transaction successfully replicated and applied to the off-line server. See the related Knowledge Base article, Perforce Metadata Replication, for further details on the use of p4 replicate. Since p4 replicate is keeping the metadata on the off-line server up to date in real-time, the off-line checkpoint procedure is simply to checkpoint the off-line server without truncating the journal (-jd):

p4d -r D:\Offline_P4ROOT -jd checkpoint.mmddyyyy

Note the use of the -jd flag in which instructs the server to not truncate the journal or increment the journal counter when creating a checkpoint. If the -jc flag is used on the off-line server, the journal counter will be incremented and will cause problems with subsequent replication with p4 replicate.

Option 3: Manually restore truncated journal files from the production server

The content in the off-line server will be as current as the latest journal truncation and replay process. To take a checkpoint on the offline server:

  1. Truncate the journal file on the production server:

    p4 -p MASTER-HOST:MASTER-P4PORT admin journal D:\Offline_P4ROOT\truncated\journal 

    Or:

    p4d -r C:\P4ROOT -jj D:\Offline_P4ROOT\truncated\journal

    The p4d command above assumes the default running journal location. If your server configuration uses the P4JOURNAL environment variable or the -J option to p4d to relocate or rename the running journal file, you must use the -J option to p4d to tell the journal rotation command where the running journal file is located. For example, if the running journal were located at "D:\perforce_journals\journal":

    p4d -r C:\P4ROOT -J D:\perforce_journals\journal -jj D:\Offline_P4ROOT\truncated\journal

    Without an argument, the -jj flag and the p4 admin journal command place rotated journals in the production server P4ROOT directory. By providing a path argument, you can specify the location where the numbered journal is written. In this example, since the off-line backup directory is on the same machine as the production server root, we can automatically create the numbered journal in a location accessible to the off-line server. Otherwise, you would have to manually copy the truncated production journal to the off-line server, as in the checkpoint seeding process above. Note that the path provided above for the truncated journal includes a prefix ("journal"); assuming the journal counter was 123, then the truncated journal above would be "D:\Offline_P4ROOT\truncated\journal.jnl.123"

  2. Restore the production journal on the off-line server:

    p4d -r D:\Offline_P4ROOT -jr D:\Offline_P4ROOT\truncated\journal.jnl.123
  3. Checkpoint the off-line server without truncating the journal (-jd):

    p4d -r D:\Offline_P4ROOT -jd checkpoint.mmddyyyy
    

    Upon completion of this process there is an off-line checkpoint that can be used to rebuild your production server, should the need ever arise.

Note: The -jd flag instructs the server to not truncate the journal or increment the journal counter when creating a checkpoint. If the -jc flag is used on the off-line server, the journal counter is incremented and the next attempt to replay a production journal will fail, generating an "out of sequence" error.

Warning: If you create off-line checkpoints on the same system as the production Perforce Server, always specify the path to the Perforce server folder using the -r flag. This prevents inadvertently running any commands against your "live" Perforce database files.

Usage Notes

  • The production server journal can be truncated at arbitrary intervals, such as once a day or once an hour, depending on your particular requirements.

  • When the production journal is truncated (copied), the production server briefly stalls during the copy operation. This stall is often imperceptible, but might be noticeable for busy servers with large journal files. Regardless of this short stall, the journal copy operation is markedly faster than a checkpoint operation.

  • If you use option 3, make sure you restart the process periodically. Take a checkpoint on the production server, erase the db.* files on the off-line server, and restore the checkpoint onto the off-line server. This ensures that the off-line server is in sync with the data on the production server.

  • If you use option 1 or 2, the need to take and restore from a production-server checkpoint is less of a concern. These options are not a manual process like option 3. Checkpointing the main server and restoring periodically does add an extra level of certainty that data is being properly backed up. Other options are to create master server database files from the offline checkpoint taken from the replica server or to rotate between the master and replica servers as the production server occasionally. These procedures can ensure that the replica server or offline checkpoint is ready to be used in the case of an actual disaster or business need.

Please contact Perforce Support if you have any questions.

Related Links

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255