Perforce Installation and Upgrade

 

 

Getting Perforce

Perforce requires at least two executables: the server (p4d), and a client programs (p4).

The programs are available from the Downloads page on the Perforce web site:

http://www.perforce.com/perforce/loadprog.html
Go to the web page, select the files for your platform, and save the files to disk.

 

Installing Perforce on UNIX


Although p4 and p4d can be installed in any directory, on UNIX the Perforce client programs typically reside in /usr/local/bin, and the Perforce server is usually located either in /usr/local/bin or in its own server root directory. Perforce client programs can be installed on any machine that has TCP/IP access to the p4d host.

To limit access to the Perforce server files, we recommend that p4d be owned and run by a Perforce user account that has been created for that purpose.

Once you've downloaded p4 and p4d, you need to do a few more things before you can use Perforce.

     

  1. Make them executable

    2. Make the Perforce server and client binaries executable:

    chmod +x p4
    chmod +x p4d

     

  2. Create a Perforce server root directory

    3. Perforce stores all of its data in files and subdirectories of its own root directory, which can reside anywhere on the server system. This directory is called the server root. This directory should be owned by the account that runs p4d, and can be named anything at all. The only necessary permissions are read, write, and execute for the user who invokes p4d.

    Since Perforce will store all submitted files under this directory, the size of the directory can become quite large. Disk space management is reviewed in Installation and Administration Tips and Disk space allocation.

    For security purposes, read and write access to the server root should be restricted to prevent anyone but the account owner from reading, modifying or even listing the actual depot files. To ensure that temporary files cannot be read by unauthorized users, set the umask(1) file creation-mode mask of the account owner to a value that will not permit other users to read the contents of the server root directory or its files.

    Do not run p4d as root. Run p4d as a non-privileged user .

    The environment variable P4ROOT should be set to point to the server root.

    You can run p4d -r alt_root_dir to specify a an alternate server root directory.

    The Perforce client programs never use this directory directly, and do not need to know the value of P4ROOT; the p4d server is the only process which uses the P4ROOT environment variable.

     

  3. Tell the Perforce server which port to listen to

    4. The p4d server and Perforce client programs communicate with each other via TCP/IP. When p4d starts, it listens (by default) on port 1666. The Perforce client assumes (also by default) that its p4d server is located on host perforce, listening on port 1666.

    If p4d is to listen on a different port, the port can be specified by running p4d -p port_num or by setting the P4PORT environment variable.

     

  4. Tell Perforce client programs which port to talk to

    5. Perforce client programs need to know the TCP/IP port on which the p4d server program is listening. The easiest way to do this under UNIX is to set each Perforce user's P4PORT environment variable to host:port#, where host is the name of the machine on which p4d is running, and port# is the port on which p4d is listening.

    P4PORT...
    		Then...
    192.169.1.150:1666 Client uses p4d server on host 192.169.1.150 listening at port 1666.
    acme.com:1666 Client uses p4d server on host acme.com listening at port 1666.

    The definition of P4PORT can be shortened if the Perforce client program is running on the same host as p4d. In this case, only the p4d port number need be provided to the client. If p4d is running on a host named or aliased perforce, listening on port 1666, the definition of P4PORT for the client can be dispensed with altogether.

    If you have troubles connecting, edit the /etc/hosts file and add "perforce" as an alias for the machine hosting the p4d executable.

    P4PORT... Then...
    1666 Client will use the p4d server on its local host listening at port 1666.
    <not set> Client program will use the p4d server on the host named or aliased perforce listening on port 1666.

    If your p4d host is not named perforce, you can choose to simplify life somewhat for your Perforce users by setting perforce as an alias to the true host name in their workstations' /etc/hosts files, or by doing so via Sun's NIS or Internet DNS.

     

  5. Start the Perforce server

    6. After the P4PORT and P4ROOT environment variables have been set, p4d can be run in the background with the command:

    p4d &

    Although this command is sufficient to run p4d, other flags can be included:

    Flag Description
    -p Override P4PORT
    -r Override P4ROOT
    -J Specify a journal file
    -L Log Errors

    For example:

    p4d -r /usr/local/p4root -J /var/log/journal -L /var/log/p4err -p 1818 &

    See also:

    1. Backup and Recovery
    2. Perforce Server Reference

 

Stop the Perforce server

If you are running Perforce 99.2 or above, use the command

to shut down the Perforce server. Only a Perforce superuser may use this command.

If you are running an earlier version of Perforce, you'll have to find the process ID of the p4d server and kill it manually from the UNIX shell. The use of kill -15 (SIGTERM) is preferable to kill -9 (SIGKILL), as the database could be left in an inconsistent state if p4d happened to be in the middle of updating a file when a SIGKILL signal was received.

 

Installation and Administration Tips

 

Release and license information

Perforce servers are licensed according to how many users they will support. This licensing information lives in a file called license in the server root directory. It is a plain text file supplied by Perforce Software. Without the license file, the Perforce server will limit itself to two users and two client workspaces.

Current licensing information may be viewed by invoking p4d -V from the server root directory or by specifying the server root directory either on the command line (p4d -V -r server_root) or in the P4ROOT environment variable.

When the server is running, the license information may also be viewed with p4 info.

Version information will be displayed when invoking p4d -V or p4 -V.

 

Observe proper backup procedures

Regular backups of your Perforce data are vital. The key concepts are:

  1. Make sure journaling is active,

  2. Create checkpoints regularly, and

  3. Use p4 verify regularly.

 

Use separate filesystems for server root and journal

Put the P4ROOT directory on a different physical drive than the journal file. This ensures that if a disk failure corrupts the drive containing P4ROOT, it will not affect the journal file. The journal file can then be used to restore any lost or damaged metadata.

 

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. The administrator who installs Perforce should use:

p4 protect
to define a Perforce superuser as soon as possible after installing the Perforce server.

Furthermore, until your users have passwords defined, any user will be able to impersonate any other Perforce user, either with the -u flag or by setting P4USER to a Perforce user's username. Proper use of Perforce passwords (as described in the Perforce User's Guide) can protect against this. See the Perforce User's Guide for details.

To set (or reset) a user's password, 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 former command will only work in release 99.1 or later; the latter command will work under all releases from 97.3 onwards.

The security-conscious Perforce superuser will use p4 protect to make sure that no access higher than list is granted to non-privileged users, and require that each user have a Perforce password.

 

Allocate disk space for anticipated growth

In general, you'll need sufficient space in your P4ROOT directory to hold your depot files (that is, the files created by your users), and an additional 0.5K per user per file to hold the data describing the files, their status, and their histories. As a rule of thumb, you also probably want at least enough disk space to hold three times the size of your present collection of versioned files.

 

Managing disk space after installation

All of Perforce's versioned files reside in subdirectories of the server root, as do its database files, and (by default) the checkpoints and journals. The stored versioned file depots are grow-only, and this can clearly present disk space problems on high use systems. The following approaches may be used to remedy this:

  • Tell Perforce to store the journal file on a separate physical disk. Use the P4JOURNAL environment variable or p4d -J to specify the location of the journal file.

  • Checkpoint on a daily basis to keep the journal file short.

  • Compress checkpoints, or use the -z option to tell p4d to compress them while creating them.

  • Use the -jc prefix option with the p4d command to write the checkpoint to a different disk. Alternately, use the default checkpoint files, but back up your checkpoints and then delete them from the root directory. Old checkpoints are needed when recovering from a crash, 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, some or all of the depot directories may be relocated to other disks by using symbolic links. Creation of symbolic links and movement of depot files to other volumes should be done only while the Perforce server is not running.

  • Due to the nature of the implementation of their access methods, the database files themselves may become internally unbalanced, resulting in them taking up more space than necessary. The database files can sometimes be reduced in size by recreating them from a checkpoint. This should be done only if the database files are more than about 10 times the size of the checkpoint in total. See "Checkpoints for Database Tree Rebalancing" on page 102.

 

Large filesystem support

Earlier versions of the Perforce server, as well as some operating systems, limit Perforce database files (the db.* files in the P4ROOT directory which contain your metadata) to 2GB in size.

The db.have file holds label contents and the list of files currently opened in client workspaces, and tends to grow the most quickly. If you anticipate any of your Perforce database files growing beyond the 2GB level, you should install the Perforce server on a platform with support for large files.

The following combinations of operating system and Perforce server revision will support database files larger than 2GB:

OS Version Perforce Server Revision
Tru64 UNIX
(a.k.a. Digital UNIX, OSF/1) 		All versions 98.2/5713 or higher
FreeBSD All versions 98.2/5713 or higher
Windows NT, 2000 All versions,
SP6 recommended for NT 		98.2/8127 or higher
SGI IRIX 6.2 All versions 98.2/5713 or higher
SGI IRIX 5.3 Only with the SGI-supplied xfs upgrade 98.2/5713 or higher xfs OS upgrade required
Solaris 2.6 and higher 98.2/7488 compiled for 2.6 or higher

 

UNIX and NFS support

The Perforce server process has been tested and is supported on the Solaris 2.6 implementation of NFS. Because Perforce client programs never directly access the files in P4ROOT, the only process needing access to P4ROOT is the p4d server itself.

Consequently, under Solaris 2.6 or higher, you can store your journal, log, depot, and db.* files on NFS-mounted filesystems.

Some issues still remain regarding file locking on non-commercial implementations of NFS (for instance, Linux and FreeBSD). On these platforms, we recommend that you store your journal, log, depot, and db.* files on a drive local to the server machine, not on an NFS-mounted volume.

These issues affect only the Perforce server process (p4d). Perforce clients (such as the p4 command-line client) have always been able to work with client workspaces on NFS-mounted drives, such as workspaces located in users' home directories.

 

Run p4d as a non-privileged user

While it is possible to run the Perforce server as root, it is highly inadvisable to do so. Sound administration practice demands that processes which don't require root access should never be run as root. For Perforce, this means that the owner of the p4d process should never be a privileged account.

A good way to manage a Perforce installation on UNIX is to create a UNIX userid for it (for example, "perforce") and (optionally) a UNIX group for it (for example, "p4admin"). The umask(1) command can be used to ensure that the server root (P4ROOT) and all files and directories beneath it are created as writable only by the UNIX user perforce, and (optionally) readable by members of the UNIX group p4admin.

The Perforce server (p4d), running as UNIX user perforce, can write to files in the server root, but none of your users will be able to overwrite its files. Access to read the files created by p4d (that is, the depot files, checkpoints, journals, and so on) can be granted to trusted users by making them members of the UNIX group p4admin.

 

Logging errors

The Perforce server's error output file can be specified with the -L flag to p4d, or can be defined in the environment variable P4LOG. If no error output file is defined, errors are dumped to stderr.

Although p4d tries to ensure that all error messages reach the user, if an error occurs and the client program disconnects before the error is received, p4d will also log these errors to its error output.

The Perforce server also has trace flags used for debugging purposes. See "Perforce server trace flags" on page 52 for details.

 

Case sensitivity issues

Whether your Perforce server is running on Windows or UNIX, if your site is involved in cross-platform development (i.e. Perforce clients on both Windows and UNIX machines), your users will still need to be made aware of certain details regarding case sensitivity issues. See "Case sensitivity and multi-platform development" on page 50 for details.

 

Tune for performance

Perforce is a relatively light consumer of network traffic and CPU power. The most important variables determining performance will be the efficiency of your server'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" on page 91.