Perforce 2003.2 User's Guide


<< Previous Chapter Reporting and Data Mining	Table of Contents Index Perforce on the Web	Next Chapter >> Environment Variables

Appendix A
Installing Perforce

This appendix outlines how to install a Perforce server for the first time.

This appendix is mainly intended for people installing an evaluation copy of Perforce for trial use; if you're installing Perforce for production use, or are planning on extensive testing of your evaluation server, we strongly encourage you to read the detailed information in the Perforce System Administrator's Guide.

Getting Perforce

Perforce requires at least two executables: the server (p4d), and at least one Perforce client program (such as p4 on UNIX, or p4.exe or p4win.exe on Windows).

The server and client executables are available from the Downloads page on the Perforce web site:

http://www.perforce.com/perforce/loadprog.html

Go to the web page, select the files for your platform, and save the files to disk.

Installing Perforce on UNIX

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

After downloading p4 and p4d, you need to do a few more things before you can start using Perforce:

Make the downloaded p4 and p4d files executable.
Create a server root directory to hold the Perforce database and versioned files.
Provide a TCP/IP port to p4d to tell the Perforce server what port to listen to.
Provide the name of the Perforce server and the p4d port number to the Perforce client program(s).
Start the Perforce server (p4d).

Download the files and make them executable

On UNIX (or MacOS X), you must also make the Perforce executables (p4 and p4d) executable. After downloading the programs, use the chmod command to make them executable, as follows:


`chmod +x p4 chmod +x 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.

To specify a server root, set the environment variable P4ROOT to point to the server root, or use the -r root_dir flag when invoking p4d. Perforce client programs never use the P4ROOT directory or environment variable; the p4d server is the only process that uses the P4ROOT variable.

A Perforce server requires no privileged access; there is no need to run p4d as root or any other privileged user. See the System Administrator's Guide for details.

The server root can be located anywhere, but the account that runs p4d must have read, write, and execute permissions on the server root and all directories beneath it. For security purposes, set the umask(1) file creation-mode mask of the account that runs p4d to a value that denies other users access to the server root directory.

Telling the Perforce server which port to listen to

The p4d server and Perforce client programs communicate with each other using TCP/IP. When p4d starts, it listens (by default) on port 1666. The Perforce client assumes (also by default) that its p4d server is located on a host named perforce, listening on port 1666.

If p4d is to listen on a different port, specify that port with the -p port_num flag when starting p4d (as in, p4d -p 1818), or set the port with the P4PORT environment or registry variable.

Unlike P4ROOT, the environment variable P4PORT is used by both the Perforce server and Perforce client programs, and must be set on both Perforce server machines and Perforce client workstations.

Starting the Perforce server

After setting p4d's P4PORT and P4ROOT environment variables, start the server by running p4d in the background with the command:

p4d & Although the example shown is sufficient to run p4d, other flags that control such things as error logging, checkpointing, and journaling, can be provided. These flags (and others) are discussed in the Perforce System Administrator's Guide.

Stopping the Perforce server

To shut down a Perforce server, use the command:

p4 admin stop to gracefully shut down the Perforce server. Only a Perforce superuser can use p4 admin stop.

If you are running a release of Perforce from prior to 99.2, you must find the process ID of the p4d server and kill the process manually from the UNIX shell. Use kill -15 (SIGTERM) instead of kill -9 (SIGKILL), as p4d might leave the database in an inconsistent state if p4d is in the middle of updating a file when a SIGKILL signal is received.

Telling Perforce clients which port to talk to

By this time, your Perforce server should be up and running; see "Connecting to the Perforce Server" on page 21 for information on how to set up your environment to allow Perforce's client programs to talk to the server.

Installing Perforce on Windows

To install Perforce on Windows, use the Perforce installer (perforce.exe) from the Downloads page of the Perforce web site.

The Perforce installer allows you to:

Install Perforce client software ("User install").

This option allows you to install 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 a Windows server or service as appropriate. ("Administrator typical" and "Administrator custom" install).

These options allow you to install Perforce client programs and the Perforce Windows server (p4d.exe) and service (p4s.exe) executables, or to automatically upgrade an existing Perforce server or service running under Windows.

Under Windows 2000 or higher, you must have Administrator privileges to install Perforce as a service, and Power User privileges to install Perforce as a server.

Uninstall Perforce: remove the Perforce server, service, and client executables, registry keys, and service entries. The Perforce database and the depot files stored under your server root are preserved.

Terminology note: Windows services and servers

The terms "Perforce server" and "p4d" are used interchangeably to refer to "the process which handles requests from Perforce client programs". In cases where the distinction between an NT server and an NT service is important, the distinction is made.

On UNIX systems, there is only one Perforce "server" program (p4d) responsible for this back-end task. On Windows, however, the back-end program can be started either as a Windows service (p4s.exe) process that runs at boot time, or as a server (p4d.exe) process that must be invoked from a command 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, the executables use the first three characters of the name with which they were invoked (either p4s or p4d) to determine their behavior. (For example, invoking copies of p4d.exe named p4smyservice.exe or p4dmyserver.exe invoke a service and a server, respectively.)

In most cases, it is preferable to install Perforce as a service, not a server. For a more detailed discussion of the distinction between services and servers, see the Perforce System Administrator's Guide.

Starting and stopping Perforce on Windows

If you install Perforce as a service under Windows, the service starts whenever the machine boots. Use the Services applet in the Control Panel to control the Perforce service's behavior.

If you install Perforce as a server under Windows, invoke p4d.exe from a command prompt. The flags for p4d under Windows are the same as those used under UNIX.

To stop a Perforce service (or server) at Release 99.2 or above, use the command:

p4 admin stop Only a Perforce superuser can use p4 admin stop.

For older revisions of Perforce, shut down services manually by using the Services applet in the Control Panel. Shut down servers running in command prompt windows by typing CTRL-C in the window or by clicking on the icon to Close the command prompt window.

Although these manual shutdown options work with 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, the manual shutdown options are obsolete.