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.

Installing Perforce on UNIX

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

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 14 and described in more detail in "Diskspace allocation" on page 66.

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

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

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

Examples:

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

p4d &

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 19. A complete list of server flags appears in the "Perforce Server (p4d) Reference" on page 79.

Stopping the Perforce server

p4 admin stop

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

Installing Perforce on NT

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 GUI), 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.

Terminology note: NT services and servers

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

Starting and stopping Perforce on NT

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, whether as a service or a server under NT, use the command

p4 admin stop

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.

Upgrading a Perforce Server

UNIX Upgrades

In addition to the steps described below, it is a good idea to run p4 verify as part of your upgrade. See "Verifying during server upgrades" on page 31 for details.

Whenever upgrading, it's wise to save your current p4d executable (and a copy of your old database, as stored in a checkpoint) rather than overwriting it with the new one; this will give you a quick, easy way to back out the upgrade should the need arise. For details, see "Backup Procedures" on page 22.

Upgrading from UNIX Release 98.2 or later

1. Downloading the new p4d executable for your platform,

2. Stopping the current instance of p4d,

3. Making a checkpoint and backing up your old installation,

4. Installing the new p4d in the desired location,

5. Restarting the new p4d with your site's usual parameters.

Upgrading from UNIX Release 98.1

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. Restart p4d with your site's usual parameters.

6. Reindex the jobs tables with:
   p4 jobs -R

   Note	Reindexing the jobs tables for releases prior to 98.2 is required because of a change made in the database structure between 98.1 and 98.2 to facilitate fast keyword searching of jobs.

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

Upgrading from UNIX Release 97.3

1. Stop the current instance of p4d.

2. Create a checkpoint file using:
   p4d -r $P4ROOT -jc

3. Make a complete backup of everything in your P4ROOT (server root) directory.

4. Install the new p4d.

5. Remove the existing db.* files from your P4ROOT directory.

6. Create new db.* files from the checkpoint using:
   p4d -r $P4ROOT -jr checkpoint.n

   where n is the numeric suffix appended to the name of the checkpoint file.

7. Restart p4d with your site's usual parameters.

8. Reindex the jobs tables with:
   p4 jobs -R

   Note	Reindexing the jobs tables for releases prior to 98.2 is required because of a change made in the database structure between 98.1 and 98.2 to facilitate fast keyword searching of jobs.

Upgrading from a pre-97.3 UNIX release

1. Stop the current instance of p4d.

2. Download the 97.3 version of p4d and name it p4d.973.

3. Create a checkpoint using the 97.3 server using:
   p4d.973 -r $P4ROOT -jc

4. Make a complete backup of everything in P4ROOT.

5. Download the new p4d and install it in the desired location.

6. Remove the existing db.* files from P4ROOT.

7. Create new db.* files from the checkpoint using:
   p4d -r $P4ROOT -jr checkpoint.n

8. Restart p4d with your site's usual parameters.

9. Reindex the jobs tables with:
   p4 jobs -R

   Note	Reindexing the jobs tables for releases prior to 98.2 is required because of a change made in the database structure between 98.1 and 98.2 to facilitate fast keyword searching of jobs.

NT upgrades

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.

Installation and Administration Tips

Release and license information

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

• Make sure journaling is active,

• Create checkpoints regularly,

• Use p4 verify regularly.

Use separate filesystems for server root and journal

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

Use protections and passwords

p4 protect

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

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

Managing disk space after installation

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

Large filesystem support

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:

UNIX: Install servers on non-NFS filesystems

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

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

UNIX and NT: Run p4d as a non-privileged user

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.

Logging errors

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

Case-sensitivity issues

Tune for performance

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