Distributing Perforce: Concepts
This chapter describes concepts common to all distributed Perforce installations.
Reference
Most of the material in this book assumes familiarity with the Perforce System Administrator's Guide
General considerations
Best practice consists of properly identifying all servers, making use of service users and structured logging, and observing good upgrade, backup, and diskspace management procedures.
For servers
Administration is greatly simplified if every server has a name and an ID. Use the p4 server to identify each server in your network.
Make use of service users; they can simplify the reading of logs, and provide authentication and audit trails for inter-server communication. Assign service users strong passwords.
Enable structured logging on all your services. Doing so can greatly simplify debugging and analysis, and is also required in order to use the p4 journaldbchecksums command to verify the integrity of a replica.
During upgrades
Distributed Perforce requires that servers, brokers, and proxies be at the same release level.
When upgrading, shut down the furthest-upstream service or commit server and permit the system to quiesce. Upgrade downstream services first, starting with the replica that is furthest downstream, working upstream towards the master or commit server. Keep downstream services stopped until the server immediately upstream has been upgraded.
Backup and maintenance guidelines
Basic operating considerations are as follows:
-
Server: follow the procedures in the Perforce System Administrator's Guide. In distributed environments, these procedures must be performed on the commit server and all edge servers. Backup requirements for replicas that are not edge servers will vary depending on your site's requirements. For notes on backing up and restoring edge servers, see “Backup and high availability / disaster recovery (HA/DR) planning”.
Any Perforce service can be configured to reject operations that reduce its diskspace below the limits defined by that service's
filesys.*.minconfigurables.Regularly monitor the integrity of your replicas by using the
integrity.csvstructured server log and the p4 journaldbchecksums command. See “Verifying Replica Integrity” for details. -
Broker: the broker stores no data locally; you must back up its configuration file manually.
-
Proxy: the proxy requires no backups and, if files are missing, automatically rebuilds its cache of data. The proxy contains no logic to detect when diskspace is running low. Periodically monitor your proxy to ensure it has sufficient diskspace for continued operation.
Linking Perforce services together
When using SSL to securely link servers, brokers, and proxies together, each link in the chain must trust the upstream link.
Furthermore, it is best practice (and is mandatory at security level 4) to use ticket-based authentication instead of password-based authentication. This means that each service user for each server in the chain must also have a valid login ticket for the upstream link in the chain.
Managing SSL keypairs
When configured to accept SSL connections, all server processes (p4d, p4p, p4broker), require a valid certificate and key pair on startup.
The process for creating a key pair is the same as it is for any
other server: set P4SSLDIR to a valid directory with
valid permissions, and use the following commands to generate pairs
of privatekey.txt and
certificate.txt files,
and make a record of the key's fingerprint.
-
Server: use p4d -Gc to create the key/certificate pair and p4d -Gf to display its fingerprint.
-
Broker: use p4broker -Gc to create the key/certificate pair and p4broker -Gf to display its fingerprint.
-
Proxy: use p4p -Gc to create the key/certificate pair and p4p -Gf to display its fingerprint.
You can also supply your own private key and certificate. Further information is available in the Perforce System Administrator's Guide.
Managing trust between Perforce services
The user that owns the server, broker, or proxy process is
typically a service user. As the administrator, you must create
P4TRUST file on behalf of the service user by
using the p4 trust command) that recognizes
the fingerprint of the upstream Perforce service.
By default, a user's P4TRUST file resides in
their home directory as .p4trust. Ensure that
the P4TRUST variable is correctly set so that when
the user (often a script or other automation tool) that actually
invokes the p4d, p4p, or
p4broker executable is able to read filename
to which P4TRUST points in the invoking user's
environment.
Further information is available in the Perforce System Administrator's Guide.
Managing tickets between Perforce services
When linking servers, brokers, and proxies together, each service user must be a valid service user at the upstream link, and it must be able to authenticate with a valid login ticket.
On the upstream server, use p4 user
to create a user of type service, and
p4 group to assign it to a group that
features a long or unlimited timeout.
Use p4 passwd to assign the service user
a strong password.
On the downstream server, use p4 login
to connect to the master server as the newly-created service
user, and create a login ticket for the service user that exists
on the downstream server. Ensure that the P4TICKET
variable is correctly set when the user (often a script or other
automation tool) that actually invokes the downstream service,
does so, so that the downstream service can correctly read the
ticket file and authenticate itself as the service user to the
upstream service.