Perforce 2002.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 any of the Perforce client programs (for instance, p4 on UNIX, p4.exe or p4win.exe on Windows).

The programs are available from the Downloads page on the Perforce web site:

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

Download the files and make them executable

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

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. This directory should be owned by the account that runs p4d, and can be named anything at all. The only necessary permissions are read, write, and execute for the user who invokes p4d.

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.

For security purposes, you are strongly advised not to run p4d as root or any other privileged user.

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

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

If p4d is to listen on a different port, the port can be specified with the -p port_num flag when starting p4d (for instance, p4d -p 1818), or the port can be set with the P4PORT environment or registry variable.

Starting the Perforce server

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

Although this command is sufficient to run p4d, other flags (for instance, those 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

If you are running Perforce 99.2 or later, use the command

to shut down the Perforce server.

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 introduction of p4 admin stop in Release 99.2, the practice of manually killing the p4d server has become obsolete.

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


Installation of Perforce on Windows is handled by the installer. You can get the installer by downloading it from the Downloads page of the Perforce web site.

This option allows for the installation of p4.exe (the Perforce Comnand-Line Client), p4win.exe (P4Win, the Perforce Windows Client), and p4scc.dll (Perforce's implementation of the Microsoft common SCM interface).

These options allow for the installation of both the Perforce client software as well as the Perforce Windows server (p4d.exe) and service (p4s.exe) executables.

You can also use either of these options to automatically upgrade an existing Perforce server or service running under Windows.

Terminology note: Windows services and servers

In most cases, it makes no difference whether the Perforce server program was installed on UNIX, as an NT service, or as an NT server. Consequently, the terms "Perforce server" and "p4d" are used interchangeably to refer to "the process which handles requests from Perforce clients". 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, 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 (either p4s or p4d) to determine their behavior. (For instance, 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 the Perforce System Administrator's Guide.

Starting and stopping Perforce on Windows

If you're running Perforce as a service under Windows, it will start when the machine boots. You can configure it within the Services applet in the Control Panel.

If you're running Perforce as a server under Windows, invoke p4d.exe from an MS-DOS command prompt. The flags under Windows are the same as those under UNIX.

If you are running Perforce 99.2 or above, whether as a service or a server, use the command

to shut down the service or server. Only a Perforce superuser may use this command.

For older revisions of Perforce, you'll have to shut down 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.


Perforce 2002.2 User's Guide
<< Previous Chapter
Reporting and Data Mining
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Environment Variables
Please send comments and questions about this manual to [email protected].
Copyright 1997-2002 Perforce Software. All rights reserved.
Last updated: 12/18/02