Perforce 2002.2 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're upgrading an existing installation to Release 2001.1 or later, see the notes in "Upgrading a Perforce Server" on page 16 before proceeding.

A short checklist of things to consider at installation time is offered, along with some basic security and administration tips. More detailed notes on administrative tasks are found in later chapters.

Windows

Windows administrators will note that many of the examples in this book are based on the UNIX version of the Perforce server. In almost all cases, they are common to both Windows and UNIX installations; Perforce's behavior is generally the same regardless of whether executed in a UNIX shell or from the MS-DOS command line.

Where the UNIX and Windows versions of Perforce differ, a note to that effect will be made. For Windows-specific information, see "Perforce and Windows" on page 103.

OS X

The material for UNIX also applies to Mac OS X.

Getting Perforce


Perforce requires at least two executables: the server (p4d), and any of the Perforce client programs (for instance, p4 on UNIX, p4.exe or p4win.exe on Windows).

The programs 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.

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. Briefly:

Download the files and make them executable

On UNIX (or MacOS X), you'll also have to make the Perforce executables (p4 and p4d) executable. After downloading the programs, use the chmod command to make them executable:

chmod +x p4
chmod +x p4d

Create a Perforce server root directory

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" on page 18 and described in more detail in "Disk space allocation" on page 92.

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.

You are strongly advised not to run p4d as root or any other privileged user. For more information, see the section entitled "UNIX: Run p4d as a non-privileged user" on page 22.

The environment variable P4ROOT should be set to point to the server root. Alternatively, the -r root_dir flag can be provided when p4d is started to specify a 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.

Unlike P4ROOT, the environment variable P4PORT is used by both the Perforce server and Perforce client programs, and should be set on both. Its use is discussed in the next two sections.

Telling the Perforce server which port to listen to

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 with the -p port_num flag when starting p4d (as in, p4d -p 1818), or the port can be set with the P4PORT environment or registry variable.

Telling Perforce client programs which port to talk to

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.

Examples:

If P4PORT is...
Then...

dogs:3435

The client program uses the p4d server on host dogs listening at port 3435.

x.com:1818

The client program uses the p4d server on host x.com listening at port 1818.

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.

Examples:

If P4PORT is...
Then...

3435

The client program will use the p4d server on its local host listening at port 3435.

<not set>

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

Starting the Perforce server

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

Although this command is sufficient to run p4d, other flags, for instance, those that control such things as error logging, checkpointing, and journaling, can be provided.

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

Installing Perforce on Windows


Installation of Perforce on Windows is handled by the installer. You can get the installer by downloading it from the Downloads page of the Perforce web site.

The Perforce installer (perforce.exe) allows you to:

This option allows for the installation of p4.exe (the Perforce Comnand-Line Client), p4win.exe (P4Win, the Perforce Windows Client), and p4scc.dll (Perforce's implementation of the Microsoft common SCM interface).

These options allow for the installation of both the Perforce client software as well as the Perforce Windows server (p4d.exe) and service (p4s.exe) executables.

You can also use either of these options to automatically upgrade an existing Perforce server or service running under Windows.

Under Windows 2000 or higher, you will need Administrator privileges to install Perforce as a service, and Power User privileges to install Perforce as a server.

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

Terminology note: Windows services and servers

In most cases, it makes no difference whether the Perforce server program was installed on UNIX, as an NT service, or as an NT server. Consequently, the terms "Perforce server" and "p4d" are used interchangeably to refer to "the process which handles requests from Perforce clients". In cases where the distinction between an NT server and an NT service are important, the distinction is made.

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 started either as an NT service (p4s.exe), which can be set to run at boot time, or as an NT server (p4d.exe), which is invoked from an MS-DOS 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, they 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 named p4smyservice.exe or p4dmyserver.exe will invoke a service and a server, respectively.)

In most cases, you will want to install Perforce as a service, not a server. For a more detailed discussion of the distinction between the two options, see "Windows services vs. Windows servers" on page 105.

Starting and stopping Perforce on Windows

If you're running Perforce as a service under Windows, it will be started when the machine boots. You can configure it within the Services applet in the Control Panel.

If you're running Perforce as a server under Windows, invoke p4d.exe from an MS-DOS command prompt. The flags under Windows are the same as those under UNIX.

If you are running Perforce 99.2 or above, whether as a service or a server, use the command

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

For older revisions of Perforce, you'll have to shut down services by using the Services applet in the Control Panel, and servers running in MS-DOS windows by typing CTRL-C in the window or clicking on the icon to Close the window.

While these options will work with both Release 99.2 and earlier versions of Perforce, they are 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, their use is no longer recommended.

Upgrading a Perforce Server


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

Warning!

If you are upgrading to 2001.1 or later, it is imperative that you read the notes pertaining to the 2001.1 upgrade.

Using old client programs with a new server

Although pre-98.1 Perforce client programs (p4, p4.exe, p4win.exe, and p4scc.dll) generally work with newer server versions with no trouble, some features in new server releases require client upgrades. In general, users with older client programs will still be able to use features available from the Perforce server at the client's release level, but will not be 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 of your Perforce servers are at or above Release 98.2.

Important Notes for 2001.1 and later

On small installations (installations with fewer than 1000 submitted changelists), the 2001.1 server automatically upgrades the underlying database for versions 98.2 and up.

On larger installations, you will have to upgrade the database manually. Although the new database will likely be smaller than the pre-2001.1 database, the upgrade process can be disk space-intensive. You will need approximately three times the size of the existing database to store the temporary files required by the upgrade.

Note

If you are disk space-constrained, 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), it may be possible to 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, you will likely have to make an intermediate checkpoint. Please contact Perforce technical support for assistance before upgrading your server.

UNIX upgrades

To upgrade your current Perforce server to a newer version, your Perforce license file must be current. Expired licenses will not work with upgraded servers. (This is not a problem if you are running a two-user installation with no license.)

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

It is a good idea to run p4 verify as part of your upgrade. See "Verifying during server upgrades" on page 44 for details.

Warning!

Upgrading to Release 2001.1 or later will require an upgrade of your database files. Downgrading thereafter will require restoration from backups.

If you wish to keep your pre-2001.1 server available as a fallback option when performing your 2001.1 upgrade, you should back up your entire server root (including the db.* files) after stopping 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 will run automatically. Larger installations will require that p4d -xu be run manually.

    Either way, you must have sufficient disk space to complete the upgrade. The required amount is typically two to three times the size of the larger of the db.have or db.integ files.

    The db.have and db.integ files reside in your P4ROOT directory.

  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; if any error condition occurs during the upgrade, you will always be able to revert to using your pre-upgrade Perforce server or service.

Note

If your server has fewer than 1000 changes, the upgrade will run automatically. Larger installations will require that p4d -xu be run manually.

Either way, you must have sufficient disk space to complete the upgrade. The required amount is typically two to three times the size of the larger of the db.have or db.integ files.

The db.have and db.integ files reside in your P4ROOT directory.

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 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:

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 usually 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 sure that if a disk failure corrupts the drive containing P4ROOT, it will not affect your journal file. The journal file can then be used 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. The administrator who installs Perforce should use:

to define a Perforce superuser as soon as possible after installing the Perforce server. For more information, see "Administering Perforce: Protections" on page 61

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.

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

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:

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.

As of this writing, the following combinations of operating system and Perforce server revision will support database files larger than 2GB:

Operating System
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 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 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 will query for an account name and a password. The Perforce service will be configured with the supplied data and run as the specified user instead of System. (This account must have Administrator privileges on the machine.)

Although Perforce operates reliably with its root directory on a network drive, does so at a substantial performance penalty, as all writes to the database have to be performed over the network. For optimal performance, it is still best to 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 107.

UNIX: 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.

Windows

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

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 p4d's 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 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.


Perforce 2002.2 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-2002 Perforce Software. All rights reserved.
Last updated: 12/18/02