|
Chapter 1
|
Welcome to Perforce: Installing and Upgrading
|
This chapter includes a brief overview of things to consider at installation time, along with some basic security and administration tips. More detailed information on administrative tasks is found in later chapters.
Perforce requires at least two executables: the server (p4d), and at least one Perforce client program (such as
p4 on UNIX, or
p4.exe on Windows).
Although you can install p4 and
p4d 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. You can install Perforce client programs 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 the purpose of running the Perforce server.
|
1.
|
Download the p4 and p4d files for your platform from the Perforce web site.
|
|
6.
|
Specify the name or TCP/IP address of the Perforce server machine and the p4d port number to the Perforce client programs by setting the P4PORT environment variable.
|
On UNIX (or Mac OS X), you must make the Perforce executables (p4 and
p4d) executable. After you download the programs, use the
chmod command to make them executable, as follows:
The Perforce server stores all user-submitted files and system-generated metadata in files and subdirectories beneath its own root directory. This directory is called the
server root.
To specify a server root, either 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.
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.
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, either specify that port with the
-p port_num flag you start
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 the Perforce client programs, so it must be set on both Perforce server machines and Perforce client workstations.
Perforce client programs need to know on what machine the p4d server resides and on which TCP/IP port the
p4d server program is listening. Set each Perforce user's
P4PORT environment variable to
host:port, where
host is the name of the machine on which
p4d is running, and
port is the number of the port on which
p4d is listening.
If the Perforce client program is running on the same host as p4d, only the
p4d port number need be provided in
P4PORT. If
p4d is running on a host named or aliased
perforce, and is listening on port
1666, leave
P4PORT unset. For example:
If your p4d host is not named
perforce, you can simplify life somewhat for your Perforce users by setting
perforce as an alias to the true host name in your users' workstations'
/etc/hosts files, or by using Sun's NIS or Internet DNS.
After you set p4d's
P4PORT and
P4ROOT environment variables, start the server by running
p4d in the background with the command:
Although the example shown is sufficient to run p4d, you can specify other flags that control such things as error logging, checkpointing, and journaling.
You can override P4PORT by starting
p4d with the
-p flag, and
P4ROOT by starting
p4d with the
-r flag. Similarly, you can specify a journal file with the
-J flag, and an error log file with the
-L flag. A startup command that overrides the environment variables might look like this:
If you are running a release of Perforce from earlier than 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), because
p4d might leave the database in an inconsistent state if it is in the middle of updating a file when a
SIGKILL signal is received.
To install Perforce on Windows, use the Perforce installer (perforce.exe) from the Downloads page of the Perforce web site:
In this manual, the terms Perforce server and
p4d are used interchangeably to refer to "the process which handles requests from Perforce client programs" unless the distinction between a Windows server process a Windows service process is relevant.
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 configured to run as a Windows service (
p4s.exe) process that starts at boot time, or as a server (
p4d.exe) process that you invoke manually 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.)
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.
For older revisions of Perforce, shut down services manually by using the applet in the . Shut down servers running in command prompt windows by pressing CTRL-C in the window or by clicking the icon to close the command prompt window. Although manually shutting down in this way works with Release 99.2 and earlier versions of Perforce, it is 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, this manual shutdown method is obsolete.
You must back up your server (see
Backup procedures) as part of any upgrade process.
Although older Perforce client programs generally work with newer server versions, some features in new server releases require upgrades to Perforce client programs. In general, users with older client programs are able to use features available from the Perforce server at the client program's release level, but are not able to use the new server features offered by subsequent server upgrades.
Read the Release Notes for complete information on server upgrade procedures. In general, Perforce server upgrades require that you:
On UNIX, replace the old version of p4d with the new version downloaded from the Perforce website. On Windows, use the Perforce installer (
perforce.exe); the installer automatically replaces the server executable.
p4d -r server_root -J
journal_file -xu
Licensing information is contained in a file called license in the server root directory. The
license file is a plain text file supplied by Perforce Software. Without the
license file, the Perforce server limits itself to two users and five client workspaces.
To view current licensing information, invoke p4d -V from the server root directory where the
license file resides, or by specifying the server root directory either on the command line (
p4d -V -r server_root) or in the
P4ROOT environment variable.
If the server is running, you can also use p4 info to view your licensing information.
See Supporting Perforce: Backup and Recovery for a full discussion of backup and restoration procedures.
Whether installing on UNIX or Windows, it is advisable to have your P4ROOT directory (that is, the directory containing your database and versioned files) on a different physical drive than your journal file.
By storing the journal on a separate drive, you can be reasonably certain that, if a disk failure corrupts the drive containing
P4ROOT, such a failure will
not affect your journal file. You can then use the journal file to restore any lost or damaged metadata.
Without passwords, any user is able to impersonate any other Perforce user, either with the
-u flag or by setting
P4USER to an existing Perforce user name. Use of Perforce passwords prevents such impersonation. See the
P4 User's Guide for details.
To set (or reset) a user's password, either 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 is supported in release 99.1 or later; the latter command is supported under all releases from 97.3 onwards.
The security-conscious Perforce superuser also uses p4 protect to ensure that no access higher than
list is granted to nonprivileged users, and to ensure that each user has a Perforce password.
Because the collection of versioned files grows over time, a good guideline is to allocate sufficient space in your
P4ROOT directory to hold three times the size of your users' present collection of versioned files, plus an additional 0.5KB per user per file to hold the database files that store the list of depot files, file status, and file revision histories.
All of Perforce's versioned files reside in subdirectories beneath the server root, as do the database files, and (by default) the checkpoints and journals. If you are running low on disk space, consider the following approaches to limit disk space usage:
|
•
|
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 to a different drive and then delete the copied checkpoints from the root directory. Moving checkpoints to separate drives is good practice not only in terms of diskspace, but also because old checkpoints are needed when recovering from a hardware failure, 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, you can relocate some or all of the depot directories to other disks by using symbolic links. If you use symbolic links to shift depot files to other volumes, create the links only after you stop the Perforce server.
|
|
•
|
Use the p4 sizes command to monitor the amount of disk space currently consumed by your entire installation, or by selected portions of your installation. See Monitoring disk space usage.
|
Early versions of the Perforce server, as well as some operating systems, limit Perforce database files (the
db.* files in the
P4ROOT directory that hold your site's metadata) to 2 GB in size. The
db.have file holds the list of files currently synced to client workspaces, and tends to grow the most quickly.
If you anticipate any of your Perforce database files growing beyond the 2 GB level, install the Perforce server on a platform with support for large files. The following combinations of operating system and Perforce server revision support database files larger than 2 GB:
To maximize performance, configure the server root (P4ROOT) to reside on a local disk and not an NFS-mounted volume. The Perforce Server's file-locking semantics work with NFS mounts on Solaris 2.5.1 and later; some issues still remain regarding file locking on noncommercial implementations of NFS (for instance, Linux and FreeBSD).
These issues affect only the Perforce Server process (p4d). Perforce client programs (such as
p4, the Perforce Command-Line Client) have always been able to work with client workspaces on NFS-mounted drives, such as client workspaces located in users' home directories.
By default, the Perforce service runs under the Windows local System account. Because Windows requires a real account name and password to access files on a network drive, if Perforce is installed as a service under Windows with
P4ROOT pointing to a network drive, the installer requires an account name and a password. The Perforce service is then configured with the supplied data and run as the specified user instead of
System. (The account running the service must have
Administrator privileges on the machine.)
Although Perforce operates reliably with its root directory on a network drive, it does so only at a substantial performance penalty, because all writes to the database are performed over the network. For optimal performance, install the Windows service to use local drives rather than networked drives.
The Perforce server process does not require privileged access. For security reasons, do not run
p4d as
root or otherwise grant the owner of the
p4d process
root-level privileges.
Create a nonprivileged UNIX user (for example, perforce) to manage
p4d and (optionally) a UNIX group for it (for example,
p4admin). Use the
umask(1) command to ensure that the server root (
P4ROOT) and all files and directories created beneath it are writable only by the UNIX user
perforce, and (optionally) readable by members of the UNIX group
p4admin.
Under this configuration, the Perforce server (p4d), running as UNIX user
perforce, can write to files in the server root, but no users are able to read or overwrite its files. To grant access to the files created by
p4d (that is, the depot files, checkpoints, journals, and so on) to trusted users, you can add the trusted users to the UNIX group
p4admin.
|
|
On Windows, directory permissions are set securely by default; when Perforce runs as a server, the server root is accessible only to the user who invoked the server from the command prompt. When Perforce is installed as a service, the files are owned by the LocalSystem account, and are accessible only to those with Administrator access.
|
Use the -L flag to
p4d or the environment variable
P4LOG to specify the Perforce server's error output file. If no error output file is defined, errors are dumped to the
p4d process' standard error. 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 also logs these errors to its error output.
If your site requires that user access to files be tracked, use the -A flag to
p4d or the environment variable
P4AUDIT to activate auditing and specify the Perforce server's audit log file. When auditing is active, every time a user accesses a file, a record is stored in the audit log file. This option can consume considerable disk space on an active server.
Whether your Perforce Server is running on Windows or UNIX, if your site is involved in cross-platform development (that is, if you are using Perforce client programs on both Windows and UNIX workstations), your users must be aware of certain details regarding case sensitivity issues.
The Perforce Server tracks information about Perforce-related processes running on your Perforce server machine. Server process monitoring requires minimal system resources, but you must enable process monitoring for
p4 monitor to work. To enable process monitoring, set the
monitor counter as follows:
After you set or change the monitor counter, you must stop and restart the Perforce server for your change to take effect.
Perforce is an efficient consumer of network bandwidth and CPU power. The most important variables that determine server performance are the efficiency of your server's disk I/O subsystem and the number of files referenced in any given user-originated Perforce operation.
Copyright 1997-2009 Perforce Software.
