This topic assumes you have read Deployment architecture.
To improve performance obtained by multiple Helix Server users accessing a shared Helix Server repository across a WAN,
- Configure P4P on the side of the network close to the users.
- Configure the users to access the service through P4P.
- Configure P4P to access the master Perforce service.
To use Helix Proxy, you must have:
- Helix Server release 2002.2 or later (2012.1 or later to use SSL)
- Sufficient disk space on the proxy host to store a cache of file revisions
In addition to the basic steps described next, see:
To install P4P on UNIX or Linux, do the following:
- Download the
p4pexecutable to the machine on which you want to run the proxy.
- Select a directory on this machine (
P4PCACHE) in which to cache file revisions.
- Select a port (
P4PORT) on which
p4pwill listen for requests from Helix Server applications.
- Select the target
Helix Server (
P4TARGET) for which this proxy will cache.
Install P4P as an option when running the Helix Core Server installer for Windows:
Helix Proxy, invoke the
p4p executable, configuring it with environment
variables or command-line options. Options you specify on the command
line override environment variable settings.
$ p4p -p tcp64:[::]:1999 -t central:1666 -r /var/proxycacheroot
which starts a proxy that:
communicates with a central Helix Server located on a host named
centralthat listens for proxy requests on port
stores its cache of file revisions in its
/var/proxycacherootdirectory (See the
-roption under General options for P4P.)
To use the proxy,
applications connect to
1999 on the machine that runs the proxy. The proxy listens on
both the IPv6 and IPv4 transports.
See P4PORT in Helix Core Command-Line (P4) Reference.
Running P4P as a Windows service
as a Windows service, either install
from the Windows installer, or specify the
-s option when
p4p.exe, or rename the
To pass parameters to the P4Proxy service, set the
P4POPTIONS registry variable using the
p4 set command. For example, if you normally run the Proxy
with the command:
C:\> p4p -p 1999 -t ssl:mainserver:1666
You can set the
P4POPTIONS variable for a Windows service
Helix Proxy by setting the
service parameters as follows:
C:\> p4 set -S "Perforce Proxy" P4POPTIONS="-p 1999 -t ssl:mainserver:1666"
"Helix Proxy" service starts,
listens for plaintext connections on port 1999 and communicates with the
Helix Core Server
via SSL at
There are multiple types of proxy options.
Run as daemon - fork first, then run (UNIX only).
Do not fork - run as a single-threaded server (UNIX only).
Run quietly; suppress startup messages.
Do not compress data stream between the Helix Server to P4P. (This option reduces CPU load on the central server at the expense of slightly higher bandwidth consumption.)
Run as a Windows service (Windows only).
Disable cache fault coordination.
The proxy maintains a table of concurrent sync operations,
General options for P4P
Display a help message.
Display the version of the Helix Proxy.
Specify the directory where revisions are cached. Default is
Specify the directory where the proxy database is stored. See
This is the directory to use with the
Do not confuse the proxy's
Specify the location of the log file. Default is
Specify the port on which
will listen for requests from
applications. Default is
Specify the port of the target
(that is, the
Helix Server for which
acts as a proxy). Default is
Cache only those files that are larger than
For proxy servers, authenticate as the specified
Specifies server trace level. Debug messages are stored in the
proxy server’s log file. Debug messages from
For a full discussion with examples, see Using P4LOG.
Display (or set) the proxy server’s
Certificate-handling options for P4P
Generate SSL credentials files for the proxy: create a private
Display the fingerprint of the proxy’s public key, and exit.
Administrators can communicate this fingerprint to end users,
who can then use the
Proxy monitoring options
List pending archive transfers
List pending archive transfers, summarized
Set the file status interval in seconds.
0: (default) Monitoring disabled
1: Proxy monitors file transfers only
2: Proxy monitors all operations
3: Proxy monitors all traffic for all operations
Proxy monitoring interval, in seconds. If not set, defaults to 10 seconds.
Show currently-active connections and their status.
Proxy archive cache options
See the lbr.proxy.case configurable in Helix Core Command-Line (P4) Reference.
The following sections describe the tasks involved in administering a proxy.
No backups required
You never need to back up the P4P cache directory.
If necessary, P4P reconstructs the cache based on Helix Server metadata.
is effectively stateless; to stop
p4p process with
SIGKILL. Under Windows, click End
Process in the Task Manager.
After you have replaced the
p4p executable with the
upgraded version, you must also remove the
pdb.monitor files (if they exist) from the proxy root before
you restart the upgraded proxy.
Enabling SSL support
To encrypt the connection between a
and its end users, your proxy must have a valid private key and
certificate pair in the directory specified by its
environment variable. Certificate and key generation and management for
the proxy works the same as it does for the
Helix Core Server. See
Using SSL to encrypt connections to a Helix Server. The users'
applications must be configured to trust the fingerprint of the
To encrypt the connection between a
and its upstream
service, your proxy installation must be configured to trust the
fingerprint of the upstream
service. That is, the user that runs
p4p (typically a
service user) must create a
P4TRUST file (using
trust) that recognizes the fingerprint of the upstream
See the Knowledge Base article, "Enabling SSL Support for the Server/Broker/Proxy".
Defending from man-in-the-middle attacks
You can use the
net.mimcheck configurable to enable checks
for possible interception or modification of data. These settings are
pertinent for proxy administration:
- A value of 3 checks connections from clients, proxies, and brokers for TCP forwarding.
- A value of 5 requires that proxies, brokers, and all Helix Server intermediate servers have valid logged-in service users associated with them. This allows administrators to prevent unauthorized proxies and services from being used.
You must restart the server after changing the value of this
Helix Server has localized error messages (see Localizing server error messages),
you can localize your proxy’s error message output by shutting down the
proxy, copying the server’s
db.message file into the proxy
root, and restarting the proxy.
Managing disk space consumption
P4P caches file revisions in its cache directory. These revisions accumulate until you delete them. P4P does not delete its cached files or otherwise manage its consumption of disk space.
If you do not delete cached files, you will eventually run out of disk space. To recover disk space, remove files under the proxy’s root.
Although you do not need to stop the proxy to delete its cached files or the
pdb.lbr file, removing the cache or pdb.lbr file is NOT recommended during a sync operation because it might cause the following error: "Proxy could not update its cache".
If you delete files from the cache without stopping the proxy, you must
also delete the
pdb.lbr file at the proxy’s root directory.
(The proxy uses the
pdb.lbr file to keep track of which
files are scheduled for transfer, so that if multiple users
simultaneously request the same file, only one copy of the file is
Determining if your Helix Server applications are using the proxy
application is using the proxy, the proxy’s version information appears
in the output of
For example, if a
service is hosted at
ssl:central:1666 and you direct your
application to a
outpost:1999, the output of
info resembles the following:
$ export P4PORT=tcp:outpost:1999 $ p4 info User name: p4adm Client name: admin-temp Client host: remotesite22 Client root: /home/p4adm/tmp Current directory: /home/p4adm/tmp Client address: 192.168.0.123 Server address: central:1666 Server root: /usr/depot/p4d Server date: 2012/03/28 15:03:05 -0700 PDT Server uptime: 752:41:23 Server version: P4D/FREEBSD4/2012.1/406375 (2012/01/25) Server encryption: encrypted Proxy version: P4P/SOLARIS26/2012.1/406884 (2012/01/25) Server license: P4 Admin <p4adm> 20 users (expires 2013/01/01) Server license-ip: 10.0.0.2 Case handling: sensitive
P4P and protections
For setting protections on proxies and brokers, see "Proxy and protections" under Setting protections with p4 protect.
Determining if specific files are being delivered from the proxy
-Zproxyverbose option with
to display messages indicating whether file revisions are coming from the
p4p) or the central server
p4d). For example:
$ p4 -Zproxyverbose sync noncached.txt //depot/main/noncached.txt - refreshing /home/p4adm/tmp/noncached.txt $ p4 -Zproxyverbose sync cached.txt //depot/main/cached.txt - refreshing /home/p4adm/tmp/cached.txt File /home/p4adm/tmp/cached.txt delivered from proxy server
Case-sensitivity issues and the proxy
If you are running the proxy on a case-sensitive platform such as UNIX,
and your users are submitting files from case-insensitive platforms (such
as Windows), the default behavior of the proxy is to fold case. For example,
FILE.TXT can overwrite
In the case of text files and source code, the performance impact of
this behavior is negligible. If, however, you are dealing with large
binaries such as
.ISO images or
objects, there can be performance issues associated with this
After any change to
lbr.proxy.case, you must clear the
cache before restarting the proxy.
Maximizing performance improvement
In addition to the topics in this chapter, see the Support Knowledgebase article on tuning tips for "Proxy Performance", including how to minimize the syncing of small files.
Reducing server CPU usage by disabling file compression
compresses communication between itself and the
versioning service, imposing additional overhead on the service. To
disable compression, specify the
-c option when you invoke
p4p. This option is particularly effective if you
have excess network and disk capacity and are storing large numbers of
binary file revisions in the depot, because the proxy (rather than the
upstream versioning service) decompresses the binary files from its cache
before sending them to
Network topologies versus P4P
If network bandwidth on the subnet with the Perforce service is nearly saturated, deploy the proxies on the other side of a router so that the traffic from end users to the proxy is isolated to a subnet separate from the subnet containing the Perforce service. You might split the subnet into multiple subnets and deploy a proxy in each resulting subnet:
Preloading the cache directory for optimal initial performance
Helix Proxy stores file revisions only when one of its users submits a new revision to the depot or requests an existing revision from the depot. That is, file revisions are not prefetched. Performance gains from P4P occur only after file revisions are cached.
P4P, you can
prefetch the cache directory by creating a dedicated client
workspace and syncing it to the head revision. All other users who
subsequently connect to the proxy immediately obtain the performance
improvements provided by
P4P. For example, a
development site located in Asia with a
server targeting a
in North America can preload its cache directory by using an
automated job that runs a
against the entire
depot after most work at the North American site has been completed, but
before its own developers arrive for work.
p4 sync writes files to the client
workspace. If you have a dedicated client workspace that you use to
prefetch files for the proxy, however, this step is redundant. If this
machine has slower I/O performance than the machine running the
Helix Proxy, it can
also be time-consuming.
To preload the proxy’s cache without the redundant step of also writing
the files to the client workspace, use the
option when syncing. For example:
$ export P4CLIENT=prefetch $ p4 sync //depot/main/written.txt //depot/main/written.txt - refreshing /home/prefetch/main/written.txt $ p4 -Zproxyload sync //depot/main/nonwritten.txt //depot/main/nonwritten.txt - file(s) up-to-date.
Both files are now cached, but
nonwritten.txt is never
written to the the
prefetch client workspace. When
prefetching the entire depot, the time savings can be considerable.
Distributing disk space consumption
P4P stores revisions as if there were only one depot tree. If this approach stores too much file data onto one filesystem, you can use symbolic links to spread the revisions across multiple filesystems.
For instance, if the
cache root is
/disk1/proxy, and the
Helix Server it supports has two depots named
//released, you can split data across disks, storing
disk2 as follows:
$ mkdir /disk2/proxy/released $ cd /disk1/proxy $ ln -s /disk2/proxy/released released
The symbolic link means that when
attempts to cache files in the
//released depot to
/disk1/proxy/released, the files are stored on