Perforce 98.2: Sys Admin: Installation & Upkeep

Perforce 98.2 p4 User's Guide


<< Previous Chapter Reporting	Table of Contents Index Perforce on the Web	Next Chapter >> Sys Admin: Protections

Chapter 13
System Administration: Installation & Upkeep

Installation of p4d and p4

95/98/NT

Installation of Perforce on Windows machines is handled by the installer. If you're using Perforce on Windows, you can skip to the protections and journaling sections, both of which start on page 103.

Perforce operation requires two executables: p4d, the server, and p4, the client. If you haven't already downloaded these, they may be retrieved from http://www.perforce.com/perforce/load.html.

The p4 program typically resides in /usr/local/bin, and p4d is usually located in /usr/local/bin or in its own root directory (see below), although they can be installed anywhere. The p4 program can be installed on any server that has TCP/IP access to the p4d host.

To limit access to the p4d 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: a root directory for the p4d files is created, a TCP/IP port is provided to p4d, and p4 is provided the name of the p4d host and number of the p4d port. These steps are described in the following sections.

Creating a p4d Root Directory

p4d stores all of its data in files and subdirectories of its own root directory, which can reside anywhere on the server system. This directory can be named anything at all, and the only necessary permissions are read and write for the user who starts p4d, and this directory should be owned by the account that runs p4d. Since p4d will store all submitted files in this directory, the size of the directory can eventually become quite large. Disk space management is described later in this chapter.

For safety's sake, type the command chmod 700 directoryname on UNIX systems to prevent anyone but the account owner from reading, modifying or even listing the actual depot files.

The environment variable P4ROOT should be set to point to this directory. Alternatively, the -r flag can be provided when p4d is started (see below). The p4 clients never directly use this directory, so they don't need to know the value of P4ROOT.

Setting p4d's Port

p4d and p4 communicate via TCP/IP. When p4d starts, it will, by default, listen on port 1666. The p4 client will, 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 flag when starting p4d (example: p4d -p 1818), or the port can be set with the P4PORT environment variable. Chances are that your p4d host is not named perforce, but you can simplify life somewhat for your p4 users by setting perforce as an alias to the true host name in the host's /etc/hosts file, or by doing so via Sun's NIS or Internet DNS.

Telling p4 Where The p4d Server Is

The p4 client program needs to know on which TCP/IP port the p4d server program is listening. p4 can be told which host and port the p4d server program is listening on by setting each p4 user's P4PORT environment variable to host:port# , where host is the name of the host that p4d is running on, and port# is the port that p4d is listening on.

Examples:


If P4PORT is...	Then...
`dogs:3435`	p4 will communicate with the p4d server on host dogs listening at port 3435.
`x.com:1818`	p4 will communicate with the p4d server on host x.com listening on port 1818.

The definition of P4PORT can be shortened if p4 is running on the same host as p4d. In this case, only the p4d port number need be provided to p4. If p4d is running on a host named or aliased perforce, listening on port 1666, the definition of P4PORT for the p4 client can be dispensed with altogether.

Examples:


If P4PORT is...	Then...
`3435`	p4 will communicate with the p4d server on its local host listening at port 3435.
`<not set>`	p4 will communicate with the p4d server on the host named or aliased `perforce` listening on port 1666.

Starting p4d: The Basics

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

p4d &

P4PORT can be overridden by starting p4d with the -p flag, and P4ROOT will be ignored if the -r flag is provided. The startup command would then have this form:

p4d -r /usr/local/p4files -p 1818 &

Although this command is sufficient to run p4d, other flags, which control such things as error logging, checkpointing, and journaling, can and should be provided. These flags are discussed in the next two sections.

Logging Errors

The p4d program tries to ensure that all error messages reach the user, but if an error occurs and the client program disconnects before the error is sent, p4d logs the error to its error output. The 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 the p4d program's standard error.

Protections

By default, every Perforce user is a Perforce superuser, and can run any Perforce command on any file. These default access levels are changed easily with the p4 protect command; the administrator who installs Perforce should run p4 protect soon after installing p4 and p4d. Access levels are described in detail in the next chapter.

Proper use of passwords can prevent Perforce users from impersonating each other with the -u flag. Please see page 50 for details.

Checkpointing, Journaling, and Recovery

! Warning !

Checkpoints and journals archive only the database files, not the files in the depot directories! Back up the depot files with the standard OS backup commands after checkpointing, as the static checkpoint can be dumped and restored consistently, while the dynamic database files might change during the backup, and may be inconsistent.

Two sets of files in the p4d root directory are sufficient to recover the complete p4d server data:

p4d stores its metadata in the top level of its root directory; all of these files are binary, and begin with "db.".
Files submitted by p4 clients are stored in p4d subdirectories that have the same names as the depots. By default, there is only one of these subdirectories; its name is depot.

p4d provides checkpointing and journaling facilities for recovery of the metadata database files. A checkpoint is just a snapshot or copy of the database files at a particular moment in time, and a journal is a log that records updates since that snapshot. If the database files become corrupted, or if there's a disk crash, you can recover the files by reloading the checkpoint and applying the changes stored in the journal. Both the checkpoint and journal are text files, and have the same format.

Because the data stored in the Perforce database is irreplaceable, journaling and checkpointing should be performed early and regularly.

Making a Checkpoint

You can create a checkpoint by invoking the p4d program with the -jc flag:

% p4d -r root -jc

This can be run while the p4d server is running. To make the checkpoint, p4d locks the entire database and then dumps the database contents to a file named checkpoint.x, where x is a sequence number. Before unlocking the database, p4d copies and then truncates the journal file if it exists. This action guarantees that the last checkpoint combined with the current journal always reflects the database.

A different checkpoint file can be specified by typing a filename after the -jc flag:

% p4d -r root -jc /disk2/perfback/ckp

A checkpoint file may be compressed, archived, or moved onto another disk. At that time or shortly thereafter, the files in the depot subdirectories should be archived as well. When recovering, the checkpoint must be no newer than the files in the depots.

The checkpoint file is often much smaller than the original database, and can be made smaller still by compressing it. The journal file, on the other hand, can grow quite large; it is truncated whenever a checkpoint is made, but the older journal is backed up and saved. The older journal files can then be moved to external media, freeing up more space locally.

Since checkpoints are readable only by the server version that created them, a new checkpoint should be taken every time the p4d server is upgraded.

Regular checkpointing is important if journaling is turned on, to keep the journal from getting too long. Making a checkpoint just before dumping the file system is simply good practice.

Turning Journaling On and Off

By default, the journal is written to the file journal in the p4d root directory. The name and location of this file can be changed by specifying the name of the journal file in the environment variable P4JOURNAL, or by providing a -J filename flag to p4d. In either case, the journal file name can be provided as an absolute path, or as a path relative to the p4d server root.

! Warning !

If you create a journal file with the
-J filename flag, make sure that subsequent checkpoints use the same file, or the checkpoint will not be properly truncated.

To create a journal, do one of the following:

Create an empty journal file in the server root, then start p4d;
Set the P4JOURNAL environment variable to point to any file, then start p4d; or
Start p4d with the -J filename flags.

Be sure to create a new checkpoint with the p4d -jc flag immediately after starting a new journal, since a journal without a checkpoint is useless. Since there is no sure protection against disk crashes, the journal file and the p4d root directory should be located on different disks.

To disable journaling, remove the existing default journal file (if it exists), unset the environment variable P4JOURNAL, and type the p4d command again without the -J flag.

Recovering

If the database files become corrupted or lost, either because of disk errors, errors in the p4d program itself, or a disk crash, the files can be recreated with your stored checkpoint and journal. To do this, kill p4d, remove the database ("db.") files, and then invoke the p4d program with the -jr flag:

% rm root/db.* % p4d -jr checkpoint_file journal_file

After recovering the database you will need to restore the depot files with the UNIX restore command to ensure that they are as new as the database.

Managing Disk Space

All of p4d's stored source files reside in subdirectories of the p4d root, as do its database files, and by default the checkpoints and journals. The stored source 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:

Store the journal file on a separate 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 after they are made.
Use the -jc checkpointfile option with the p4d command to write the checkpoint to a different disk. Or use the default checkpoint files, but backup your checkpoints and then delete them from the root directory. They aren't needed unless you are recovering.
[UNIX only] If necessary, all or part of the depot subdirectories may be relocated to other disks, using symbolic links from the depot trees. This should be done while the p4d server is not running.
The database files can become internally bloated, due to the nature of the implementation of their access methods. They can sometimes be compressed by recreating them from a checkpoint: take a checkpoint, delete the database files, then recover. This should only be done if the database files are more than about 10 times the size of the checkpoint in total.

License File

Perforce servers are licensed according to how many users they will support. This licensing information lives in a file called license in the p4d root directory. It is a plain text file supplied by Perforce Software. Without this license file, the p4d server will limit itself to two users and two client workspaces.

The current licensing information can be viewed by invoking p4d -V from the server root directory.

When the server is running, the license information can also be viewed with p4 info.

Release and License Information

The p4 client and p4d server programs will display their version and license information with the -V flag. The p4 info command will attempt to connect to the server and display its license information (among other things). Version information can also be gleaned from p4 or p4d executables with the UNIX what(1) command.

Perforce 98.2 p4 User's Guide


<< Previous Chapter Reporting	Table of Contents Index Perforce on the Web	Next Chapter >> Sys Admin: Protections