8. PERFORCE Administration Guide

This chapter describe how to start up a PERFORCE system. It does not explain how to convert an existing source repository to PERFORCE, but only how to start a new one.

8.1. Defaults

PERFORCE has several defaults built in to avoid requiring users to set environment variables.

8.2. Creating a Depot

The p4d program needs a directory to store its data. This directory must be created before invoking p4d for the first time. The p4d program puts its database files in this directory, and puts the stored source files under a subdirectory named "depot".

8.3. Starting the Server

Assuming the p4d server is going to listen on the default TCP/IP port number 1666, the server program needs only to know the root of its file tree. The simplest way to start it is then:

    % p4d -r /usr/local/p4root &

The p4d program takes special care 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. A shell script that captures standard error and the process id is probably the best way to start the server:

    #!/bin/sh

    cd /usr/local/p4root
    touch journal
    p4d -r . -p 1666 >> LOG 2>&1 & echo $! > PID

This script, which also turns on journalling (see below), can be invoked from the system startup scripts in /etc/rc (BSD dervied UNIX) or /etc/rc.d (SYSV dervied UNIX).

Startup scripts (such as the one above) are available for downloading from the PERFORCE home page at http://www.perforce.com.

8.4. Stopping the Server

The p4d program is a daemon which serves only to listen for incoming connections and then fork off a copy of itself to handle a client's request. The daemon itself may safely be killed at any time. If the above script was used to start the server, the server's process ID will be in root/PID.

8.5. Checkpointing, Journaling, Recovering

The p4d program stores its database files in the p4d root directory. These files are binary files and all begin with db. The p4d program has the ability to checkpoint, journal, and recover these files. A checkpoint is a just a snapshot of the database and a journal is a log recording updates since that snapshot. If the database files ever get corrupted, you can recover them by reloading the dump and subsequent journal. Both the dump and journal are text files, and they have the same format.

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, but it is truncated when a checkpoint is made.

The checkpointing, journaling, and recovering only affect the database files and not the archive files in the "depot" subdirectory. The "depot" files can be dumped and restored with the normal UNIX dump(8) and restore(8) commands. However, the database files should be checkpointed before being dumped and a corrupted or lost database should be recovered from the checkpoint. This is because the static checkpoint can be dumped and restored consistently, while the dynamic database files themselves may change during the course of a dump.

Making a Checkpoint

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

    % p4d -r root -jc

This can be run while the server p4d 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 truncates the journal file if it exists. This action guarantees that the last checkpoint combined with the current journal always reflects the database.

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

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

Turning Journaling On and Off

The p4d program writes to the file journal in the PERFORCE depot root directory if that file exists. To turn on journaling, create that file with the UNIX touch(1) command. To turn off journaling, remove the file. A journal file contains the updates to the database since the last checkpoint; therefore, you should turn on journaling either before starting p4d for the first time, or just before doing a checkpoint.

For maximum recoverability, the journal should be on a disk other than the database files. To do this, make the "journal" file a symbolic link to the actual journal file on another disk.

Recovering

If the database files get corrupted, either because of disk errors or errors in the p4d program itself, the files can be recreated with a checkpoint and (optionally) a journal. To do this, you must ensure there is no activity on the p4d server (killing it does this), remove the database files, and the invoke the p4d program with a special flag:

    % rm root/db.*
    % p4d -r root -jr checkpoint journal

After recovering the database you may need to restore the "depot" files to ensure that they are as new as the database.

8.6. Managing Disk Space

The p4d program expects its database, checkpoint, and journal files to live in the PERFORCE depot root directory. It also expects all stored source files to reside under the "depot" subdirectory, and this tree is grow-only. This can present disk space problems on high use systems. The following approaches may be used to remedy this:

  1. Put the journal file on a separate disk, using a symbolic link from the root directory.
  2. Checkpoint on a daily basis to keep the journal file short.
  3. Compress checkpoints after they are made.
  4. Delete checkpoints after they are backed up. They aren't needed unless you are recovering
  5. If necessary, all or part of the "depot" subdirectory may be relocated to other disks, using symbolic links from the "depot" tree. This should be done while the p4d server is not running.
  6. The database files can become interally bloated, due to the nature of the implementation of their access methods. They can be sometimes be compressed by recreating them from a checkpoint: first checkpoint, then delete the database files, then recover. This should only be done if the database files are in total more than about 10 times the size of the checkpoint.
  7. There is currently no support in PERFORCE for pruning unwanted data from the database and files from the depot. This feature is anticipated.

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

8.8. PERFORCE 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.