Combined with a centralized authorization server (see Centralized authorization server (P4AUTH)), Perforce administrators can configure the Perforce Broker (see
Chapter 11, The Perforce Broker) to redirect commands to replica servers to balance load efficiently across an arbitrary number of replica servers.
|
•
|
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.
|
|
|
|
|
|
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 flag) 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.
|
|
|
Because p4 configure stores its data on the master server, all replica servers automatically pick up any changes you make.
|
|
|
A configuration mechanism that defines a server in terms of its offered services. In order 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.
|
|
|
A command to set or display the unique identifier for a Perforce 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.
|
|
|
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.
|
|
|
A new type of user intended for authentication of server-to-server communications. Service users have extremely limited access to the depot and do not consume Perforce licenses.
To make logs easier to read, create one service user on your master server for each replica or proxy in your network of Perforce Servers.
|
|
|
In -M readonly mode, the Perforce 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.
|
|
|
You can use the -T tableexcludelist flag with p4 pull to explicitly filter out updates to entire database tables.
Using the ClientDataFilter: and RevisionDataFilter: fields of the p4 server form can provide you with far more fine-grained control over what data is replicated. Use the -P pattern flag with p4 pull, but instead of specifying each pattern on the command line, use the Name: of the server whose p4 server spec holds the desired set of filter patterns.
|
p4d -D readonly
p4d -D ondemand
p4d -D none
lbr.replication
|
Replica servers can be configured to automatically reject user commands that attempt to modify archived depot files (the "library").
In -D readonly mode, the Perforce 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.
In -D ondemand mode, the Perforce Server accepts commands that read metadata, but does not transfer file archive contents from the master. ( p4 pull -u and p4 verify -t, which would otherwise transfer archive files, are disabled.) This mode is useful if both the master and replica are using a shared set of archive files stored on a common SAN, and you are interested in using the replica for metadata only as part of an HA/DR solution. It is also a useful way to create a replica server with its own archive space, consisting of only those files that have been explicitly fetched by users of that replica.
In -D none mode, the Perforce 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.
|
|
|
As with the Perforce Proxy, you can use P4TARGET to specify the master server (or, as of Release 2013.1, 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 and -D flags, or their equivalent db.replication and lbr.replication configurables, correctly specified.
|
|
|
Use the startup.n (where n is an integer) configurable to automatically spawn multiple p4 pull processes on startup.
|
|
|
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. (If you remove the state file, replication begins with an offset of zero, reseeding the replica from scratch.)
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.
|
|
|
|
Perforce's p4 pull command provides the most general solution for replication. Use
p4 pull to configure a replica server that:
|
•
|
uses the startup.n configurable to automatically spawn as many p4 pull processes as required.
|
|
•
|
The startup.n configurables are processed sequentially. Processing stops at the first gap in the numerical sequence; any commands after a gap are ignored.
|
Although you can run p4 pull from the command line for testing and debugging purposes, it's most useful when controlled by the
startup.n configurables, and in conjunction with named servers, service users, and centrally-managed configurations.
To set a Perforce server name, set the P4NAME environment variable or specify the
-In command line flag to
p4d when you start the server. Assigning names to servers is essential for configuring replication. Assigning server names permits most of the server configuration data to be stored in Perforce itself, as an alternative to using startup flags or environment values to specify configuration details. In replicated environments, named servers are a necessity, because
p4 configure settings are replicated from the master server along with other Perforce metadata.
You can use p4 configure on the master to control settings on
both the master and the replica, because configuration settings are part of a Perforce server's metadata and are replicated accordingly.
After the configuration data has been replicated, the two servers have different server monitoring levels. That is, if you run
p4 monitor show against
master:11111, you see both active and idle processes, because for the server named
master, the
monitor configurable is set to
2. If you run
p4 monitor show against
replica:22222, only active processes are shown, because for the
Replica1 server,
monitor is
1.
Because the master (and each replica) is likely to have its own journal and checkpoint, it is good practice to use the
journalPrefix configurable (for each named server) to ensure that their prefixes are unique:
You can further define a set of services offered by a Perforce server by using the p4 server and
p4 serverid commands. At present, the only replication configuration that requires the use of
p4 server is the build farm replica. It is good practice, however, to define all servers on your network.
The p4 serverid command creates (or updates) a small text file named
server.id. The
server.id file always resides in a server's root directory.
The p4 server command can be used to maintain a list of all servers known to your installation. It can also be used to create a unique server ID that can be passed to the
p4 serverid command, and to define the services offered by any server that, upon startup, reads that server ID from a
server.id file. The
p4 server command can also be used to set a server's name (
P4NAME).
There are three types of Perforce users: standard users,
operator users, and
service users. A
standard user is a traditional user of Perforce, an
operator user is intended for human or automated system administrators, and a
service user is used for server-to-server authentication, as part of the replication process.
Creating a service user for each master, replica, or proxy server greatly simplifies the task of interpreting your server logs. Service users can also help you improve security, by requiring that your replica servers have valid login tickets before they can communicate with the master server. Service users do not consume Perforce licenses.
User: service1
Email: services@example.com
FullName: Service User for Replica Server 1
Type: service
|
By default, the output of p4 users omits service users. To include service users, run
p4 users -a.
A newly-created service user that is not a member of any groups is subject to the default ticket timeout of 12 hours. To avoid issues that arise when a service user's ticket ceases to be valid, create a group for your service users that features an extremely long timeout, or to
unlimited. On the master server, issue the following command:
Add service1 to the list of
Users: in the group, and set the
Timeout: and
PasswordTimeout: values to a large value or to
unlimited.
Group: service_users
Timeout: unlimited
PasswordTimeout: unlimited
Subgroups:
Owners:
Users:
service1
|
On the master server, use p4 protect to grant the service user
super permission. Service users are tightly restricted in the commands they can run, so granting them
super permission is safe.
When you start a replica that points to a master server with P4TARGET, you must specify both the
-M (metadata access) and a
-D (depot access) flags, or set the configurables
db.replication (access to metadata) and
lbr.replication (access the depot's library of versioned files) to control which Perforce commands are permitted or rejected by the replica server.
Set P4TARGET to the the fully-qualified domain name or IP address of the master server from which a replica server is to retrieve its data. You can set
P4TARGET explicitly, specify it on the
p4d command line with the
-t host:port flag, or you can use
p4 configure to set a
P4TARGET for each named replica server. .
If you specify a target, p4d examines its configuration for
startup.n commands: if no valid
p4 pull commands are found,
p4d runs and waits for the user to manually start a
p4 pull command. If you omit a target,
p4d assumes the existence of an external metadata replication source such as
p4 replicate. See
p4 pull vs. p4 replicate for details.
Where n represents the order in which the commands are executed: the command specified for
startup.1 runs first, then the command for
startup.2, and so on. The only valid startup command is
p4 pull.
Perforce also supports a more limited form of replication based on the p4 replicate command. This command does not replicate file content, but supports filtering of metadata on a per-table basis.
For more information about p4 replicate, see "Perforce Metadata Replication" in the Perforce Knowledge Base:
To encrypt the connection between a replica server and its end users, the replica must have its own valid private key and certificate pair in the directory specified by its
P4SSLDIR environment variable. Certificate and key generation and management for replica servers works the same as it does for the (master) server. See
Key and certificate management. The users' Perforce applications must be configured to trust the fingerprint of the replica server.
To encrypt the connection between a replica server and its master, the replica must be configured so as to trust the fingerprint of the master server. That is, the user that runs the replica
p4d (typically a service user) must create a
P4TRUST file (using
p4 trust) that recognizes the fingerprint of the
master Perforce Server.
If you are using p4 pull for both metadata and
p4 pull -u for versioned files, start your replica server with
p4d -t host:port -Mreadonly -Dreadonly. Commands that require read-only access to server metadata and to depot files will succeed. Commands that attempt to write to server metadata and/or depot files will fail gracefully.
To use p4 pull for metadata-only replication, start the server with
p4d -t host:port -Mreadonly -Dnone. You must specify a target. Do not configure the server to spawn any
p4 pull -u commands that would replicate the depot files.
|
|
Replication is asynchronous, and a replicated server is not recommended as the sole means of backup or disaster recovery. Maintaining a separate set of database checkpoints and depot backups (whether on tape, remote storage, or other means) is advised. Disaster recovery and failover strategies are complex and site-specific. Perforce Consultants are available to assist organizations in the planning and deployment of disaster recovery and failover strategies. For details, see:
|
|
•
|
Your master server is named Master and is running on a host called master, using port 11111, and its server root directory is /p4/master
|
|
•
|
Your replica server will be named Replica1 and will be configured to run on a host machine named replica, using port 22222, and its root directory will be /p4/replica.
|
|
|
You cannot define P4NAME using the p4 configure command, because a server must know its own name to use values set by p4 configure.
You cannot define P4ROOT using the p4 configure command, to avoid the risk of specifying an incorrect server root.
|
To define the behavior of the replica, you enter configuration information into the master server's
db.config file using the
p4 configure set command. Configure the master server first; its settings will be replicated to the replica later.
|
1.
|
To set the server named Replica1 to use master:11111 as the master server to pull metadata and versioned files, issue the command:
|
|
3.
|
Set the Replica1 server configurable to 1, which is equivalent to specifying the " -vserver=1" server startup flag:
|
Each p4 pull -u command creates a separate thread for replicating archive data. Heavily-loaded servers might require more threads, if archive data transfer begins to lag behind the replication of metadata. To determine if you need more
p4 pull -u processes, read the contents of the
rdb.lbr table, which records the archive data transferred from the master Perforce server to the replica.
If p4 pull -l -s indicates a large number of pending transfers, consider adding more "
p4 pull -u"
startup.n commands to address the problem.
|
6.
|
Set the db.replication (metadata access) and lbr.replication (depot file access) configurables to readonly:
|
|
9.
|
Set the Replica1 configurable for the serviceUser to service.
|
|
5.
|
To create a valid ticket file, use p4 login to connect to the master server and obtain a ticket on behalf of the replica server's service user. On the machine that will host the replica server, run:
|
|
•
|
A target server of master:11111, which is equivalent to specifying -t master:11111 on the command line
|
|
•
|
Both db.replication and lbr.replication set to readonly, which is equivalent to specifying -M readonly -D readonly on the command line
|
|
•
|
A series of p4 pull commands configured to run when the master server starts
|
To name your server Replica1, set
P4NAME or specify the
-In flag and start the replica as follows:
When the replica starts, all of the master server's configuration information is read from the replica's copy of the
db.config table (which you copied earlier). The replica then spawns three
p4 pull threads: one to poll the master server for metadata, and two to poll the master server for versioned files.
To confirm that the p4 pull commands (specified in
Replica1's
startup.n configurations) are running , issue the following command:
If the p4 pull and/or
p4 pull -u processes are terminated, read-only commands will continue to work for replica users as long as the replica server's
p4d is running,
|
|
Replica servers in -M readonly -D readonly mode will retrieve versioned files from master servers even if started without a p4 pull -u command to replicate versioned files to the replica. Such servers act as "on-demand" replicas, as do servers running in -M readonly -D ondemand mode or with their lbr.replication configurable set to ondemand.
Administrators: be aware that creating an on-demand replica of this sort can still affect server performance or resource consumption, for example, if a user enters a command such as " p4 print //...", which reads every file in the depot.
|
When you copied the versioned files from the master server to the replica server, you relied on the operating system to transfer the files. To determine whether data was corrupted in the process, run
p4 verify on the replica server:
Any errors that are present on the replica but not on the master indicate corruption of the data in transit or while being written to disk during the original copy operation. (Run
p4 verify on a regular basis, because a failover server's storage is just as vulnerable to corruption as a production server.)
You can perform all normal operations against your master server (p4 -p master:11111 command). To reduce the load on the master server, direct reporting (read-only) commands to the replica (
p4 -p replica:22222 command). Because the replica is running in
-M readonly -D readonly mode, commands that read both metadata and depot file contents are available, and reporting commands (such as
p4 annotate,
p4 changes,
p4 filelog,
p4 diff2,
p4 jobs, and others) work normally. However, commands that update the server's metadata or depot files are blocked.
Some scenarios are relatively straightforward: consider a command such as p4 sync. A plain
p4 sync fails, because whenever you sync your workspace, the Perforce Server must update its metadata (the "have" list, which is stored in the
db.have table). Instead, use
p4 sync -p to populate a workspace without updating the have list:
Some commands affect metadata in more subtle ways. For example, many Perforce commands update the last-update time that is associated with a specification (for example, a user or client specification). Attempting to use such commands on replica servers produces errors unless you use the
-o flag. For example,
p4 client (which updates the
Update: and
Access: fields of the client specification) fails:
However, p4 client -o works:
If a command is blocked due to an implicit attempt to write to the server's metadata, consider workarounds such as those described above. (Some commands, like
p4 submit, always fail, because they attempt to write to the replica server's depot files; these commands are blocked by the
-D readonly flag.)
You can use the Perforce Broker with a replica server to redirect read-only commands to replica servers. This approach enables all your users to connect to the same
host:port setting (the broker). In this configuration, the broker is configured to transparently redirect key commands to whichever Perforce Server is appropriate to the task at hand.
The Perforce Proxy is easier to configure and maintain, but caches only file content; it holds no metadata. A forwarding replica caches both file content and metadata, and can therefore process many commands without requesting additional data from the master server. This behavior enables a forwarding replica to offload more tasks from the master server and provides improved performance. The trade-off is that a forwarding replica requires a higher level of machine provisioning and administrative considerations compared to a proxy.
A read-only replica rejects commands that update metadata; a forwarding replica does not reject such commands, but forwards them to the master server for processing, and then waits for the metadata update to be processed by the master server and returned to the forwarding replica. Although users connected to the forwarding replica cannot write to the replica's metadata, they nevertheless receive a consistent view of the database.
The following example assumes an environment with a regular server named master, and a forwarding replica server named
fwd-replica on a host named
forward.
ServerID: fwd-1667 Name: fwd-replica Type: server Services: forwarding-replica Address: tcp:forward:1667 Description: Forwarding replica pointing to master:1666
|
When the replica server with the serverID: of
fwd-1667 (which was previously assigned the
Name: of
fwd-replica) pulls its configuration from the master server, its
rpl.forward.all configurable directs it to behave as a forwarding replica.
Continuous integration and other similar development processes can impose a significant workload on your Perforce infrastructure. Automated build processes frequently access the Perforce server to monitor recent changes and retrieve updated source files; their client workspace definitions and associated have lists also occupy storage and memory on the server.
With a build farm server, you can offload the workload of the automated build processes to a separate machine, and ensure that your main Perforce server's resources are available to your users for their normal day-to-day tasks.
One issue with implementing a build farm against a read-only replica is that under Perforce, both of those operations involve writes to metadata: in order to use a client workspace in a build environment, the workspace must contain some information (even if nothing more than the client workspace root) specific to the build environment, and in order for a build tool to efficiently sync a client workspace, a build server must be able to keep some record of which files have already been synced.
To address these issues, build farm replicas host their own local copies of certain metadata; in addition to the Perforce commands supported in a read-only replica environment, build farm replicas with support the
p4 client and
p4 sync commands when applied to workspaces that are bound to that replica.
The following example assumes an environment with a regular server named master, and a build farm replica server named
buildfarm1 on a host named
builder.
# A Perforce Server Specification.# # ServerID: The server identifier. # Type: The server type: server/broker/proxy. # Name: The P4NAME used by this server (optional). # Address: The P4PORT used by this server (optional). # Description: A short description of the server (optional). # Services: Services provided by this server, one of: # standard: standard Perforce server # replica: read-only replica server # broker: p4broker process # proxy: p4p caching proxy # forwarding-replica: replica which forwards update commands # build-server: replica which supports build farm integration # P4AUTH: server which provides central authentication # P4CHANGE: server which provides central change numbers # # Use 'p4 help server' to see more about server ids and services.
ServerID: master-1666 Name: master Type: server Services: standard Address: tcp:master:1666 Description: Master server - regular development work
|
ServerID: builder-1667 Name: buildfarm1 Type: server Services: build-server Address: tcp:builder:1667 Description: Build farm - bind workspaces to builder-1667 and use a port of tcp:builder:1667
|
At this point, there should be two servers in operation: a master server named master, with a server ID of
master-1666, and a
build-server replica named
buildfarm1, with a server ID of
builder-1667.
When the p4 client form appears, set the
ServerID: field to
builder-1667.
Because the client workspace build0001 is bound to
builder-1667, users on the master server are unaffected, but users on the build farm server are not only able to edit its specification, they are able to sync it:
In a real-world scenario, your organization's build engineers would re-configure your site's build system to use the new server by resetting their
P4PORT to point directly at the build farm server. Even in an environment in which continuous integration and automated build tools create a client workspace (and sync it) for every change submitted to the master server, performance on the master would be unaffected.
In a real-world scenario, performance on the master would likely improve for all users, as the number of read and write operations on the master server's database would be substantially reduced.
If there are database tables that you know your build farm replica does not require, consider using the
-F and
-T filter options to
p4 pull. Also consider specifying the
RevisionDataFilter: and
ClientDataFilter: fields of the replica's
p4 server form.
If your automation load should exceed the capacity of a single machine, you can configure additional build farm servers. There is no limit to the number of build farm servers that you may operate in your installation.
As part of an HA/DR solution, one typically wants to ensure that all the metadata and all the versioned files are replicated. In most other use cases, particularly build farms and/or forwarding replicas, this leads to a great deal of redundant data being transferred.
It is often advantageous to configure your replica servers to filter in (or out) data on client workspaces and file revisions. For example, developers working on one project at a remote site do not typically need to know the state of every client workspace at other offices where other projects are being developed, and build farms don't require access to the endless stream of changes to office documents and spreadsheets associated with a typical large enterprise.
The simplest way to filter metadata is by using the -T tableexcludelist flag with
p4 pull command. If you know, for example, that a build farm has no need to refer to
any of your users' have lists or the state of their client workspaces, you can filter out
db.have and
db.client entirely with
p4 pull -T db.have,db.client.
Excluding entire database tables is a coarse-grained method of managing the amount of data passed between servers, requires some knowledge of which tables are most likely to be referred to during Perforce command operations, and furthermore, offers no means of control over which versioned files are replicated.
You can gain much more fine-grained control over what data is replicated by using the ClientDataFilter: and
RevisionDataFilter: fields of the
p4 server form. These options enable you to replicate (or exclude from replication) those portions of your server's metadata and versioned files that are of interest at the replica site.
ServerID: site1-1668 Name: site1backup Type: server Services: replica Address: tcp:site1bak:1668 Description: Replicate all client workspace data, except the states of workspaces of users at sites 2 and 3. Do not replicate .mp4 video files, which tend to be large ClientDataFilter: -//site2-ws-* -//site3-ws-* RevisionDataFilter: -//....mp4
|
To further illustrate the concept, consider a build farm replica scenario. The ongoing work of the organization (whether it be code, business documents, or the latest video commercial) can be stored anywhere in the depot, but this build farm is dedicated to building releasable products, and has no need to have the rest of the organization's output at its immediate disposal:
Releasable code is placed into //depot/releases/... and automated builds are based on these changes. Changes to other portions of the depot, as well as the states of individual workers' client workspaces, are filtered out:
ServerID: builder-1669 Name: relbuild
Type: server Services: build-server Address: tcp:built:1669 Description: Exclude all client workspace data Replicate only revisions in release branches ClientDataFilter: -//... RevisionDataFilter: -//... //depot/releases/...
|
The p4 pull thread that pulls metadata for replication filters out all client workspace data (including the have lists) of all users.
The p4 pull -u thread(s) ignore all changes on the master except those that affect revisions in the
//depot/releases/... branch, which are the only ones of interest to a build farm.
|
•
|
Large numbers of "Perforce password (P4PASSWD) invalid or unset" errors in the replica log indicate that the service user has not been logged in or that the P4TICKETS file is not writable.
|
In the case of a read-only directory or P4TICKETS file,
p4 login appears to succeed, but
p4 login -s generates the "invalid or unset" error. Ensure that the
P4TICKETS file exists and is writable by the replica server.
|
•
|
Users of P4V and forwarding replicas are urged to upgrade to P4V 2012.1 or higher. Perforce applications older than 2012.1 that attempt to use a forwarding replica can, under certain circumstances, require the user to log in twice to obtain two tickets: one for the first read (from the forwarding replica), and a separate ticket for the first write attempt (forwarded to the master) requires a separate ticket. This confusing behavior is resolved if P4V 2012.1 or higher is used.
|
|
•
|
Although replicas can be chained together as of Release 2013.1, (that is, a replica's P4TARGET can be another replica, as well as from a central server), it is the administrator's responsibility to ensure that no loops are inadvertently created in this process. Certain multi-level replication scenarios are permissible, but pointless; for example, a forwarding replica of a read-only replica offers no advantage because the read-only replica will merely reject all writes forwarded to it. Please contact Perforce technical support for guidance if you are considering a multi-level replica installation.
|
Copyright 1997-2013 Perforce Software.
