Perforce 2006.1 System Administrator's Guide
<< Previous Chapter
About This Manual
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Supporting Perforce:
Backup and Recovery


Chapter 1
Welcome to Perforce:
Installing and Upgrading

This chapter describes how to install a Perforce server or upgrade an existing installation.

Warning!

If you are upgrading an existing installation to Release 2005.1 or later, see the notes in "Upgrading a Perforce server" on page 16 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.

Windows

Where the UNIX and Windows versions of Perforce differ, this manual notes the difference. For Windows-specific information, see "Perforce and Windows" on page 129.

Many of the examples in this book are based on the UNIX version of the Perforce server. In most cases, the examples apply equally to both Windows and UNIX installations.

OS X

The material for UNIX also applies to Mac OS X.

Getting Perforce

Perforce requires at least two executables: the server (p4d), and at least one Perforce client program (such as p4 on UNIX, or p4.exe or p4win.exe on Windows).

The server and client executables 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.

UNIX installation

Although you can install p4 and p4d 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. You can install Perforce client programs on any machine that has TCP/IP access to the p4d host.

To limit access to the Perforce server 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 server.

To start using Perforce:

  1. Download the p4 and p4d files for your platform from the Perforce web site.

  2. Make the downloaded p4 and p4d files executable.

  3. Create a server root directory to hold the Perforce database and versioned files.

  4. Tell the Perforce server what port to listen to by specifying a TCP/IP port to p4d.

  5. Start the Perforce server (p4d).

  6. Specify the name or TCP/IP address of the Perforce server machine and the p4d port number to the Perforce client programs by setting the P4PORT environment variable.

Downloading the files and making them executable

On UNIX (or Mac OS X), you must make the Perforce executables (p4 and p4d) executable. After you download the programs, use the chmod command to make them executable, as follows:

chmod +x p4
chmod +x p4d

Creating a Perforce server root directory

The Perforce server 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 -r root_dir flag when invoking p4d. Perforce client programs never use the P4ROOT directory or environment variable; the p4d server is the only process that uses the P4ROOT variable.

Because all Perforce files are stored beneath the server root, the contents of the server root grow over time. See "Installation and administration tips" on page 19 for a brief overview of diskspace requirements, and "Disk space allocation" on page 116 for more detail.

A Perforce server 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" on page 22.

The server root can be located anywhere, but the account that runs p4d must have read, write, and execute permissions on the server root and all directories beneath it. For security purposes, set the 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 Perforce servers which port to listen on

The p4d server and Perforce client programs communicate with each other using 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 a host named perforce, listening on port 1666.

If p4d is to listen on a different port, either specify that port with the -p port_num flag you start p4d (as in, p4d -p 1818), or set the port with the P4PORT environment or registry variable.

Unlike P4ROOT, the environment variable P4PORT is used by both the Perforce server and the Perforce client programs, so it must be set on both Perforce server machines and Perforce client workstations.

Telling Perforce client programs which port to connect to

Perforce client programs need to know on what machine the p4d server resides and on which TCP/IP port the p4d server program is listening. 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 number of the port on which p4d is listening.

Examples:

P4PORT
Client program behavior

dogs:3435

Perforce client programs connect to the p4d server on host dogs listening on port 3435.

x.com:1818

Perforce client programs connect to the p4d server on host x.com listening on port 1818.

If the Perforce client program is running on the same host as p4d, only the p4d port number need be provided in P4PORT. If p4d is running on a host named or aliased perforce, and is listening on port 1666, leave P4PORT unset. For example:

P4PORT
Client program behavior

3435

Perforce client programs connect to the p4d server on the same machine as the client program, listening on port 3435.

<not set>

Perforce client programs connect to the p4d server on a host named or aliased perforce listening on port 1666.

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

Starting the Perforce server

After you set p4d's P4PORT and P4ROOT environment variables, start the server 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.

Stopping the Perforce server

To shut down a Perforce server, use the command:

Only a Perforce superuser can use p4 admin stop.

If you are running a release of Perforce from earlier than 99.2, you must find the process ID of the p4d server and kill the process manually from the UNIX shell. Use kill -15 (SIGTERM) instead of kill -9 (SIGKILL), because p4d might leave the database in an inconsistent state if it is in the middle of updating a file when a SIGKILL signal is received.

Windows installation

To install Perforce on Windows, use the Perforce installer (perforce.exe) from the Downloads page of the Perforce web site.

Use the Perforce installer to:

This option enables you to install p4.exe (the Perforce Command-Line Client), p4win.exe (P4Win, the Perforce Windows Client), and p4scc.dll (Perforce's implementation of the Microsoft common SCM interface).

These options enable you to install Perforce client programs and the Perforce Windows server (p4d.exe) and service (p4s.exe) executables, or to automatically upgrade an existing Perforce server or service running under Windows.

Under Windows 2000 or higher, you must have Administrator privileges to install Perforce as a service or as a server.

This option removes the Perforce server, service, and client executables, registry keys, and service entries. The Perforce database and the depot files stored under your server root are preserved.

For more about installing on Windows, see "Using the Perforce installer" on page 129.

Windows services and servers

In this manual, the terms Perforce server and p4d are used interchangeably to refer to "the process which handles requests from Perforce client programs" unless the distinction between a Windows server process a Windows service process is relevant.

On UNIX systems, there is only one Perforce "server" program (p4d) responsible for this back-end task. On Windows, however, this back-end 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.)

In most cases, it is preferable to install Perforce as a service, not a server. For a more detailed discussion of the distinction between services and servers, see "Windows services vs. Windows servers" on page 132.

Starting and stopping Perforce

If you install Perforce as a service under Windows, the service starts whenever the machine boots. Use the Services applet in the Control Panel 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:

Only a Perforce superuser can use p4 admin stop.

For older revisions of Perforce, shut down services manually by using the Services applet in the Control Panel. Shut down servers running in command prompt windows by pressing CTRL-C in the window or by clicking the icon to close the command prompt window. Although manually shutting down in this way works with Release 99.2 and earlier versions of Perforce, it is not necessarily "clean", in the sense that the server or service is shut down abruptly. With the availability of the p4 admin stop command in 99.2, this manual shutdown method is obsolete.

Upgrading a Perforce server

Whether your Perforce server is installed on Windows or UNIX, you must back up your server (see "Backup procedures" on page 31) as part of any upgrade process.

Warning!

Before you upgrade a Perforce server, always read the release notes associated with your upgraded server.

For large installations, p4d -xu may require a significant amount of time to complete.

Using old client programs with a new server

Although older Perforce client programs (p4, p4.exe, p4win.exe, and p4scc.dll) generally work with newer server versions, some features in new server releases require upgrades to Perforce client programs. In general, users with older client programs are able to use features available from the Perforce server at the client program's release level, but they are not able to use the new server features offered by subsequent server upgrades.

Perforce's remote depot support is an exception: remote depot support is not guaranteed to work unless all Perforce servers are at or above Release 99.2.

Important notes for 2005.1 and later

As of Release 2005.1, Perforce servers keep track of file length metadata on a per-revision basis. Newly submitted files have file length metadata added to the database automatically, but you must still run p4 verify -u at least once following an upgrade to 2005.1 in order to generate file length data for any files added to the depot before your upgrade.

Administrators of very large sites (such as those with tens of millions of revisions) may encounter memory constraints immediately following an upgrade to 2005.1 if they attempt to update file length metadata for the entire repository at once. If this is the case, use the -m maxRevs flag to limit the number of revisions updated per command.

For example, the following command

limits file length metadata recomputation to a million files at a time, enabling an administrator to divide file length metadata recomputation over several calls to p4 verify.

Important notes for 2001.1 and later

On small installations (installations with fewer than 1000 submitted changelists), installing a 2001.1 (or more recent) server automatically upgrades the underlying database from versions 98.2 and up.

On larger installations, you must upgrade the database manually. Although the upgraded database is typically smaller than a pre-2001.1 database, the upgrade process might (temporarily) require approximately three times the size of the existing database to store files required during the upgrade.

Note

If you have limited disk space, see the release notes for a more precise estimate of the amount of disk space required.

By turning off journaling during the upgrade (by setting P4JOURNAL to off), you can reduce the amount of disk space required for the upgrade. (Remember to turn journaling back on when the upgrade is complete!)

If you are upgrading from Release 97.3 or earlier to 2001.1 or later, the automatic or manual upgrade procedures do not apply; you will probably have to make an intermediate checkpoint. Contact Perforce technical support for assistance before upgrading a Release 97.3 or earlier server.

UNIX upgrades

To upgrade your current Perforce server to a newer version, your Perforce license file must be current. Expired licenses do not work with upgraded servers. (Restrictions on license files are not an issue for users running a two-user installation with no license.)

You must back up your server as described in "Backup procedures" on page 31 as part of any upgrade process.

For additional safety, run p4 verify as part of your upgrade. See "Verifying files during server upgrades" on page 48 for details.

Warning!

Upgrading to Release 2001.1 or later requires an upgrade of your database files. Downgrading thereafter requires that you restore from backups.

If you want to keep a pre-2001.1 server available as a fallback option when upgrading to 2001.1 or higher, you must back up your entire server root (including the db.* files) after you stop the server.

Upgrading from UNIX Release 98.2 or later

If you have a valid license (or require no license) and are upgrading from Release 98.2 or later:

  1. Download the new p4d executable for your platform.

  2. Stop the current instance of p4d.

  3. Make a checkpoint and back up your old installation.

  4. Install the new p4d in the desired location.

  5. Run p4d -xu to upgrade the database.

    Note

    If your server has fewer than 1000 changes, the upgrade runs automatically. Larger installations require that you run p4d -xu manually. You must have sufficient disk space to complete the upgrade.

  6. Restart the new p4d with your site's usual parameters.

Your users should then be able to use the new server.

Windows upgrades

On Windows, download the installer (perforce.exe) and follow the installation dialog.

The upgrade process on Windows is extremely conservative; in the event of an error condition during an upgrade, you will be able to revert to your pre-upgrade Perforce server or service.

Note

If your server has fewer than 1000 changes, the upgrade runs automatically. Larger installations require that you run p4d -xu manually. You must have sufficient disk space to complete the upgrade.

If you have any questions or difficulties during an upgrade, contact Perforce technical support.

Installation and administration tips

Release and license information

Perforce servers are 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 Perforce server limits itself to two users and two client workspaces.

To view current licensing information, invoke p4d -V from the server root directory where the 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.

If the server is running, you can also use p4 info to view your licensing information.

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:

See "Supporting Perforce: Backup and Recovery" on page 25 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 journal file.

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" on page 25.

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 server, use:

as soon as possible to define a Perforce superuser. To learn more about how p4 protect works, see "Administering Perforce: Protections" on page 75.

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 P4 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 former command is supported in release 99.1 or later; the latter command is supported under all releases from 97.3 onwards.

The security-conscious Perforce superuser also uses p4 protect to ensure that no access higher than list is granted to nonprivileged users, and to ensure that each user has a Perforce password.

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 P4ROOT 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" on page 116.

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:

Large filesystem support

Early versions of the Perforce server, as well as some operating systems, limit Perforce database files (the db.* files in the P4ROOT directory 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 with support for large files. The following combinations of operating system and Perforce server revision support database files larger than 2 GB:

Operating system
OS version
Perforce server revision

Windows NT, 2000, XP

All versions,
SP6 recommended for NT

98.2/8127 or higher

FreeBSD

All versions

98.2/5713 or higher

Linux x86

Kernels 2.4.0 and higher

2002.2/21749 or higher

HP-UX

HP-UX 11.11 and higher

2001.1/26433 or higher

Solaris

2.6 and higher

98.2/7488 compiled for 2.6 or higher

Tru64 UNIX
(a.k.a. Digital UNIX, OSF/1)

All versions

98.2/5713 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

UNIX and NFS support

The Perforce server process has been tested and is supported on the Solaris 2.6 (and higher) implementations of NFS. Because Perforce client programs never directly access the files in P4ROOT, the only process that needs 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. To maximize performance, however, the server root (P4ROOT) should still be on a local disk, not an NFS-mounted volume.

Some issues still remain regarding file locking on noncommercial implementations of NFS (for instance, Linux and FreeBSD). On these platforms, 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 client programs (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.

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 of 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" on page 133.

UNIX: Run p4d as a nonprivileged user

The Perforce server process does not require privileged access. For security reasons, do not run p4d as root or otherwise grant the owner of the p4d process root-level privileges.

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 UNIX group p4admin.

Under this configuration, the Perforce server (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 p4admin.

Windows

On Windows, directory permissions are set securely by default; when Perforce runs as a server, the server root is accessible only to the user who invoked the server from the command prompt. When Perforce is installed as a service, the files are owned by the LocalSystem account, and are accessible only to those with Administrator access.

Logging errors

Use the -L flag to p4d or the environment variable P4LOG to specify the Perforce server'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 client program disconnects before the error is received, p4d also logs these errors to its error output.

The Perforce server also supports trace flags used for debugging. See "Perforce server trace and tracking flags" on page 60 for details.

Logging file access

If your site requires that user access to files be tracked, use the -A flag to p4d or the environment variable P4AUDIT to activate auditing and specify the Perforce server'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 server.

See "Auditing user file access" on page 62 for details.

Case sensitivity issues

Whether your Perforce server is running on Windows or UNIX, if your site is involved in cross-platform development (that is, if you are using Perforce client programs on both Windows and UNIX workstations), your users must be aware of certain details regarding case sensitivity issues.

See "Case sensitivity and multiplatform development" on page 57 for details.

Tune for performance

Perforce is an efficient consumer of network bandwidth and CPU power. The most important variables that determine server performance are 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 115.


Perforce 2006.1 System Administrator's Guide
<< Previous Chapter
About This Manual
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Supporting Perforce:
Backup and Recovery

Please send comments and questions about this manual to [email protected].
Copyright 1999-2006 Perforce Software. All rights reserved.
Last updated: 06/23/06