Perforce 2007.3 System Administrator's Guide


<< Previous Chapter Perforce and Windows	Table of Contents Index Perforce on the Web	Next Chapter >> Perforce Server (p4d) Reference

Chapter 9
Perforce Proxy

Perforce is built to handle distributed development in a wide range of network topologies. Where bandwidth to remote sites is limited, P4P, the Perforce Proxy, improves performance by mediating between Perforce clients and servers to cache frequently transmitted file revisions. By intercepting requests for cached file revisions, P4P reduces demand on the Perforce server and network.

To improve performance obtained by multiple Perforce clients accessing a central Perforce server across a WAN, configure P4P on the side of the network close to the clients and configure the clients to access P4P; then configure P4P to access the central Perforce server. (On a LAN, you can also obtain performance improvements by setting up proxies to divert workload from the central server's CPU and disks.)

The following diagram illustrates a typical P4P configuration.

In this configuration, file revisions requested by users at a remote development site are fetched first from a central Perforce server (p4d running on central) and transferred over a relatively slow WAN. Subsequent requests for that same revision, however, are delivered from the Perforce Proxy, (p4p running on outpost), over the remote development site's LAN, reducing both network traffic across the WAN and CPU load on the central server.

System requirements

To use Perforce Proxy, you must have:

A Perforce server at Release 2002.2 or higher
Sufficient disk space on the proxy host to store a cache of file revisions

Installing P4P

UNIX

To install P4P on UNIX, do the following:

Download the p4p executable 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 p4p will listen for requests from Perforce client programs.
Select the target Perforce server (P4TARGET) for which this proxy will cache.

Windows

Install P4P from the Windows installer's custom/administrator installation dialog.

Running P4P

To run P4P, invoke the p4p executable, configuring it with environment variables or command-line flags. Flags you specify on the command line override environment variable settings.

For example, the following command line starts a proxy that communicates with a central Perforce server located on a host named central, listening on port 1666.

p4p -p 1999 -t central:1666 -r /var/proxyroot

To use the proxy, Perforce client programs connect to P4P on port 1999 on the machine where the proxy runs. P4P file revisions are stored under a directory named /var/proxyroot.

Running P4P as a Windows service

To run P4P as a Windows service, either install P4P from the Windows installer, or specify the -s flag when you invoke p4p.exe, or rename the P4P executable to p4ps.exe. Set the P4POPTIONS variable to hold command-line flags to p4p.exe or p4s.exe for which there are no environment variables.

P4P flags

The following command-line flags specific to the proxy are supported.


Flag	Meaning
`-c`	Do not compress files transmitted from the Perforce server to P4P. (This option reduces CPU load on the central server at the expense of slightly higher bandwidth consumption.)
`-d`	Run as daemon - fork first, then run (UNIX only).
`-f`	Do not fork - run as a single-threaded server (UNIX only).
`-i`	Run for `inetd` (socket on `stdin`/`stdout` - UNIX only).
`-q`	Run quietly; suppress startup messages.
`-s`	Run as an NT service (Windows only). Running `p4p.exe -s` is equivalent to invoking `p4ps.exe`.
`-e` `size`	Cache only those files that are larger than `size` bytes. Default is `P4PFSIZE`, or zero (cache all files) if `P4PFSIZE` is not set.

The following general options are supported.


Flag	Meaning
`-h` or `-?`	Display a help message.
`-L` `logfile`	Specify the location of the log file. Default is `P4LOG`, or the directory from which `p4p` is started if `P4LOG` is not set.
`-p` `port`	Specify the port on which P4P will listen for requests from Perforce client programs. Default is `P4PORT`, or 1666 if `P4PORT` is not set.
`-r` `root`	Specify the directory where revisions are cached. Default is `P4PCACHE`, or the directory from which `p4p` is started if `P4PCACHE` is not set.
`-t` `port`	Specify the port of the target Perforce server (that is, the Perforce server for which P4P acts as a proxy). Default is `P4TARGET` or `perforce:1666` if `P4TARGET` is not set.
`-v` `level`	Specifies server trace level. Debug messages are stored in the proxy server's log file. Debug messages from `p4p` are not passed through to `p4d`, and debug messages from `p4d` are not through to instances of `p4p`. Default is `P4DEBUG`, or none if `P4DEBUG` is not set.
`-V`	Display the version of the Perforce Proxy.

Administering P4P

No backups required

You never need to back up the P4P cache directory.

If necessary, P4P reconstructs the cache based on Perforce server metadata.

Stopping P4P

P4P is effectively stateless; to stop P4P under UNIX, kill the p4p process with SIGTERM or SIGKILL. Under Windows, click End Process in the Task Manager.

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.


Warning!	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. It is safe to delete the proxy's cached files while the proxy is running.

Determining if your Perforce client is using the proxy

If your Perforce client program is using the proxy, the proxy's version information appears in the output of p4 info.

For example, if a Perforce server is running on central:1666 and you direct your Perforce client to a Perforce Proxy running on outpost:1999, the output of p4 info resembles the following:


`$ export P4PORT=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:55768 Server address: central:1666 Server root: /src/p4root Server date: 2002/10/14 15:03:05 -0700 PDT Server version: P4D/FREEBSD4/main/36609 (2002/09/30) Proxy version: P4P/SOLARIS26/main/36884 (2002/10/14) Server license: P4 Admin <p4adm> 20 users (expires 2003/02/01)`

P4P and protections

To apply the IP address of a Perforce Proxy user's workstation against the protections table, prepend the string proxy- to the workstation's IP address.

For instance, consider an organization with a remote development site with workstations on a subnet of 192.168.10.0/24. The organization also has a central office where local development takes place; the central office exists on the 10.0.0.0/8 subnet. A Perforce server resides on the 10.0.0.0/8 subnet, and a Perforce Proxy resides on the 192.168.10.0/24 subnet. Users at the remote site belong to the group remotedev, and occasionally visit the central office.

To ensure that members of the remotedev group use the proxy while working at the remote site, but do not use the proxy when visiting the local site, add the following lines to your protections table:


`list group remotedev 192.168.10.0/24 -//... write group remotedev proxy-192.168.10.0/24 //... list group remotedev proxy-10.0.0.0/8 -//... write group remotedev 10.0.0.0/8 //...`

The first line denies list access to all users in the remotedev group if they attempt to access Perforce without using the proxy from their workstations in the 192.168.10.0/24 subnet. The second line grants write access to all users in remotedev if they are using a Perforce Proxy server and are working from the 192.168.10.0/24 subnet. Users of workstations at the remote site must use the proxy.

Similarly, the third and fourth lines deny list access to remotedev users when they attempt to use the proxy from workstations on the central office's subnet (10.0.0.0/8), but grant write access to remotedev users who access the Perforce server directly from workstations on the central office's subnet. When visiting the local site, users from the remotedev group must access the Perforce server directly.

Determining if specific files are being delivered from the proxy

Use the -Zproxyverbose flag with p4 to display messages indicating whether file revisions are coming from the proxy (p4p) or the central server (p4d).

For instance:


`$ 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`

Maximizing performance improvement

Reducing server CPU usage by disabling file compression

By default, P4P compresses communication with the central Perforce server, imposing additional overhead on the server.

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 server) decompresses the binary files from its cache before sending them to Perforce clients.

Network topologies versus P4P

If network bandwidth on the same subnet as the central Perforce server is nearly saturated, deploying proxy servers on the same subnet will not likely result in a performance improvement. Instead, deploy the proxy servers on the other side of a router so that the traffic from the clients to the proxy server is isolated to a subnet separate from the subnet containing the central Perforce server.

For example:

Deploying an additional proxy server on a subnet when network bandwidth on the subnet is nearly saturated will not likely result in a performance improvement. Instead, split the subnet into multiple subnets and deploy a proxy server in each resulting subnet.

In the illustrated configuration, a server room houses a company's Perforce server (p4d), a network storage device (NAS), and a database server (RDBMS). The server room's network segment is saturated by heavy loads placed on it by a sales force constantly querying a database for live updates, and by developers and graphic artists frequently accessing large files through the Perforce server.

Deploying two instances of Perforce Proxy (one on the developers' subnet, and one on the graphic artists' subnet) enables all three groups to benefit from improved performance due to decreased use on the server room's network segment.

Preloading the cache directory for optimal initial performance

P4P stores file revisions only when one of its clients 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.

After starting P4P, you can effectively prefetch the cache directory by creating a dedicated client workspace and syncing it to the head revision. All other clients that subsequently connect to the proxy immediately obtain the performance improvements provided by P4P. For example, a development site located in Asia with a P4P server targeting a Perforce server in North America can preload its cache directory by using an automated job that runs a p4 sync against the entire Perforce depot after most work at the North American site has been completed, but before its own developers arrive for work.

By default, 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 the client machine has slower I/O performance than the machine running the Perforce 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 -Zproxyload 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 P4P cache root is /disk1/proxy, and the Perforce server it supports has two depots named //depot and //released, you can split data across disks, storing //depot on disk1 and //released on disk2 as follows:


`mkdir /disk2/proxy/released cd /disk1/proxy ln -s /disk2/proxy/released released`

The symbolic link means that when P4P attempts to cache files in the //released depot to /disk1/proxy/released, the files are stored on /disk2/proxy/released.