| Perforce 2002.2 System Administrator's Guide | ||
|
<< Previous Chapter About This Manual |
Table of Contents Index Perforce on the Web |
Next Chapter >> Supporting Perforce: Backup and Recovery |
|
Warning! |
If you're upgrading an existing installation to Release 2001.1 or later, see the notes in "Upgrading a Perforce Server" on page 16 before proceeding. |
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.
|
Windows |
Windows administrators will note that many of the examples in this book are based on the UNIX version of the Perforce server. In almost all cases, they are common to both Windows and UNIX installations; Perforce's behavior is generally the same regardless of whether executed in a UNIX shell or from the MS-DOS command line. Where the UNIX and Windows versions of Perforce differ, a note to that effect will be made. For Windows-specific information, see "Perforce and Windows" on page 103. |
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.
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:
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.
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.
|
If P4PORT is... |
Then... |
|---|---|
|
dogs:3435 |
The client program uses the p4d server on host dogs listening at port 3435. |
|
x.com:1818 |
The client program uses the p4d server on host x.com listening at port 1818. |
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.
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.
p4d &
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.
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:
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 119.
p4 admin stop
to shut down the Perforce server. Only a Perforce superuser may use this command.
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.
The Perforce installer (perforce.exe) allows you to:
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.
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
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.
|
Warning! |
If you are upgrading to 2001.1 or later, it is imperative that you read the notes pertaining to the 2001.1 upgrade. |
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.
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.
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.
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.
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.
See "Supporting Perforce: Backup and Recovery" on page 25 for a full discussion of backup and restoration procedures.
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.
p4 protect
to define a Perforce superuser as soon as possible after installing the Perforce server. For more information, see "Administering Perforce: Protections" on page 61
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.
For a more detailed example of a disk sizing estimate, see "Disk space allocation" on page 92.
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:
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 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 workspaces located in users' home directories.
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 107.
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.
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.
For more detailed performance tuning information, see "Tuning Perforce for Performance" on page 91.
| Perforce 2002.2 System Administrator's Guide | ||
|
<< Previous Chapter About This Manual |
Table of Contents Index Perforce on the Web |
Next Chapter >> Supporting Perforce: Backup and Recovery |