Welcome to Perforce: Installing and Upgrading

Perforce 2000.2 System Administrator's Guide (2000.2.sa.1)


<< 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 will describe how to install a Perforce server or upgrade an existing installation.

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.


95/98/NT	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 NT versions of Perforce differ, a note to that effect will be made. For NT-specific information, see "Perforce and NT" on page 69.

Installing Perforce on UNIX

Perforce operation requires two executables: the server (p4d), and any of the Perforce client programs (e.g. p4 on UNIX, p4.exe or p4win.exe on NT). If you haven't already downloaded these, they may be retrieved from the Downloads page on the Perforce web site.

Although p4 and p4d can be installed in any directory, on UNIX the Perforce client program typically resides 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, it is recommended that p4d be owned and run by a Perforce user account that has been created for that purpose.

Only a few additional steps need to be performed before p4 and p4d can be run. They are described in detail in the following sections. Briefly:

Create a root directory for the Perforce files,
Provide a TCP/IP port to p4d,
Provide the name of the Perforce server and the p4d port number to the Perforce client program(s),
Start the Perforce server (p4d).

Creating 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 touched on in "Installation and Administration Tips" on page 11 and described in more detail in "Diskspace allocation" on page 62.

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 and NT: Run p4d as a non-privileged user" on page 13.

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 clients, 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 will (by default) listen on port 1666. The Perforce client will (also by default) assume 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 (e.g. p4d -p 1818), or the port can be set with the P4PORT environment or registry variable.

Telling Perforce clients 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 will use the `p4d` server on host `dogs` listening at port `3435`.
`x.com:1818`	The client will use the `p4d` server on host `x.com` listening at port `1818`.

The definition of P4PORT can be shortened if the Perforce client 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 will use the `p4d` server on its local host listening at port `3435`.
`<not set>`	The client 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. NT administrators can do the same thing with NT's DNS capabilities or the %SystemRoot%\system32\drivers\etc\hosts file.

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:

p4d & Although this command is sufficient to run p4d, other flags, (e.g., those that control such things as error logging, checkpointing, and journaling), can be provided.

Example:

Starting a Perforce server

P4PORT can be overridden by starting p4d with the -p flag, and P4ROOT can be overridden by starting p4d with the -r flag. A journal file may be specified with the -J flag, and errors may be logged to a file specified with a -L flag. The startup command would then have this form:

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

These flags (and others) are discussed in "Supporting Perforce: Backup and Recovery" on page 15. A complete list of server flags appears in the "Perforce Server (p4d) Reference" on page 75.

Stopping the Perforce server

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

p4 admin stop 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.

With the appearance of p4 admin stop in Release 99.2, the practice of manually killing the p4d server has become obsolescent.

Installing Perforce on NT

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

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

Install Perforce client software ("User install").

This option allows for the installation of 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).

Install Perforce as either an NT server or service as appropriate. ("Administrator typical" and "Administrator custom" install).

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

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

Uninstall Perforce: remove the Perforce server, service, and client executables, registry keys, and service entries. The database and depot files in your server root, however, will be preserved.

For more about the Perforce NT installer, see "Using the Perforce installer" on page 69.

Terminology note: NT services and servers

In most cases, it makes no difference whether Perforce 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 will be made.

On UNIX systems, there is only one Perforce "server" program (p4d) responsible for this back-end task. On NT, 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 (i.e. either p4s or p4d) to determine their behavior. (i.e. 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 "NT services vs. NT servers" on page 70.

Starting and stopping Perforce on NT

If you're running Perforce as a service under NT, 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 NT, invoke it from an MS-DOS command prompt. The flags under NT are the same as those under UNIX.

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

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

For older revisions of Perforce, you'll have to shut down NT 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.

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:

Make sure journaling is active,
Create checkpoints regularly,
Use p4 verify regularly.

See "Supporting Perforce: Backup and Recovery" on page 15 for a full discussion of backup and restoration procedures.

Use separate filesystems for server root and journal

Whether installing on UNIX or NT, it is usually advisable to have your P4ROOT directory (i.e. your database and versioned files) on a different physical volume than your journal file.

By moving the journal to a separate volume, if a disk failure corrupts the volume containing the files in P4ROOT, you can be reasonably sure that it will not have affected your journal file. The journal file can then be used to restore any lost or damaged data. Further details are available in "Supporting Perforce: Backup and Recovery" on page 15.

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. For more information, see "Administering Perforce: Protections" on page 39

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 should use p4 protect to make sure that no access higher than list is granted to *, and require that each user have a Perforce password.

Allocate diskspace for anticipated growth

In general, you'll need sufficient space in your P4ROOT directory to hold your depot files (i.e. 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 diskspace to hold three times the size of your present collection of versioned files.

For a more detailed example of a disk sizing estimate, see "Diskspace allocation" on page 62.

Managing disk space after installation

All of p4d'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, using the P4JOURNAL environment variable or the -J flag to p4d.
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. (Remember, however, that the storage of Perforce versioned files on NFS-mounted disks is not recommended; this solution is intended to be implemented by linking to directories on other volumes which are also on drives local to the machine running p4d.)
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 68.

Large filesystem support

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

The db.have file, which holds label contents and the list of files currently opened in client workspaces, tends to grow the most quickly. If you anticipate your Perforce database files growing beyond the 2GB level, you should ensure that you are installing 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	All versions, SP5 recommended	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` upgrade required at OS level
Solaris	2.6 and higher	98.2/7488 compiled for 2.6 or higher

UNIX: Install servers on local filesystems

Perforce expects to have fast access to its database; both for performance reasons (on all platforms), and certain issues involving NFS filesystems and file locking (particularly on Linux and FreeBSD), we recommend that you not store your journal, log, depot, or db.* files on an NFS-mounted filesystem.

Perforce uses a client-server architecture; this means that Perforce clients never directly access the files in P4ROOT, and the only process needing access to P4ROOT is the p4d server itself. It is almost always preferable to ensure that the files used by Perforce are local to the machine running p4d.

NT: Username and password required for networked drives

By default, the Perforce service runs under the NT local System account. Since NT machines require a real account name and password to access files on a network drive, if Perforce is installed as a service under NT 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 will operate reliably with its root directory on a network drive, it will do so at a substantial performance penalty, as all writes to the database will have to be performed over the network. For optimal performance, it is still best to install the NT service to use local drives rather than networked drives.

For more information, see "Installing the Perforce NT service on a network drive" on page 71.

UNIX and NT: 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. In the case of Perforce, 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 (e.g., "perforce") and (optionally) a UNIX group for it (e.g., "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 in the server root (e.g. depot files, checkpoints, journals) can be granted to trusted users by making them members of the UNIX group p4admin.


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

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

Case-sensitivity issues

Whether your Perforce server is running on NT or UNIX, if your site is involved in cross-platform development (i.e. Perforce clients on both NT 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 32 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 61.

Upgrading a Perforce 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.)

We strongly recommend you back up your server as described on "Backup Procedures" on page 18 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 27 for details.


!Warning!	Upgrading to Release 2000.1 or later from release 99.2 or earlier will automatically upgrade your database files. Downgrading thereafter will require assistance from technical support. If you wish to have your 99.2 server available as a fallback option when performing your 2000.1 upgrade, you should back up your entire server root (including the db.* files) after stopping the 99.2 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, upgrading your Perforce server is as simple as:

Downloading the new p4d executable for your platform
Stopping the current instance of p4d,
Making a checkpoint and backing up your old installation,
Installing the new p4d in the desired location,
Restarting the new p4d with your site's usual parameters.

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

Upgrading from UNIX Release 98.1 or earlier

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 a new server release require a client upgrade. 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.

There are additional requirements associated with upgrading from early versions of Perforce:


!Warning!	Upgrades from release 98.1 require a reindexing of the jobs table because of a change in the database structure made between 98.1 and 98.2 for fast keyword searching of jobs. Upgrades from releases prior to 98.1 require more work: there was a change in database support in 98.1 which made it impossible to read database files from pre-98.1 (97.3 and earlier) servers. The 98.1 and later servers can, however, read 97.3 checkpoint files. Checkpoint files contain a plain text representation of all the data in the database files. Upgrades from releases prior to 97.3, however, require an interim checkpoint created with the 97.3 server.

Please contact Perforce technical support for assistance when upgrading from release 98.1 or earlier.

NT upgrades

On NT, all of the special requirements required when upgrading between older Perforce UNIX releases and the present release are handled automatically by the Perforce Windows installer. Simply download the installer (perforce.exe) and follow the installation dialog.

The upgrade process on NT 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.

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