Perforce Public Knowledge Base - Installing a Helix Replica Server
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Installing a Helix Replica Server

« Go Back



How do I install a Helix Replica Server?



Additional details can be found in the Perforce Replication section of the Administration Guide for multi-site deployment, the canonical reference for Helix Server multi-site configuration and administration.

There are different types of Helix Replica servers. Review your requirements and choose a replica type that best suits your needs.

System Requirements

  • As a general rule, all replica servers must be at the same release level or at a release later as the master server. Any functionality that requires an upgrade for the master requires an upgrade for the replica, and vice versa.

  • ​All replica servers must have the same Unicode setting as the master server.

  • All replica servers must be hosted on a filesystem with the same case-sensitivity behavior as the master server’s filesystem.

  • p4 pull (when replicating metadata) does not read compressed journals. The master server must not compress journals until the replica server has fetched all journal records from older journals. Only one metadata-updating p4 pull thread may be active at one time.

  • Helix Server releases 2015.1 and later that are configured as replicas don't require a license file; they use the master license. If the replica serves as a failover server for the master, a duplicate license file is recommended. If using a server release prior to 2015.1, a duplicate license file is required on the replica. Duplicate server licenses can be requested here.

  • The master and replica servers must have the same time zone setting.

  • A current checkpoint and versioned files from the master server are required for initial seeding of the replica server.

The instructions below detail creating a read-only replica server. The read-only replica maintains complete replicated copies of master server metadata and versioned file content and provides the following capabilities:

  • Used by itself or in conjunction with a p4broker to offload read-only commands from the master server

  • Enables offline checkpoint operations preventing master server downtime for checkpoint operations

  • Can be used as a warm stand-by server for disaster recovery

For this example:

  • The master server is named hiss on port 1666

  • The replica server is named gabriel running on port 1669

  • The replica server root directory is /p4/1/root

  • The service user is named service

  • The replica versioned files (archive files) are not shared with the master. (This would require lbr.replication=ondemand)

On the Master Server

To configure and define the behavior of the replica, you enter configuration information into the master server’s global configuration table (db.config) using the p4 configure set command. Run all commands in this section as a super user connected to the master server.

Create the replica configuration

Note: P4NAME should also be set for Windows servers.

To have gabriel function as a read-only replica create a server specification on the master:

p4 server gabriel
ServerID:       gabriel
Type:   server
Services:       replica
        Read-only replica pointing to hiss:1666

p4 configure set gabriel#P4TARGET=hiss:1666
p4 configure set gabriel#db.replication=readonly 
p4 configure set gabriel#lbr.replication=readonly
p4 configure set gabriel#startup.1="pull -i 1" 
p4 configure set gabriel#startup.2="pull -u -i 1"
p4 configure set gabriel#startup.3="pull -u -i 1"
p4 configure set gabriel#rpl.compress=4
p4 configure set gabriel#P4LOG=replicaLog.txt
p4 configure set gabriel#server=3
p4 configure set gabriel#monitor=2
p4 configure set gabriel#serviceUser=service
p4 configure set gabriel#P4TICKETS=/p4/1/.p4tickets
p4 configure set gabriel#journalPrefix=/p4/1/checkpoints/backup


The P4PORT of the upstream master from which this replica retrieves its data.


The metadata (db) and depot file (lbr) access are set to readonly to configure both metadata and versioned file replication from the master.


Startup threads are pull commands that start when the replica server starts and handle journal and versioned file replication. The startup.1 pull thread handles metadata replication and startup.2 and startup.3 pull threads handle versioned file data (-u).


Set rpl.compress=4 to compress the journal data stream between master and replica.


Unique log name for the replica server.


Sets log level detail in the replica server log.


Enables process monitoring on the replica using p4 monitor show.


Set the serviceUser used for replication to service.


The P4TICKETS location for the service user login ticket used by the replication process.


  1. The journalPrefix variable specifies an existing directory and an arbitrary name where numbered journals on the master server are located. For example, "journalPrefix=/p4/1/checkpoints/backup" specifies "/p4/1/checkpoints" as the directory containing numbered journals on the master server, and "backup" is part of the filename that will be used when creating numbered journals and checkpoints.

    P4NAME (for Windows):

    In addition, Windows servers should set P4NAME. From a "Run as administrator" command prompt, create a variable P4NAME for the Perforce service. To set P4NAME on Windows machines:

    p4 set -S Perforce P4NAME=gabriel
  2. Create and configure the service user account used for replication

    Create the service user account and add 'Type: service' to the user specification:

    p4 user -f service
    Type: service

    Set the service user password:

    p4 passwd service

    Add the service user to a group with an unlimited timeout:

    p4 group service_group
    Users: service
    Timeout: unlimited

    Grant super access to the service user in the protections table:

    p4 protect
    super user service * //...

    Service users are restricted in the commands they can run, so granting super permission is safe. It is good practice to set the security level of all your Helix Servers to at least 3, so as to require a strong password for the service user, and ideally to 4, to ensure that only authenticated service users may attempt to perform replica or remote depot transactions.

  3. Checkpoint the master server

    p4 admin checkpoint -Z
    Checkpointing to checkpoint.42.gz...
    MD5 (checkpoint.42) = 2A8D6E594F2522F03CB5E9C9A43665BF
    Rotating journal to journal.41...
    p4 journals -F type=checkpoint -m1 -T jfile 
    ... jfile checkpoint.42.gz

    Note: The -Z option to p4 admin checkpoint compresses the checkpoint but not the rotated journal. Going forward, rotated master journals can only be compressed when the replica has processed all journal transactions within them. Update your procedures for master server checkpoint and journal rotation commands to use the -Z option in place of -z with p4 admin checkpoint, p4d -jj, or p4d -jc, and don't use -z with p4 admin journal. Use p4 pull -lj against the replica which reports a line on the replica journal state that includes a journal sequence number.

    For example:

    ​Current replica journal state is:    Journal 45,    Sequence 14818.

    ​indicates the replica is currently processing journal 45 on the master so it would be safe to manually compress rotated master journals with a sequence number below 45. Note, if more than one replica is configured for a single master, all replicas need to have processed a rotated master journal before it can be compressed.

On the Replica

Carry out the following steps on the replica server host machine:

  1. Restore the master checkpoint to the replica P4ROOT

    p4d -r /p4/1/root -z -jr checkpoint.42.gz

    Requires copying the checkpoint from the master to the replica. Create the replica P4ROOT directory if it doesn't already exist before running the checkpoint restore command above.

  2. Create the service user login ticket

    p4 -E P4TICKETS=/p4/1/.p4tickets -u service -p hiss:1666 login

    Ensure the value provided with the -E option above for P4TICKETS matches the location configured for the replica, and the value provided with the -p option matches the P4TARGET configured for the replica.

  3. Set the server name and start the replica server

    p4d -r /p4/1/root -xD gabriel
    p4d -r /p4/1/root -In gabriel -p gabriel:1669 -d

    ​On Windows, starting the server will typically involve starting the Windows service associated with the Perforce Server.

  4. Copy the Perforce versioned files from the master server to the replica

    You can use utilities like rsync on Linux or xcopy on Windows to copy the versioned files from master to replica. The location of the versioned files is based on the 'Map:' path setting for each depot and the setting of the server.depot.root configurable. The following command:

    p4 -F "%name% %map%" -ztag depots

    Produces a list of depot names and their 'Map:' path settings. Relative depot map paths (depot/...) are relative to P4ROOT or to server.depot.root if it has been configured. Absolute depot map paths point directly the location of versioned file storage for that depot.

  5. Check the replication status

    p4 -p gabriel:1669 login 
    p4 -p gabriel:1669 pull -lj

Forwarding Replica

To turn the gabriel read-only replica into a forwarding replica, simply modify the server specification on the master:

p4 server gabriel
Services:       forwarding-replica
        Forwarding replica pointing to hiss:1666

Set the 'Services' field to forwarding-replica and provide a description. Once the server specification is replicated to gabriel, it will become a forwarding replica.


If the configuration isn't correct you may have to go back to the master, reconfigure as needed, and proceed again from master step 3 above by taking a new checkpoint to re-seed the replica with the proper configuration variables. If you simply missed one of the configuration variable settings on the master before taking the master checkpoint, it is possible to set the configuration data in db.config directly on the replica so you don't have to take another master checkpoint. See the KB article 3196 for details on using p4d -cset to set configuration variables directly on the replica.

Note: If you make changes using p4d -cset directly to db.config on the replica, also run the corresponding p4 configure set commands on the master so the configurations match.

If the p4 pull -lj shows that replication isn't working, check the end of your replica log first. For example, you may see:

Perforce password (P4PASSWD) invalid or unset.
Perforce server error:
2011/11/23 19:12:16 pid 3145 service@1669 background 'pull -i 1'
Perforce password (P4PASSWD) invalid or unset.

This indicates the service user failed to authenticate, possibly due to a problem with the service user login ticket. Other useful commands for debugging include p4 monitor show and p4 configure show to check the replica configuration.

Related Links



Was this article helpful?



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

Characters Remaining: 255