A short checklist of things to consider at installation time is offered, along with some basic security and administration tips. More detailed notes on administrative tasks are found in later chapters.

Getting Perforce

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

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

Installing Perforce on UNIX

To limit access to the Perforce server files, we recommend that p4d be owned and run by a Perforce user account that has been created for that purpose.

Once you've downloaded p4 and p4d, you need to do a few more things before you can use Perforce. Briefly:

• Download the files and make them executable,

• Create a root directory for the Perforce files,

• Provide a TCP/IP port to p4d,

• Provide the name of the Perforce server and the p4d port number to the Perforce client program(s), and

• Start the Perforce server (p4d).

Download the files and make them executable

Create a Perforce server root directory

Since Perforce will store all submitted files under this directory, the size of the directory can become quite large. Disk space management is reviewed in "Installation and Administration Tips" on page 18 and described in more detail in "Disk space allocation" on page 92.

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.

You are strongly advised not to run p4d as root or any other privileged user. For more information, see the section entitled "UNIX: Run p4d as a non-privileged user" on page 22.

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 client programs, and should be set on both. Its use is discussed in the next two sections.

Telling the Perforce server which port to listen to

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

Telling Perforce client programs which port to talk to

Examples:

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

Examples:

If your p4d host is not named perforce, you can choose to simplify life somewhat for your Perforce users by setting perforce as an alias to the true host name in their workstations' /etc/hosts files, or by doing so via Sun's NIS or Internet DNS.

Starting the Perforce server

p4d &

Example:  Starting a Perforce server.

P4PORT can be overridden by starting p4d with the -p flag, and P4ROOT can be overridden by starting p4d with the -r flag. A journal file may be specified with the -J flag, and errors may be logged to a file specified with a -L flag. The startup command would then have this form:

p4d -r /usr/local/p4root -J /var/log/journal -L /var/log/p4err -p 1818 &

These flags (and others) are discussed in "Supporting Perforce: Backup and Recovery" on page 25. A complete list of server flags appears in the "Perforce Server (p4d) Reference" on page 111.

Stopping the Perforce server

p4 admin stop

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.

Installing Perforce on Windows

The Perforce installer (perforce.exe) allows you to:

• Install Perforce client software ("User install").

This option allows for the installation of 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 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.

• Uninstall Perforce: remove the Perforce server, service, and client executables, registry keys, and service entries. The database and depot files in your server root, however, will be preserved.

Terminology note: Windows services and servers

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 example, 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 "Windows services vs. Windows servers" on page 105.

Starting and stopping Perforce on Windows

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

p4 admin stop

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.

Upgrading a Perforce Server

Using old client programs with a new server

Perforce's remote depot support is an exception: remote depot support is not guaranteed to work unless all of your Perforce servers are at or above Release 98.2.

Important Notes for 2001.1

On larger installations, you will have to upgrade the database manually. Although the new database will likely be smaller than the pre-2001.1 database, the upgrade process can be disk space-intensive. You will need approximately three times the size of the existing database to store the temporary files required by the upgrade.

If you are upgrading from Release 97.3 or earlier to 2001.1, you will likely have to make an intermediate checkpoint. Please contact Perforce technical support for assistance before upgrading your server.

UNIX upgrades

You must back up your server as described on "Backup Procedures" on page 31 as part of any upgrade process.

It is a good idea to run p4 verify as part of your upgrade. See "Verifying during server upgrades" on page 44 for details.

Upgrading from UNIX Release 98.2 or later

1. Download the new p4d executable for your platform

2. Stop the current instance of p4d

3. Make a checkpoint and back up your old installation

4. Install the new p4d in the desired location

5. Run p4d -xu to upgrade the database.

   Note

   If your server has fewer than 1000 changes, the upgrade will run automatically. Larger installations will require that p4d -xu be run manually. Either way, you must have sufficient disk space to complete the upgrade. The required amount is typically two to three times the size of the larger of the db.have or db.integ files. The db.have and db.integ files reside in your P4ROOT directory.

6. Restart the new p4d with your site's usual parameters.

Windows upgrades

The upgrade process on Windows is extremely conservative; if any error condition occurs during the upgrade, you will always be able to revert to using your pre-upgrade Perforce server or service.

If you have any questions or difficulties during an upgrade, contact Perforce technical support.

Installation and Administration Tips

Release and license information

This licensing information lives in a file called license in the server root directory. It is a plain text file supplied by Perforce Software. Without the license file, the Perforce server will limit itself to two users and two client workspaces.

Current licensing information may be viewed by invoking p4d -V from the server root directory or by specifying the server root directory either on the command line (p4d -V -r server_root) or in the P4ROOT environment variable.

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

Version information will be displayed when invoking p4d -V or p4 -V.

Observe proper backup procedures

• Make sure journaling is active,

• Create checkpoints regularly, and

• Use p4 verify regularly.

Use separate filesystems for server root and journal

By storing the journal on a separate drive, you can be reasonably sure that if a disk failure corrupts the drive containing P4ROOT, it will not affect your journal file. The journal file can then be used to restore any lost or damaged metadata.

Further details are available in "Supporting Perforce: Backup and Recovery" on page 25.

Use protections and passwords

p4 protect

Furthermore, until your users have passwords defined, any user will be able to impersonate any other Perforce user, either with the -u flag or by setting P4USER to a Perforce user's username. Proper use of Perforce passwords (as described in the Perforce User's Guide) can protect against this. See the Perforce User's Guide for details.

To set (or reset) a user's password, use p4 passwd username (as a Perforce superuser), and enter the new password for the user, or invoke p4 user -f username (also while as a Perforce superuser) and enter the new password into the user specification form. The former command will only work in release 99.1 or later; the latter command will work under all releases from 97.3 onwards.

The security-conscious Perforce superuser will use p4 protect to make sure that no access higher than list is granted to non-privileged users, and require that each user have a Perforce password.

Allocate disk space for anticipated growth

For a more detailed example of a disk sizing estimate, see "Disk space allocation" on page 92.

Managing disk space after installation

• Tell Perforce to store the journal file on a separate physical disk. Use the P4JOURNAL environment variable or p4d -J to specify the location of the journal file.

• Checkpoint on a daily basis to keep the journal file short.

• Compress checkpoints, or use the -z option to tell p4d to compress them while creating them.

• Use the -jc prefix option with the p4d command to write the checkpoint to a different disk. Alternately, use the default checkpoint files, but back up your checkpoints and then delete them from the root directory. Old checkpoints are needed when recovering from a crash, and if your checkpoint and journal files reside on the same disk as your depot, a hardware failure could leave you without the ability to restore your database.

• On UNIX systems, some or all of the depot directories may be relocated to other disks by using symbolic links. Creation of symbolic links and movement of depot files to other volumes should be done only while the Perforce server is not running.

• Due to the nature of the implementation of their access methods, the database files themselves may become internally unbalanced, resulting in them taking up more space than necessary. The database files can sometimes be reduced in size by recreating them from a checkpoint. This should be done only if the database files are more than about 10 times the size of the checkpoint in total. See "Checkpoints for Database Tree Rebalancing" on page 102.

Large filesystem support

The db.have file holds label contents and the list of files currently opened in client workspaces, and tends to grow the most quickly. If you anticipate any of your Perforce database files growing beyond the 2GB level, you should install the Perforce server on a platform with support for large files.

As of this writing, the following combinations of operating system and Perforce server revision will support database files larger than 2GB:

UNIX and NFS support

Consequently, under Solaris 2.6 or higher, you can store your journal, log, depot, and db.* files on NFS-mounted filesystems.

Some issues still remain regarding file locking on non-commercial implementations of NFS (for instance, Linux and FreeBSD). On these platforms, we recommend that you store your journal, log, depot, and db.* files on a drive local to the server machine, not on an NFS-mounted volume.

These issues affect only the Perforce server process (p4d). Perforce clients (such as the p4 command-line client) have always been able to work with client workspaces on NFS-mounted drives, such as workspaces located in users' home directories.

Windows: Username and password required for network drives

Although Perforce operates reliably with its root directory on a network drive, does so at a substantial performance penalty, as all writes to the database have to be performed over the network. For optimal performance, it is still best to install the Windows service to use local drives rather than networked drives.

For more information, see "Installing the Perforce service on a network drive" on page 106.

UNIX: Run p4d as a non-privileged user

A good way to manage a Perforce installation on UNIX is to create a UNIX userid for it (for example, "perforce") and (optionally) a UNIX group for it (for example, "p4admin"). The umask(1) command can be used to ensure that the server root (P4ROOT) and all files and directories beneath it are created as writable only by the UNIX user perforce, and (optionally) readable by members of the UNIX group p4admin.

The Perforce server (p4d), running as UNIX user perforce, can write to files in the server root, but none of your users will be able to overwrite its files. Access to read the files created by p4d (that is, the depot files, checkpoints, journals, and so on) can be granted to trusted users by making them members of the UNIX group p4admin.

Logging errors

Although p4d tries to ensure that all error messages reach the user, if an error occurs and the client program disconnects before the error is received, p4d will also log these errors to its error output.

The Perforce server also has trace flags used for debugging purposes. See "Perforce server trace flags" on page 52 for details.

Case sensitivity issues

Tune for performance

For more detailed performance tuning information, see "Tuning Perforce for Performance" on page 91.