Welcome to Perforce: Installing and Upgrading
This chapter describes how to install the Perforce service or upgrade an existing installation.
If you are upgrading an existing installation to Release 2005.1 or later, see the notes in Upgrading the Perforce service before proceeding.
This chapter includes a brief overview of things to consider at installation time, along with some basic security and administration tips. More detailed information on administrative tasks is found in later chapters.
Where the UNIX and Windows versions of Perforce differ, this manual notes the difference. For Windows-specific information, see “Perforce and Windows”.
Many of the examples in this book are based on the UNIX version of the Perforce service. In most cases, the examples apply equally to both Windows and UNIX installations.
The material for UNIX also applies to Mac OS X.
Perforce requires at least two executables: the Perforce service (p4d), and at least one Perforce application (such as p4 on UNIX, or p4.exe on Windows).
The Perforce service and applications are available from the Downloads page on the Perforce web site:
Go to the web page, select the files for your platform, and save the files to disk.
Although you can install p4 and p4d
in any directory, on UNIX, the Perforce applications typically reside in
/usr/local/bin, and the Perforce service is usually
located either in
/usr/local/bin or in its own server
root directory. You can install Perforce applications on any machine that
has TCP/IP access to the p4d host.
To limit access to the Perforce service's files, ensure that the p4d executable is owned and run by a Perforce user account that has been created for the purpose of running the Perforce service.
To maximize performance, configure the server root (
P4ROOT) to reside on
a local disk and not an NFS-mounted volume. Perforce's file-locking semantics work with NFS
mounts on Solaris 2.5.1 and later; some issues still remain regarding file locking on
noncommercial implementations of NFS (for instance, Linux and FreeBSD). It is best to place
metadata and journal data on separate drive.s
These issues affect only the Perforce server process (p4d). Perforce applications (such as p4, the Perforce Command-Line Client) have always been able to work with client workspaces on NFS-mounted drives, such as client workspaces located in users' home directories.
To start using Perforce:
Download the p4 and p4d applications for your platform from the Perforce web site.
Make the downloaded p4 and p4d files executable.
Create a server root directory to hold the Perforce database and versioned files.
Tell the Perforce service what port to listen to by specifying a TCP/IP port to p4d.
Start the Perforce service (p4d).
Set the p4d port and address for Perforce applications by setting the
Downloading the files and making them executable
On UNIX (or Mac OS X), you must make the p4 and p4d binaries executable. After you download the software, use the chmod command to make them executable, as follows:
chmod +x p4 chmod +x p4d
Creating a Perforce server root directory
The Perforce service stores all user-submitted files and system-generated metadata in files and subdirectories beneath its own root directory. This directory is called the server root.
To specify a server root, either set the environment variable
P4ROOT to point to the server root, or use the
when invoking p4d. Perforce applications never use
P4ROOT directory or environment variable;
p4d is the only process that uses the
Because all Perforce files are stored beneath the server root, the contents of the server root grow over time. See Installation and administration tips for a brief overview of diskspace requirements, and Disk space allocation for more detail.
The Perforce service requires no privileged access; there is no need to
run p4d as
root or any other
privileged user. For more information, see UNIX: Run p4d as a nonprivileged user.
The server root can be located anywhere, but the account that runs
p4d must have
execute permissions on
the server root and all directories beneath it. For security purposes,
umask(1) file-creation-mode mask of the
account that runs p4d to a value that denies other
users access to the server root directory.
Telling the Perforce service which port to listen on
The p4d service and Perforce applications communicate
with each other using TCP/IP. When p4d starts, it
listens (by default) for plaintext connections to port
1666. Perforce applications like
p4 assume (also by default) that the corresponding
p4d is located on a host named
perforce, listening on port
and that communications are performed in plaintext.
If p4d is to listen on a different port and/or use a
different protocol, either specify the configuration with the
flag when you start p4d (as in, p4d -p
ssl:1818), or by the contents of the
environment variable. Plaintext communications are specified with
port and SSL
encryption is specified with
port. (To use SSL, you
must also supply or generate a certificate and key pair and store them a
secure location on your server. See Encrypting connections to a Perforce server for
To enable IPv6 support, specify the wildcard address with two colons when starting p4d. For example:
p4d -p tcp64:[::]:1818
starts a Perforce service that listens for plaintext connections, on both IPv6 and IPv4 transports, on port 1818. Similarly,
p4d -p ssl64:[::]:1818
starts a Perforce service that requires SSL and listens on IPv6 and IPv4, and
p4d -p ssl6:[::]:1818
starts a Perforce service that requires SSL connections, and listens for IPv6 connections exclusively.
See IPv6 support and mixed networks for more information about IPv6 and IPv4 transports.
P4ROOT, the environment variable
P4PORT is used by both the Perforce service and the
Perforce applications, so it must be set both on the machine that hosts
the Perforce service and on individual user workstations.
Telling Perforce applications which port to connect to
Perforce applications need to know on what machine the p4d service is listening, on which TCP/IP port p4d is listening, and whether to communicate in plaintext or over SSL.
Set each Perforce user's
P4PORT environment variable to
where protocol is the communications protocol (beginning with
ssl: for SSL, or
host is the name of the machine
on which p4d is running, and
port is the number of the port on which
p4d is listening. For example:
Perforce applications connect in plaintext to the Perforce
service on host
Perforce applications connect in plaintext to the Perforce
service on host
Perforce applications connect via SSL to the Perforce service
Perforce applications connect to the Perforce service on a
host named or aliased
If you have enabled SSL, users are shown the server's fingerprint the
first time they attempt to connect to the service. If the fingerprint is
accurate, users can use the p4 trust command (either
p4 trust -y, or p4 -p
fingerprint) to install
the fingerprint into a file (pointed to by the
environment variable) that holds a list of known/trusted Perforce
servers and their respective fingerprints. If
unset, this file is
.p4trust in the user's home
IPv6 support and mixed networks
As of Release 2013.1, Perforce supports connectivity over IPv6 networks as well as over IPv4 networks.
Behavior and performance of networked services is contingent not merely upon the networking capabilities of the machine that hosts the service, nor only on the operating systems used by the end users, but also on your specific LAN and WAN infrastructure (and the state of IPv6 support for every router between the end user and the Perforce versioning service).
To illustrate just one possible scenario, a user working from home; even
if they have an IPv6-based home network, their ISP or VPN provider may
not fully support IPv6. We have consequently provided several variations
P4PORT to provide maximum flexibility and backwards
compatibility for administrators and users during the transition from
IPv4 to IPv6.
P4PORT protocol value
Behavior in IPv4/IPv6 or mixed networks
Listen on/connect to an IPv4 address/port only.
Listen on/connect to an IPv6 address/port only.
Attempt to listen/connect to an IPv4 address. If this fails, try IPv6.
Attempt to listen/connect to an IPv6 address. If this fails, try IPv4.
Listen on/connect to an IPv4 address/port only, using SSL encryption
Listen on/connect to an IPv6 address/port only, using SSL encryption.
Listen on/connect to an IPv4 address/port. If that fails, try IPv6. After connecting, require SSL encryption.
Listen on/connect to an IPv6 address/port. If that fails, try IPv4. After connecting, require SSL encryption.
In mixed environments it is good practice to set the
net.rfc3484 configurable to 1:
p4 configure set net.rfc3484=1
Doing so ensures RFC3484-compliant behavior for users who do not
explicitly specify the protocol value; that is, if the client-side
net.rfc3484 is set to
P4PORT is set to
ssl:example.com:1666, the user's operating system
will automatically determine, for any given connection, whether to use
IPv4 or IPv6 transport.
In multiserver environments,
net.rfc3484, when set
server-side, also controls the behavior of of host resolution when
initiating server-to-server (or proxy, broker, etc.) communications.
Starting the Perforce service
After you set p4d's
P4ROOT environment variables, start the service by
running p4d in the background with the command:
Although the example shown is sufficient to run p4d, you can specify other flags that control such things as error logging, checkpointing, and journaling.
Example 1. Starting the Perforce service
You can override
P4PORT by starting
p4d with the
-p flag (in
this example, listen to port 1818 on IPv6 and IPv4 transports), and
P4ROOT by starting p4d with the
-r flag. Similarly, you can specify a journal
file with the
-J flag, and an error log file
-L flag. A startup command that
overrides the environment variables might look like this:
p4d -r /usr/local/p4root -J /var/log/journal -L /var/log/p4err -p tcp64:[::]:1818 &
-L flags (and others) are discussed in
“Supporting Perforce: Backup and Recovery”. To enable SSL support, see
Encrypting connections to a Perforce server. A complete list of flags is provided in
the Perforce Server (p4d) Reference.
Stopping the Perforce service
To shut down the Perforce service, use the command:
p4 admin stop
Only a Perforce superuser can use p4 admin stop.
Restarting a running Perforce service
To restart a running Perforce service (for example, to read a new license file), use the command:
p4 admin restart
Only a Perforce superuser can use p4 admin restart. On UNIX platforms, you can also use kill -HUP to restart the service.
To install Perforce on Windows, use the Perforce installer (perforce.exe) from the Downloads page of the Perforce web site:
Use the Perforce installer program to install or upgrade the Perforce service, Perforce proxy, broker, or the Perforce Command-Line Client.
Other Perforce applications on Windows, such as the Perforce Visual Client (P4V), as well as third-party plug-ins, may be downloaded and installed separately.
For more about installing on Windows, see Using the Perforce installer.
Windows services and servers
In this manual, the terms Perforce Service and p4d are used interchangeably to refer to "the process which provides versioning services to Perforce applications" unless the distinction between a Windows server process or a service process is relevant.
On UNIX systems, there is only one Perforce service (p4d) responsible for providing the versioning service. On Windows, this program can be configured to run as a Windows service (p4s.exe) process that starts at boot time, or as a server (p4d.exe) process that you invoke manually from a command prompt.
The Perforce service (p4s.exe) and the Perforce server (p4d.exe) executables are copies of each other; they are identical apart from their filenames. When run, the executables use the first three characters of the name with which they were invoked (either p4s or p4d) to determine their behavior. (For example, invoking copies of p4d.exe named p4smyservice.exe or p4dmyserver.exe invoke a service and a server, respectively.)
By default, the Perforce installer configures Perforce as a Windows service. For a more detailed discussion of the distinction between services and servers, see Windows services vs. Windows servers.
Starting and stopping Perforce
If you install Perforce as a service under Windows, the service starts whenever the machine boots. Use theapplet in the to control the Perforce service's behavior.
If you install Perforce as a server under Windows, invoke p4d.exe from a command prompt. The flags for p4d under Windows are the same as those used under UNIX.
To stop a Perforce service (or server), use the command:
p4 admin stop
Only a Perforce superuser can use p4 admin stop.
For older revisions of Perforce, shut down services manually by using the CTRL+C in the window or by clicking the icon to close the command prompt window. Manually shutting down a server in this way is not necessarily "clean"; best practice is to use the p4 admin stop command.applet in the . Shut down servers running in command prompt windows by pressing
Upgrading the Perforce service
You must back up your Perforce installation (see Backup procedures) as part of any upgrade process.
Before you upgrade the Perforce service, always read the release notes associated with your upgraded installation.
In order to upgrade from 2013.2 (or earlier) to 2013.3 (or later), you must restore the database from a checkpoint. See Checkpoints for database tree rebalancing for an overview of the process and Upgrading p4d - between 2013.2 and 2013.3 for instructions specific to this upgrade.
In replicated and distributed environments (see Perforce Server Administrator's Guide: Multi-site Deployment), all replicas must be at the same release level as the master. Any functionality that requires an upgrade for the master requires an upgrade for the replica, and vice versa.
Using old Perforce applications after an upgrade
Although older Perforce applications generally work with newer versions of Perforce, some features in new server releases require upgrades to Perforce applications. In general, users with older applications are able to use features available from the Perforce versioning service at the user application's release level, but are not able to use the new features offered by subsequent upgrades to the service.
Licensing and upgrades
To upgrade Perforce to a newer version, your Perforce license file must be current. Expired licenses do not work with upgraded versions of Perforce.
Follow the instructions in this section if both your old and new versions are 2013.3 or later, or if both old and new versions are 2013.2 or earlier.
Read the Release Notes for complete information on upgrade procedures.
In order to upgrade from 2013.2 (or earlier) to 2013.3 (or later), you must restore the database from a checkpoint. See Checkpoints for database tree rebalancing for an overview of the process, and Upgrading p4d - between 2013.2 and 2013.3 instructions specific to this upgrade.
In general, Perforce upgrades require that you:
Stop the Perforce service (p4 admin stop).
Make a checkpoint and back up your old installation. (see Backup procedures)
Replace the p4d executable with the upgraded version.
On UNIX, replace the old version of p4d with the new version downloaded from the Perforce website. On Windows, use the Perforce installer (perforce.exe); the installer automatically replaces the executable.
Some upgrades (installations with more than 1000 changelists, or upgrades with certain database changes) may require that you manually upgrade the database by running:
This command may take considerable time to complete. You must have sufficient disk space to complete the upgrade.
Restart the Perforce service with your site's usual parameters.
If you have any questions or difficulties during an upgrade, contact Perforce technical support.
Upgrading p4d - between 2013.2 and 2013.3
Follow the instructions in this section if your old version is 2013.2 or earlier and your new version is 2013.3 or later.
Perforce 2013.3 contains major changes to the Perforce database implementation. These
changes allow for increased concurrency and scalability, and increase the size limit for the
db.* database files to 16TB.
db.* database file format has changed,
the checkpoint and journal file formats are identical. In order to
upgrade from 2013.2 (or earlier) to 2013.3 (or later), you
must restore the database from a checkpoint. To do
Stop the Perforce service (p4 admin stop).
Make a checkpoint and back up your old installation. (see Backup procedures)
If a file called
tiny.dbexists in your old server root, you must back it up separately by running the following command with the old p4d:
p4d -xf 857 > tiny.ckp
Remove the old
db.*files, or preferably, move them to a safe location in the event that the upgrade fails.
There must be no
db.*files in the
P4ROOTdirectory when you rebuild a database from a checkpoint. Although the old
db.*files will not be used again, it's good practice not to delete them until you're certain your upgrade was successful.
rdb.lbrfile, if it exists.
rdb.lbrfile keeps track of files that need to be transferred to the (local) replica, and may become out of date while the upgrade is underway. Note that this file only exists if your Perforce service was configured as a replica.
Replace the old (2013.2 or earlier) p4d executable with the new (2013.3 or later) p4d executable.
Do not run p4d -xu after replacing p4d at this time. In this upgrade scenario, you are not upgrading an existing database, you have removed it completely and will rebuild it from the checkpoint that you just took.
Use the upgraded p4d to replay the checkpoint and rebuild the new database tables:
p4d -r $P4ROOT -jr
If your site uses localized server messages from a message file obtained through Perforce technical support, retrieve the original
message.txtfile and re-create
db.messagein the new database format by running the following command with the new p4d:
p4d -jr /
See Localizing server error messages for more information.
If you created a
tiny.ckpfile as part of your backup process, restore
tiny.dbby running the following command with the new p4d:
p4d -xf 857 tiny.ckp
Run p4d -xu against the Perforce database to update the database schema:
p4d -r $P4ROOT -J
Restart the Perforce service and resume operations.
Installation and administration tips
Release and license information
The Perforce versioning service is licensed according to how many users they support.
Licensing information is contained in a file called
license in the server root directory. The
license file is a plain text file supplied by
Perforce Software. Without the
license file, the
service limits itself to either 20 users and 20 client workspaces (and
unlimited files), or to an unlimited number of users and workspaces (but
with a limit of 1000 files). You can update an existing file without
stopping Perforce by using the p4 license command.
See Adding new licensed users for details.
If the service is running, any user can use p4 info to view basic licensing information. Administrators can use p4 license -u to obtain more detailed information about how many users and files are in use.
If the service is down, you can can also obtain licensing information by
running p4d -V from the server root directory where
license file resides, or by specifying the
server root directory either on the command line (p4d -V -r
server_root) or in the
P4ROOT environment variable.
The server version is also displayed when you invoke p4d -V or p4 -V.
Observe proper backup procedures
Regular backups of your Perforce data are vital. The key concepts are:
Make sure journaling is active.
Create checkpoints regularly.
Use p4 verify regularly.
See “Supporting Perforce: Backup and Recovery” for a full discussion of backup and restoration procedures.
Use separate physical drives for server root and journal
Whether installing on UNIX or Windows, it is advisable to have your
P4ROOT directory (that is, the directory containing your
database and versioned files) on a different physical drive than your
By storing the journal on a separate drive, you can be reasonably
certain that, if a disk failure corrupts the drive containing
P4ROOT, such a failure will not
affect your journal file. You can then use the journal file to restore
any lost or damaged metadata.
Further details are available in “Supporting Perforce: Backup and Recovery”.
Use protections and passwords
Until you define a Perforce superuser, every Perforce user is a Perforce superuser and can run any Perforce command on any file. After you start a new Perforce service, use:
as soon as possible to define a Perforce superuser. To learn more about how p4 protect works, see “Administering Perforce: Protections”.
Without passwords, any user is able to impersonate any other Perforce
user, either with the
-u flag or by setting
P4USER to an existing Perforce user name. Use of Perforce
passwords prevents such impersonation. See the
User's Guide for details.
To set (or reset) a user's password, either use p4 passwd
username (as a Perforce superuser),
and enter the new password for the user, or invoke p4 user -f
username (also while as a Perforce
superuser) and enter the new password into the user specification form.
The security-conscious Perforce superuser also uses p4
protect to ensure that no access higher than
list is granted to nonprivileged users, p4
configure to set the
security level to a
level that requires that all users have strong passwords, and
p4 group to assign all users to groups (and,
optionally, to require regular changes of passwords for users on a
per-group basis, to set a minimum required password length for all users
on the site, and to lock out users for predefined amounts of time after
repeated failed login attempts).
Allocate sufficient disk space for anticipated growth
Because the collection of versioned files grows over time, a good
guideline is to allocate sufficient space in your
directory to hold three times the size of your users' present collection
of versioned files, plus an additional 0.5KB per user per file to hold
the database files that store the list of depot files, file status, and
file revision histories.
For a more detailed example of a disk sizing estimate, see Disk space allocation.
Managing disk space after installation
All of Perforce's versioned files reside in subdirectories beneath the server root, as do the database files, and (by default) the checkpoints and journals. If you are running low on disk space, consider the following approaches to limit disk space usage:
Configure Perforce to store the journal file on a separate physical disk. Use the
P4JOURNALenvironment variable or p4d -J to specify the location of the journal file.
Keep the journal file short by taking checkpoints on a daily basis.
Compress checkpoints, or use the
-zoption to tell p4d to compress checkpoints on the fly.
-jcoption with the p4d command to write the checkpoint to a different disk. Alternately, use the default checkpoint files, but back up your checkpoints to a different drive and then delete the copied checkpoints from the root directory. Moving checkpoints to separate drives is good practice not only in terms of diskspace, but also because old checkpoints are needed when recovering from a hardware failure, and if your checkpoint and journal files reside on the same disk as your depot, a hardware failure could leave you without the ability to restore your database.
On UNIX systems, you can relocate some or all of the depot directories to other disks by using symbolic links. If you use symbolic links to shift depot files to other volumes, create the links only after you stop the Perforce service.
If your installation's database files have grown to more than 10 times the size of a checkpoint, you might be able to reduce the size of the files by re-creating them from a checkpoint. See Checkpoints for database tree rebalancing.
Use the p4 diskspace and p4 sizes commands to monitor the amount of disk space currently consumed by your entire installation, or by selected portions of your installation. See Monitoring disk space usage.
If you have large binary files that are no longer accessed frequently, consider creating an archive depot and using the p4 archive command to transfer these files to bulk, near-line, or off-line storage. See Reclaiming disk space by archiving files.
Large filesystem support
Very early versions of Perforce (typically prior to 98.2), as well as
some older operating systems, limit Perforce database files (the
db.* files in the
that hold your site's metadata) to 2 GB in size. The
db.have file holds the list of files currently
synced to client workspaces, and tends to grow the most quickly.
If you anticipate any of your Perforce database files growing beyond the 2 GB level, install the Perforce server on a platform that supports large files.
Windows: Username and password required for network drives
By default, the Perforce service runs under the Windows local
System account. Because Windows requires a real
account name and password to access files on a network drive, if
Perforce is installed as a service under Windows with
P4ROOT pointing to a network drive, the installer
requires an account name and a password. The Perforce service is then
configured with the supplied data and run as the specified user instead
System. (The account running the service must have
Administrator privileges on the machine.)
Although Perforce operates reliably with its root directory on a network drive, it does so only at a substantial performance penalty, because all writes to the database are performed over the network. For optimal performance, install the Windows service to use local drives rather than networked drives.
For more information, see Installing the Perforce service on a network drive.
UNIX: Run p4d as a nonprivileged user
Perforce does not require privileged access. For security reasons, do
not run p4d as
root or otherwise
grant the owner of the p4d process
Create a nonprivileged UNIX user (for example,
perforce) to manage p4d and
(optionally) a UNIX group for it (for example,
p4admin). Use the umask(1) command
to ensure that the server root (
P4ROOT) and all files and
directories created beneath it are writable only by the UNIX user
perforce, and (optionally) readable by members of the
Under this configuration, the Perforce service (p4d),
running as UNIX user
perforce, can write to files in
the server root, but no users are able to read or overwrite its files.
To grant access to the files created by p4d (that is,
the depot files, checkpoints, journals, and so on) to trusted users, you
can add the trusted users to the UNIX group
On Windows, directory permissions are set securely by default; when
Perforce runs as a Windows server, the server root is accessible only
to the user who invoked p4d.exe from the command
prompt. When Perforce is installed as a service, the files are owned
LocalSystem account, and are accessible only
to those with
-L flag to p4d or the
P4LOG to specify Perforce's error
output file. If no error output file is defined, errors are dumped to
the p4d process' standard error. Although
p4d tries to ensure that all error messages reach the
user, if an error occurs and the user application disconnects before the
error is received, p4d also logs these errors to its
Perforce also supports trace flags used for debugging. See Perforce server trace and tracking flags for details.
Logging file access
If your site requires that user access to files be tracked, use the
-A flag to p4d or the
P4AUDIT to activate auditing and
specify the Perforce's audit log file. When auditing is active, every
time a user accesses a file, a record is stored in the audit log file.
This option can consume considerable disk space on an active
See Auditing user file access for details.
Case sensitivity issues
Whether you host the Perforce versioning service on Windows or UNIX, if your site is involved in cross-platform development (that is, if you are using Perforce applications on both Windows and UNIX environments), your users must also be aware of certain details regarding case sensitivity issues.
See Case sensitivity and multiplatform development for details.
Enable process monitoring
Perforce tracks information about the processes it spawns on the machine that hosts the versioning service. Process monitoring requires minimal system resources, but you must enable process monitoring for p4 monitor to work.
To enable process monitoring, set the
configurable as follows:
p4 configure set monitor=1
See Monitoring server activity for details.
Tune for performance
Perforce is an efficient consumer of network bandwidth and CPU power. The most important variables that affect performance are the efficiency of the host machine's disk I/O subsystem and the number of files referenced in any given user-originated Perforce operation.
For more detailed performance tuning information, see “Tuning Perforce for Performance”.