Chapter 1
Welcome to Perforce:
Installing and Upgrading

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.

Getting Perforce

The server and client executables are available from the Downloads page on the Perforce web site:

http://www.perforce.com/perforce/loadprog.html

UNIX installation

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

Creating a Perforce server root directory

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 128 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 23.

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

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

Examples:

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:

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

p4d &

Example:  Starting a Perforce server

You can override P4PORT by starting p4d with the -p flag, 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 with the -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 1818 &

The -r, -J, and -L flags (and others) are discussed in "Supporting Perforce: Backup and Recovery" on page 25. A complete list of server flags is provided in the "Perforce Server (p4d) Reference" on page 159.

Stopping the Perforce server

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

http://www.perforce.com/perforce/loadprog.html

• Install the Perforce Command-Line Client software ("User install")

The user install option installs only the Perforce Command-Line Client (p4.exe).

Other Perforce clients on Windows, such as the Perforce Visual Client (P4V), the Perforce Windows Client (P4Win), as well as third-party plug-ins, may be downloaded and installed separately.

• Install Perforce as either a Windows server or Windows service as appropriate ("Administrator typical" and "Administrator custom" install)

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.

• Uninstall Perforce

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.

Windows services and servers

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 144.

Starting and stopping Perforce

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

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

Using old client programs with a new server

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

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

p4 verify -u -m 1000000 //...

Important notes for 2001.1 and later

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.

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

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 47 for details.

Upgrading from UNIX 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.

Windows upgrades

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.

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

Installation and administration tips

Release and license information

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 five client workspaces.

You can update an existing file without stopping the Perforce Server by using the p4 license command. See "Adding new licensed users" on page 45 for details.

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

• Make sure journaling is active.

• Create checkpoints regularly.

• Use p4 verify regularly.

Use separate physical drives for server root and journal

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

p4 protect

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

For a more detailed example of a disk sizing estimate, see "Disk space allocation" on page 128.

Managing disk space after installation

• Configure 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.

• Keep the journal file short by taking checkpoints on a daily basis.

• Compress checkpoints, or use the -z option to tell p4d to compress checkpoints on the fly.

• 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 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 server.

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

• Use the p4 sizes command 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" on page 129.

Large filesystem support

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:

UNIX and NFS support

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

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 145.

UNIX: Run p4d as a nonprivileged user

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.

Logging errors

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

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

Case sensitivity issues

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

Tune for performance

For more detailed performance tuning information, see "Tuning Perforce for Performance" on page 127.