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.
Only a few 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.
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 of this chapter.
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. 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 on page 99.
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.
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.
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.
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:
After p4d's P4PORT and P4ROOT environment variables have been set, p4d can be run in the background with the command
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:
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.
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.
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.
Two sets of files in the p4d root directory are sufficient to recover the complete p4d server data:
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.
You can create a checkpoint by invoking the p4d program with the -jc flag:
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:
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.
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.
To create a journal, do one of the following:
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.
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:
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.
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:
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.
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.