Replication basics

Commands and configurables

Replication of Helix Servers depends upon certain commands, environment variables, and configurables:

Command or Feature Typical use case

p4 pull

A command that can replicate both metadata and versioned files, and report diagnostic information about pending content transfers.

A replica server can run multiple p4 pull commands against the same master server. To replicate both metadata and file contents, you must run two p4 pull threads simultaneously: one (and only one) p4 pull (without the -u option) thread to replicate the master server’s metadata, and one (or more) p4 pull -u threads to replicate updates to the server’s versioned files.

p4 configure

A configuration mechanism that supports multiple servers.

Because p4 configure stores its data on the master server, all replica servers automatically pick up any changes you make.

p4 server

A configuration mechanism that defines a server in terms of its offered services. To be effective, the ServerID: field in the p4 server form must correspond with the server’s server.id file as defined by the p4 serverid command.

p4 serverid

A command to set or display the unique identifier for a Helix Core Server. On startup, a server takes its ID from the contents of a server.id file in its root directory and examines the corresponding spec defined by the p4 server command.

Important

To avoid configuration problems, the value of serverID should always match the value of P4NAME if both are set. We recommend setting serverID, but support P4NAME for backward compatibility.

p4 verify -t

Causes the replica to schedule a transfer of the contents of any damaged or missing revisions.

The command reports BAD! or MISSING! files with (transfer scheduled) at the end of the line.

For the transfer to work on a replica with lbr.replication=cache, the replica should have one or more p4 pull -u threads configured (perhaps also using the --batch=N flag.)

Note

You can also run the p4 verify -S -t command on a replica to request re-transfer of a shelved archive that is missing or bad. Re-transferring a shelved archive from the master only works if the shelved archive is on the master:

  • the shelf was originally created on the master, or

  • the shelf was promoted from an edge server

Server names

P4NAME

Helix Servers can be identified and configured by name.

When you use p4 configure on your master server, you can specify different sets of configurables for each named server. Each named server, upon startup, refers to its own set of configurables, and ignores configurables set for other servers.

Important

To avoid configuration problems, the value of serverID should always match the value of P4NAME if both are set. We recommend setting serverID, but support P4NAME for backward compatibility.

Service users

serviceUser

A type of user intended for authentication of server-to-server communications. Service users have extremely limited access to the depot and do not consume Helix Server licenses.

To make logs easier to read, create one service user on your master server for each replica or proxy in your network of Helix Servers .

Metadata access

db.replication

Replica servers can be configured to automatically reject user commands that attempt to modify metadata (db.* files).

In readonly mode, the Helix Core Server denies any command that attempts to write to server metadata. In this mode, a command such as p4 sync (which updates the server’s have list) is rejected, but p4 sync -p (which populates a client workspace without updating the server’s have list) is accepted.

Metadata filtering

p4 server

Replica servers can be configured to filter in (or out) data on client workspaces and file revisions.

  • To provides fine-grained control over what data is replicated, using the ClientDataFilter:, RevisionDataFilter:, and ArchiveDataFilter: fields of the p4 server form.
    • Alternatively, to explicitly filter out updates to entire database tables, use the -T tableexcludelist option with p4 pull.
  • To create a filtered checkpoint based on a serverId, use the p4d command with the -P serverId -jd options.

Depot file access


lbr.replication

Replica servers can be configured to automatically reject user commands that attempt to modify archived depot files (the “library”).

  • In readonly mode, the Helix Core Server accepts commands that read depot files, but denies commands that write to them. In this mode, p4 describe can display the diffs associated with a changelist, but p4 submit is rejected.
    •  However, edge servers do have the capability to write some files, such as shelved files, to the depot.
    • A forwarding replica cannot write to archive files, but instead forwards the command to the master server.

  • In shared mode, the Helix Server accepts commands that read metadata, but does not transfer new files nor remove purged files from the master. (p4 pull -u and p4 verify -t, which would otherwise transfer archive files, are disabled.) If a file is not present in the archives, commands that reference that file will fail.

    This mode must be used when a replica directly shares the same physical archives as the target, whether by running on the same machine or via network sharing. This mode can also be used when an external archive synchronization technique, such as rsync, is used for archives.

  • In cache mode, the Helix Core Server permits commands that reference file content, but does not automatically transfer new files. Files that are purged from the target are removed from the replica when the purge operation is replicated. If a file is not present in the archives, the replica will retrieve it from the target server.
  • In none mode, the Helix Core Server denies any command that accesses the versioned files that make up the depot. In this mode, a command such as p4 describe changenum is rejected because the diffs displayed with a changelist require access to the versioned files, but p4 describe -s changenum (which describes a changelist without referring to the depot files in order to generate a set of diffs) is accepted.

Target server

P4TARGET

As with the Helix Proxy, you can use P4TARGET to specify the master server or another replica server to which a replica server points when retrieving its data.

You can set P4TARGET explicitly, or you can use p4 configure to set a P4TARGET for each named replica server.

A replica server with P4TARGET set must have both the -M (metadata access) and -D (depot access) options.

Alternatively, use the equivalent configurables:

Startup commands

startup.1

Use the startup.n (where n is an integer) configurable to automatically spawn multiple p4 pull processes on startup.

State file

statefile

Replica servers track the most recent journal position in a small text file that holds a byte offset. When you stop either the master server or a replica server, the most recent journal position is recorded on the replica in the state file.

Upon restart, the replica reads the state file and picks up where it left off. Do not alter this file or its contents. (When the state file is written, a temporary file is used and moved into place, which should preserve the existing state file if something goes wrong when updating it. If the state file is empty or missing, the replica server will re-fetch from the start of its last used journal position.)

By default, the state file is named state and it resides in the replica server’s root directory. You can specify a different file name by setting the statefile configurable.

P4Broker

The Helix Broker can be used for load balancing, command redirection, and more. See Helix Broker for details.

Warning

Replication requires uncompressed journals. Starting the master using the p4d -jc -z command breaks replication. Instead, use the -Z flag instead to prevent journals from being compressed.