Previous Table of Contents Index Next
Perforce 2009.2: System Administrator's Guide



Chapter 3
Administering Perforce: Superuser Tasks
This chapter describes basic tasks associated with day-to-day Perforce administration and advanced Perforce configuration issues related to cross-platform development issues, migration of Perforce servers from one machine to another, and working with remote and local depots.
Most of the tasks described in this chapter requires that you have Perforce superuser (access level super) or administrator (access level admin) privileges as defined in the Perforce protections table. For more about controlling Perforce superuser access, and protections in general, see Administering Perforce: Protections.
Release 2004.2 of Perforce introduced a new authentication mechanism and a server-configurable security setting to govern password strength requirements and authentication method policy. For details, see Authentication methods: passwords and tickets and Server security levels.
Basic Perforce Administration
Tasks commonly performed by Perforce administrators and superusers include:
User maintenance tasks, including resetting passwords, creating users, disabling the automatic creation of users, and cleaning up files left open by former users
Administrative operations, including setting the server security level, obliterating files to reclaim disk space, editing submitted changelists, verifying server integrity, defining file types to control Perforce's file type detection mechanism, and the use of the -f flag to force operations
Authentication methods: passwords and tickets
Perforce supports two methods of authentication: password-based and ticket-based.
Although ticket-based authentication provides a more secure authentication mechanism than password-based authentication, it does not encrypt network traffic between client workstations and the Perforce server.
If you are accessing Perforce over an insecure network, use a third-party tunneling solution (for example, ssh or a VPN) regardless of the authentication method you choose.
How password-based authentication works
Password-based authentication is stateless; once a password is correctly set, access is granted for indefinite time periods. Prior to Release 2004.2, the password-based authentication mechanism did not enforce password strength or existence requirements.
The concept of the server security level, introduced in Release 2004.2, enables administrators to enforce password strength and existence requirements. See Server security levels for details.
Password based authentication is supported at security levels 0, 1, and 2.
How ticket-based authentication works
Ticket-based authentication is based on time-limited tickets that enable users to connect to Perforce servers. Tickets are stored in the file specified by the P4TICKETS environment variable. If this variable is not set, tickets are stored in %USERPROFILE%\p4tickets.txt on Windows, and in $HOME/.p4tickets on UNIX and other operating systems. Tickets are managed automatically by 2004.2 and later Perforce client programs.
Tickets have a finite lifespan, after which they cease to be valid. By default, tickets are valid for 12 hours (43200 seconds). To set different ticket lifespans for groups of users, edit the Timeout: field in the p4 group form for each group. The timeout value for a user in multiple groups is the largest timeout value (including unlimited, but ignoring unset) for all groups of which a user is a member. To create a ticket that does not expire, set the Timeout: field to unlimited.
Although tickets are not passwords, Perforce servers accept valid tickets wherever users can specify Perforce passwords. This behavior provides the security advantages of ticket-based authentication with the ease of scripting afforded by password authentication. Ticket-based authentication is supported at all server security levels, and is required at security level 3.
Logging in to Perforce
To use ticket-based authentication, get a ticket by logging in with the p4 login command:
p4 login
You are prompted for your password, and a ticket is created for you in your ticket file. You can extend your ticket's lifespan by calling p4 login while already logged in. If you run p4 login while logged in, your ticket's lifespan is extended by 1/3 of its initial timeout setting, subject to a maximum of your initial timeout setting.
By default, Perforce tickets are valid for your IP address only. If you have a shared home directory that is used on more than one machine, you can log in to Perforce from both machines by using the command:
p4 login -a
to create a ticket in your home directory that is valid from all IP addresses.
Logging out of Perforce
To log out of Perforce from one machine by removing your ticket, use the command:
p4 logout
The entry in your ticket file is removed. If you have valid tickets for the same Perforce server, but those tickets exist on other machines, those tickets remain present (and you remain logged in) on those other machines.
If you are logged in to Perforce from more than one machine, you can log out of Perforce from all machines from which you were logged in by using the command:
p4 logout -a
All of your Perforce tickets are invalidated and you are logged out.
Determining ticket status
To see if your current ticket (that is, for your IP address, user name, and P4PORT setting) is still valid, use the command:
p4 login -s
If your ticket is valid, the length of time for which it will remain valid is displayed.
To display all tickets you currently have, use the command:
p4 tickets
The contents of your ticket file are displayed.
Server security levels
Perforce superusers can configure server-wide password usage requirements, password strength enforcement, and supported methods of user/server authentication by setting the security counter. To change the security counter, issue the command:
p4 counter -f security seclevel
where seclevel is 0, 1, 2, or 3. After setting the counter, stop and restart the server.
Choosing a server security level
The default security level is 0: passwords are not required, and password strength is not enforced.
To ensure that all users have passwords, use security level 1. Users of old client programs can still enter weak passwords.
To ensure that all users have strong passwords, use security level 2. Old Perforce software continues to work, but users of old Perforce client software must change their password to a strong password by using a Perforce client program at Release 2003.2 or above.
To require that all users have strong passwords, and to require the use of session-based authentication, use security level 3 and current Perforce client software.
Level 0 corresponds to pre-2003.2 server operation. Levels 1 and 2 were designed for support of legacy client software. Level 3 affords the highest degree of security.
The Perforce server security levels and their effects on the behavior of Perforce client programs are defined below.
0
(or unset)
Users with passwords can use either their P4PASSWD setting or the p4 login command for ticket-based authentication.
Strong passwords are required for users of post-2003.2 Perforce client programs, but existing passwords are not reset.
Pre-2003.2 Perforce client programs can set passwords with p4 passwd or in the p4 user form, but password strength is not enforced.
Users with passwords can use either their P4PASSWD setting or the p4 login command for ticket-based authentication.
Users of client programs at release 2003.2 or higher must use p4 passwd and enter their passwords at the prompt. Setting passwords with the p4 user form or the p4 passwd -O oldpass -P newpass command is prohibited.
On Windows, passwords are no longer stored in (or read from) the registry. (Storing P4PASSWD as an environment variable is supported, but passwords set with p4 set P4PASSWD are ignored.)
Users who have set strong passwords with a 2003.2 or higher Perforce client program can use either their P4PASSWD setting for password-based authentication, or the p4 login command for ticket-based authentication.
If you have scripts that rely on passwords, use p4 login to create a ticket valid for the user running the script, or use p4 login -p to display the value of a ticket that can be passed to Perforce commands as though it were a password (that is, either from the command line, or by setting P4PASSWD to the value of the valid ticket).
Password strength
Certain combinations of server security level and Perforce client software releases require users to set "strong" passwords. A password is considered strong if it is at least eight characters long, and at least two of the following are true:
For example, the passwords a1b2c3d4, A1B2C3D4, aBcDeFgH are considered strong.
Resetting user passwords
If you are a Perforce superuser, you can reset a Perforce user's password with:
p4 passwd username
When prompted, enter a new password for user username.
p4 user -f username
Enter the password in the Password: field of the user specification form.
Creating users
By default, Perforce creates a new user record in its database whenever a command is issued by a user that does not exist. Perforce superusers can also use the -f (force) flag to create a new user as follows:
p4 user -f username
Fill in the form fields with the information for the user you want to create.
The p4 user command also has an option (-i) to take its input from the standard input instead of the forms editor. To quickly create a large number of users, write a script that reads user data, generates output in the format used by the p4 user form, and then pipes each generated form to p4 user -i -f.
Preventing automatic creation of users
By default, Perforce creates a new user record in its database whenever a user invokes any client command that can update the depot or its metadata.
To prevent Perforce from automatically creating users, all users must be defined in the protections table. The easiest way to do this is to include all users in a Perforce group, and to configure Perforce to grant access only to members of that group.
Example: Setting up users in a group
A Perforce superuser wants to prevent the server from creating new users. He starts by setting up a group called p4users for the three users currently at his site. He types:
p4 group p4users
and fills in the form as follows:
# A Perforce Group Specification.
# Group:      The name of the group.
# MaxResults: Limits the rows (unless 'unlimited' or 'unset') any
#             one operation can return to the client.
# MaxScanRows:Limits the rows (unless 'unlimited' or 'unset') any
#             one operation can scan from any one database table.
# MaxLockTime:Limits the time (in milliseconds, unless 'unlimited'
#             or 'unset') any one operation can lock any database
#             table when scanning data...
# Timeout:    Time (in seconds, unless 'unlimited' or 'unset') which
#             determines how long a 'p4 login' session ticket
#             remains valid (default is 12 hours).
# Subgroups:  Other groups automatically included in this group.
# Owners:     Users allowed to change this group without requiring
#             super access permission.
# Users:      The users in the group.  One per line.
Group:  p4users
MaxResults:     unset
MaxScanRows:    unset
MaxLockTime:    unset
Timeout:        43200
Subgroups:
Owners:
Users:
        edk
        lisag
He then uses p4 protect to edit the protections table. The relevant line of the default protections table looks like this:
This grants write permission to any user matching * (that is, to all users) from any host (the second *) in all areas of the depot (that is, to files in //...).
Finally, the superuser uses p4 protect to change this line in the protections table to read:
The replacement protection grants only write access to users whose group matches p4users. Members of p4users can use Perforce from any host (*) and have write access to all areas of the depot (//...).
As long as no other lines in the protections table grant (or deny!) permission to "all users", all users are now defined within p4 protect, and the server no longer automatically creates new user entries when new users attempt to access Perforce.
For a more in-depth description of Perforce protections, see Administering Perforce: Protections.
Deleting obsolete users
Each user on the system consumes one Perforce license. A Perforce administrator can free up licenses by deleting users with the following command:
p4 user -d -f username
Before you delete a user, you must first revert (or submit) any files a user has open in a changelist. If you attempt to delete a user with open files, Perforce displays an error message to that effect.
Deleting a user frees a Perforce license but does not automatically update the group and protections tables. Use p4 group and p4 protect to delete the user from these tables.
Adding new licensed users
Perforce licenses are controlled by a text file called license. This file resides in the server root directory.
To add or update a license file, stop the Perforce Server, copy the license file into the server root directory, and restart the Perforce Server.
As of Release 2006.2, you can update an existing license without shutting down the Perforce Server, use p4 license -i to read the new license file from the standard input.
Most new license files obtained from Perforce can be installed with p4 license, except for when the server IP address has changed. If the server IP address has changed, or if no license file currently exists, you must still stop the Perforce Server, manually copy the license file into place, and restart the Server.
Reverting files left open by obsolete users
If files have been left open by a nonexistent or obsolete user (for instance, a departing employee), a Perforce administrator can revert the files by deleting the client workspace specification in which the files were opened.
As an example, if the output of p4 opened includes:
//depot/main/code/file.c#8 - edit default change (txt) by jim@stlouis
you can delete the stlouis client workspace specification with:
p4 client -d -f stlouis
Deleting a client workspace specification automatically reverts all files opened in that workspace, deletes pending changelists associated with the workspace, and any pending fix records associated with the workspace. Deleting a client workspace specification does not affect any files in the workspace actually used by the workspace's owner; the files can still be accessed by other employees.
Reclaiming disk space by obliterating files
Use p4 obliterate with caution. This is the only command in Perforce that actually removes file data.
The depot is always growing, which is not always desirable: a user might have created hundreds of unneeded files by means of an inadvertent branch or submit, or perhaps there are directories of old files that are no longer in use. Because p4 delete merely marks files as deleted in their head revisions, it cannot be used to free up disk space on the server. This is where p4 obliterate can be useful.
Perforce administrators can use p4 obliterate filename to remove all traces of a file from a depot, making the file indistinguishable from one that never existed in the first place.
The purpose of a software configuration management system is to enable your site to maintain a history of what operations were performed on which files. The p4 obliterate command defeats this purpose; as such, it is intended only to be used to remove files that never belonged in the depot in the first place, and not as part of a normal software development process.
Note also that p4 obliterate is computationally expensive; obliterating files requires that the entire body of metadata be scanned per file argument. Avoid using p4 obliterate during peak usage periods.
Do not use operating system commands (erase, rm, and their equivalents) to remove files from the Perforce server root by hand.
By default, p4 obliterate filename does nothing; it merely reports on what it would do. To actually destroy the files, use p4 obliterate -y filename.
To destroy only one revision of a file, specify only the desired revision number on the command line. For instance, to destroy revision 5 of a file, use:
p4 obliterate -y file#5
Revision ranges are also acceptable. To destroy revisions 5 through 7 of a file, use:
p4 obliterate -y file#5,7
If you intend to obliterate a revision range, be certain you've specified it properly. If you fail to specify a revision range, all revisions of the file are obliterated.
The safest way to use p4 obliterate is to use it without the -y flag until you are certain the files and revisions are correctly specified.
Deleting changelists and editing changelist descriptions
Perforce administrators can use the -f (force) flag with p4 change to change the description, date, or user name of a submitted changelist. The syntax is p4 change -f changenumber. This command presents the standard changelist form, but also enables superusers to edit the changelist's time, description, date, and associated user name.
You can also use the -f flag to delete any submitted changelists that have been emptied of files with p4 obliterate. The full syntax is p4 change -d -f changenumber.
Example: Updating changelist 123 and deleting changelist 124
Use p4 change with the -f (force) flag:
p4 change -f 123
p4 change -d -f 124
The User: and Description: fields for change 123 are edited, and change 124 is deleted.
Verifying files by signature
Perforce administrators can use the p4 verify filenames command to validate stored MD5 digests of each revision of the named files. The signatures created when users store files in the depot can later be used to confirm proper recovery in case of a crash: if the signatures of the recovered files match the previously saved signatures, the files were recovered accurately. If a new signature does not match the signature in the Perforce database for that file revision, Perforce displays the characters BAD! after the signature.
It is good practice to run p4 verify before performing your nightly system backups, and to proceed with the backup only if p4 verify reports no corruption.
For large installations, p4 verify can take some time to run. Furthermore, the database is locked when p4 verify is running, which prevents most other Perforce commands from being used. Administrators of large sites might want to perform p4 verify on a weekly basis, rather than a nightly basis.
If you ever see a BAD! signature during a p4 verify command, your database or versioned files might be corrupt, and you should contact Perforce Technical Support.
Verifying files during server upgrades
It is good practice to use p4 verify as follows before and after server upgrades:
1.
p4 verify -q //...
to verify the integrity of your server before the upgrade.
2.
3.
4.
p4 verify -q //...
to verify the integrity of your new system.
Defining filetypes with p4 typemap
By default, Perforce automatically determines if a file is of type text or binary based on an analysis of the first 8192 bytes of a file. If the high bit is clear in each of the first 8192 bytes, Perforce assumes it to be text; otherwise, it is assumed to be binary.
Although this default behavior can be overridden by the use of the -t filetype flag, it's easy for users to overlook this consideration, particularly in cases where files' types are usually (but not always) detected correctly. Certain file formats, such as RTF (Rich Text Format) and Adobe PDF (Portable Document Format), can start with a series of comment fields or other textual data. If these comments are sufficiently long, such files can be erroneously detected by Perforce as being of type text.
The p4 typemap command solves this problem by enabling system administrators to set up a table that links Perforce file types with filename specifications. If an entry in the typemap table matches a file being added, it overrides the file type that would otherwise be assigned by the Perforce client program. For example, to treat all PDF and RTF files as binary, use p4 typemap to modify the typemap table as follows:
Typemap:
        binary //....pdf
        binary //....rtf
The first three periods ("...") in the specification are a Perforce wildcard specifying that all files beneath the root directory are to be included in the mapping. The fourth period and the file extension specify that the specification applies to files ending in .pdf (or .rtf).
The following table lists recommended Perforce file types and modifiers for common file extensions.
GIF graphic file
HTML file
HTML file
JPEG graphic file
MPEG video file
Adobe PDF file
ZIP archive file
Use the following p4 typemap table to map all of the file extensions to the Perforce file types recommended in the preceding table.
# Perforce File Type Mapping Specifications.
#
#  TypeMap:     a list of filetype mappings; one per line.
#               Each line has two elements:
#               Filetype: The filetype to use on 'p4 add'.
#               Path:     File pattern which will use this filetype.
# See 'p4 help typemap' for more information.

TypeMap:

        text //....asp
        binary+F //....avi
        binary //....bmp
        binary //....btr
        text //....cnf
        text //....css
        binary //....doc
        binary //....dot
        binary+w //....exp
        binary+F //....gif
        text //....htm
        text //....html
        binary //....ico
        text //....inc
        text+w //....ini
        binary //....jpg
        text //....js
        binary+w //....lib
        text+w //....log
        binary+F //....mpg
        binary //....pdf
        text+w //....pdm
        binary //....ppt
        binary //....xls
        binary+F //....zip
If a file type requires the use of more than one file type modifier, specify the modifiers consecutively. For example, binary+lFS10 refers to a binary file with exclusive-open (l), stored in full (F) rather than compressed, and for which only the most recent ten revisions are stored (S10).
For more information, see the p4 typemap page in the Perforce Command Reference.
Implementing sitewide pessimistic locking with p4 typemap
By default, Perforce supports concurrent development, but environments in which only one person is expected to have a file open for edit at a time can implement pessimistic locking by using the +l (exclusive open) modifier as a partial filetype. If you use the following typemap, the +l modifier is automatically applied to all newly added files in the depot:
Typemap:
        +l //depot/...
If you use this typemap, any files your users add to the depot after you update your typemap automatically have the +l modifier applied, and may only be opened for edit by one user at a time. The typemap table applies only to new additions to the depot; after you update the typemap table for sitewide exclusive open, files previously submitted without +l must be opened for edit with p4 edit -t+l filename and resubmitted. Similarly, users with files already open for edit must update their filetypes with p4 reopen -t+l filename.
Forcing operations with the -f flag
Certain commands support the -f flag, which enables Perforce administrators and superusers to force certain operations unavailable to ordinary users. Perforce administrators can use this flag with p4 branch, p4 change, p4 client, p4 job, p4 label, and p4 unlock. Perforce superusers can also use it to override the p4 user command. The usages and meanings of this flag are as follows.
p4 branch -f branchname
Allows the modification date to be changed while editing the branch mapping
p4 change -f [changelist#]
Allows the modification date to be changed while editing the changelist specification
p4 change -f changelist#
Allows the description field and username in a committed changelist to be edited
p4 change -f -d changelist#
p4 client -f clientname
Allows the modification date to be changed while editing the client specification
Deletes the client, ignoring ownership, even if the client has opened files
p4 job -f [jobname]
Allows the manual update of read-only fields
p4 label -f labelname
Allows the modification date to be changed while editing the label specification
Releases a lock (set with p4 lock) on an open file in a pending numbered changelist, ignoring ownership
p4 user -f username
Allows the update of all fields, ignoring ownership
Advanced Perforce administration
Running Perforce through a firewall
Perforce clients communicate with a Perforce server using TCP/IP. The server listens for connections at a specified port on the machine on which it's running, and clients make connections to that port.
The port on which the server listens is specified when the server is started. The number is arbitrary, so long as it does not conflict with any other networking services and is greater than 1024. The port number on the client machine is dynamically allocated.
A firewall is a network element that prevents any packets from outside a local (trusted) network from reaching that local network. This is done at a low level in the network protocol; any packets not coming from a trusted IP address are simply ignored.
In the following diagram, the Perforce client is on an untrusted part of the network. None of its connection requests reach the machine with the Perforce server. Consequently, the user running the client through the firewall is unable to use Perforce.
Secure shell
To solve this problem, you have to make the connection to the Perforce server from within the trusted network. This can be done securely using a package called secure shell (ssh).
Secure shell (ssh) is meant to be a replacement for the UNIX rsh (remote shell) command, which allows you to log into a remote system and execute commands on it. The "secure" part of "secure shell" comes from the fact that the connection is encrypted, so none of the data is visible while it passes through the untrusted network. With simple utilities like rsh, all traffic, even passwords, is unencrypted and visible to all intermediate hosts, creating an unacceptable security hazard.
Secure shell is available for free in source form for a multitude of UNIX platforms from http://www.openssh.com. This page also links to ports of ssh for OS/2 and Amiga, as well as commercial implementations for Windows and Macintosh from Data Fellows (http://www.datafellows.com) and SSH (http://www.ssh.com).
The OpenSSH FAQ can also be found online at the main site (http://www.openssh.com/faq.html).
Solving the problem
Once you have ssh up and running, the simplest thing to do is to use it to log into the firewall machine and run the Perforce client from the firewall. While it has the advantage of simplicity, it's a poor solution: you typically want your client files accessible on your local machine, and of course, there's no guarantee that your firewall machine will match your development platform.
A good solution takes advantage of ssh's ability to forward arbitrary TCP/IP connections. By using ssh, you can make your Perforce client appear as though it's connecting from the firewall machine over the local (trusted) network. In reality, your client remains on your local machine, but all packets from your local machine are first sent to the firewall through the secure channel set up by ssh.
Suppose the Perforce server is on p4dbox.bigcorp.com, and the firewall machine is called firewall.bigcorp.com. In our example, we'll arbitrarily choose local port 4242, and assume that the Perforce server is listening on port 3710.
Packets ultimately destined for your client's port 4242 are first sent to the firewall, and ssh forwards them securely to your client. Likewise, connections made to port 4242 of the firewall machine will end up being routed to port 3710 of the Perforce server.
On UNIX, the ssh command on your own machine to set up and forward the TCP/IP connection would be:
ssh -L 4242:p4dbox.bigcorp.com:3710 firewall.bigcorp.com
At this point, it might be necessary to provide a password to log into firewall.bigcorp.com. Once the connection is established, ssh listens at port 4242 on the local machine, and forwards packets over its encrypted connection to firewall.bigcorp.com; the firewall then forwards them by normal channels to port 3710 on p4dbox.bigcorp.com.
All that remains is to tell the Perforce client to use port 4242 by setting the environment variable P4PORT to 4242.
Normally, setting P4PORT=4242 would normally indicate that we are trying to connect to a Perforce server on the local machine listening at port 4242. In this case, ssh takes the role of the Perforce server. Anything a client sends to port 4242 of the local machine is forwarded by ssh to the firewall, which passes it to the real Perforce server at p4dbox.bigcorp.com. Since all of this is transparent to the Perforce client, it doesn't matter whether the client is talking to an instance of ssh that's forwarding traffic from port 4242 of the local machine, or if it's talking to a real Perforce server residing on the local machine.
The only glitch is that there's a login session you don't normally want on the firewall machine.
This can be solved by running the following command:
ssh -L 4242:p4dbox.bigcorp.com:3710 firewall.bigcorp.com -f sleep 9999999 -f
on the remote system.
This tells ssh on firewall.bigcorp.com to fork a long-running sleep command in the background after the password prompt. Effectively, this sets up the ssh link and keeps it up; there is no login session to terminate.
Finally, ssh can be configured to "do the right thing" so that it is unnecessary to type such a long command with each session. The Windows version of ssh, for instance, has a GUI to configure this.
One final concern: with port 4242 on the local machine now forwarded to a supposedly secure server, your local machine is part of the trusted network; it is prudent to make sure the local machine really is secure. The Windows version of ssh has an option to only permit local connections to the forwarded port, which is a wise precaution; your machine will be able to use port 4242, but a third party's machine will be ignored.
Specifying IP addresses in P4PORT
Under most circumstances, your Perforce server's P4PORT setting consists solely of a port number. If you specify both an IP address and a port number in P4PORT when starting p4d, the Perforce server ignores requests from any IP addresses other than the one specified in P4PORT.
Although this isn't the default behavior, it can be useful. For instance, if you want to configure p4d to listen only to a specific network interface or IP address, you can force your Perforce server to ignore all nonlocal connection requests by setting P4PORT=localhost:port.
Running from inetd on UNIX
Under a normal installation, the Perforce server is run on UNIX as a background process that waits for connections from clients. To have p4d start up only when connections are made to it, using inetd and p4d -i, add the following line to /etc/inetd.conf:
p4dservice stream tcp nowait username /usr/local/bin/p4d p4d -i -rp4droot
and then add the following line to /etc/services:
p4dservice nnnn/tcp
where:
p4dservice is the service name you choose for this Perforce server
/usr/local/bin is the directory holding your p4d binary
p4droot is the root directory (P4DROOT) to use for this Perforce server (for example, /usr/local/p4d)
username is the UNIX user name to use for running this Perforce server
nnnn is the port number for this Perforce server to use
The "extra" p4d on the /etc/inetd.conf line must be present; inetd passes this to the OS as argv[0]. The first argument, then, is the -i flag, which causes p4d not to run in the background as a daemon, but rather to serve the single client connected to it on stdin/stdout. (This is the convention used for services started by inetd.)
This method is an alternative to running p4d from a startup script. It can also be useful for providing special services; for example, at Perforce, we have a number of test servers running on UNIX, each defined as an inetd service with its own port number.
There are caveats with this method:
inetd may disallow excessive connections, so a script that invokes several thousand p4 commands, each of which spawns an instance of p4d via inetd can cause inetd to temporarily disable the service. Depending on your system, you might need to configure inetd to ignore or raise this limit.
There is no easy way to disable the server, since the p4d executable is run each time; disabling the server requires modifying /etc/inetd.conf and restarting inetd.
Case sensitivity and multiplatform development
Early (pre-97.2) releases of the Perforce server treated all filenames, pathnames, and database entity names with case significance, whether the server was running on UNIX or Windows.
For example, //depot/main/file.c and //depot/MAIN/FILE.C were treated as two completely different files. This caused problems where users on UNIX were connecting to a Perforce server running on Windows because the filesystem underlying the server could not store files with the case-variant names submitted by UNIX users.
In release 97.3, the behavior was changed, and only the UNIX server supports case-sensitive names. However, there are still some case-sensitivity problems that users can encounter when sharing development projects across UNIX and Windows.
If you are running a pre-97.2 server on Windows, please contact [email protected] to discuss upgrading your server and database.
For current releases of the server:
The Perforce server on UNIX supports case-sensitive names.
The following table summarizes these rules.
To find out what platform your Perforce server runs on, use p4 info.
Perforce server on UNIX
If your Perforce server is on UNIX, and you have users on both UNIX and Windows, your UNIX users must be very careful not to submit files whose names differ only by case. Although the UNIX server can support these files, when Windows users sync their workspaces, they'll find files overwriting each other.
Conversely, Windows users will have to be careful to use case consistently in filenames and pathnames when adding new files. They might not realize that files added as //depot/main/one.c and //depot/MAIN/two.c will appear in two different directories when synced to a UNIX user's workspace.
The UNIX Perforce server always respects case in client names, label names, branch view names, and so on. Windows users connecting to a UNIX server should be aware that the lowercased workstation names are used as the default names for new client workspaces. For example, if a new user creates a client spec on a Windows machine named ROCKET, his client workspace is named rocket by default. If he later sets P4CLIENT to ROCKET (or Rocket), Perforce will tell him his client is undefined. He must set P4CLIENT to rocket (or unset it) to use the client workspace he defined.
Perforce server on Windows
If your Perforce server is running on Windows, your UNIX users must be aware that their Perforce server will store case-variant files in the same namespace.
For example, users who try something like this:
p4 add dir/file1
p4 add dir/file2
p4 add DIR/file3
should be aware that all three files will be stored in the same depot directory. The depot pathnames and filenames assigned to the Windows server will be those first referenced. (In this case, the depot pathname would be dir, and not DIR.)
Monitoring server activity
Use the p4 monitor command to obtain information about Perforce-related processes running on your Perforce server machine.
Enabling process monitoring
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:
p4 counter -f monitor 1
After you set or change the monitor counter, you must stop and restart the Perforce server for your change to take effect.
Enabling idle processes monitoring
By default, IDLE processes (often associated with custom applications based on the Perforce API) are not included in the output of p4 monitor. To include idle processes in the output of p4 monitor, use monitoring level 2.
p4 counter -f monitor 2
You must stop and restart the Perforce server for your change to take effect.
Listing running processes
To list the processes running on the Perforce server, use the command:
p4 monitor show
By default, each line of p4 monitor output looks like this:
pid status owner hh:mm:ss command [args]
where pid is the UNIX process ID (or Windows thread ID), status is R or T depending on whether the process is running or marked for termination, owner is the Perforce user name of the user who invoked the command, hh:mm:ss is the time elapsed since the command was called, and command and args are the command and arguments as received by the Perforce server. For example:
$ p4 monitor show
74612 R qatool     00:00:47 job
78143 R edk        00:00:01 filelog
78207 R p4admin    00:00:00 monitor
To show the arguments with which the command was called, use the -a (arguments) flag:
$ p4 monitor show -a
74612 R qatool     00:00:48 job job004836
78143 R edk        00:00:02 filelog //depot/main/src/proj/file1.c //dep
78208 R p4admin    00:00:00 monitor show -a
To obtain more information about user environment, use the -e flag. The -e flag produces output of the form:
pid client IP-address status owner workspace hh:mm:ss command [args]
where client is the Perforce client program (and version string or API protocol level), IP-address is the IP address of the user's Perforce client program, and workspace is the name of the calling user's current client workspace setting. For example:
$ p4 monitor show -e
74612 p4/2005.2 192.168.10.2   R qatool    buildenvir 00:00:47 job
78143           192.168.10.4   R edk       eds_elm    00:00:01 filelog
78207 p4/2005.2 192.168.10.10  R p4admin   p4server   00:00:00 monitor
By default, all user names and (if applicable) client workspace names are truncated at 10 characters, and lines are truncated at 80 characters. To disable truncation, use the -l (long-form) option:
$ p4 monitor show -a -l
74612 R qatool     00:00:50 job job004836
78143 R edk        00:00:04 filelog //depot/main/src/proj/file1.c //dep
ot/main/src/proj/file1.mpg
78209 R p4admin    00:00:00 monitor show -a -l
Only Perforce administrators and superusers can use the -a, -l, and -e options.
Marking processes for termination
If a process on a Perforce Server is consuming excessive resources, administrators and superusers can mark it for termination with p4 monitor terminate.
Once marked for termination, the process is terminated by the Perforce server within 50000 scan rows or lines of output. Only processes that have been running for at least ten seconds can be marked for termination.
Users of terminated processes are notified with the following message:
Command has been canceled, terminating request
Processes that involve the use of interactive forms (such as p4 job or p4 user) can also be marked for termination, but data entered by the user into the form is preserved. Some commands, such as p4 obliterate, cannot be terminated.
Clearing entries in the process table
Under some circumstances (for example, a Windows machine is rebooted while certain Perforce commands are running), entries may remain in the process table even after the process has terminated.
Perforce administrators and superusers can remove these erroneous entries from the process table altogether with p4 monitor clear pid, where pid is the erroneous process ID. To clear all processes from the table (running or not), use p4 monitor clear all.
Running processes removed from the process table with p4 monitor clear continue to run to completion.
Perforce server trace and tracking flags
To turn on command tracing or performance tracking, specify the appropriate -v subsystem=value flag to the p4d startup command. Use P4LOG or the -L logfile flag to specify the log file. For instance:
p4d -r /usr/perforce -v server=1 -p 1666 -L /usr/perforce/logfile
Before you activate logging, make sure that you have adequate disk space.
When running Perforce as a Windows service, use the p4 set command to set P4DEBUG as a registry variable. You can also set these trace flags when running p4d.exe as a server process from the command line.
Setting server debug levels on a Perforce server (p4d) has no effect on the debug level of a Perforce Proxy (p4p) process, and vice versa.
In most cases, the Perforce server command tracing and tracking flags are useful only to system administrators working with Perforce Technical Support to diagnose or investigate a problem.
Command tracing
The server command trace flags and their meanings are as follows.
In addition to data logged at level 1, logs server command completion and basic information on CPU time used. Time elapsed is reported in seconds. On UNIX, CPU usage (system and user time) is reported in milliseconds, as per getrusage().
In addition to data logged at level 2, adds usage information for compute phases of p4 sync and p4 flush (p4 sync -k) commands.
For command tracing, output appears in the specified log file, showing the date, time, username, IP address, and command for each request processed by the server.
Performance tracking
The Perforce Server produces diagnostic output in the server log whenever user commands exceed certain predetermined thresholds of resource usage. Performance tracking is enabled by default, and if P4DEBUG is unset (or the tracking flag is not specified on the command line), the tracking level is computed based on the number of users in the license file.
The precise format of the tracking output is undocumented and subject to change.
Auditing user file access
As of Release 2006.1, the Perforce Server can log individual file accesses to an audit logfile.
Auditing is disabled by default, and is only enabled if P4AUDIT is set to point to the location of the audit log file, or if the server is started with the -A auditlog flag.
When auditing is enabled, the server adds a line to the audit log file every time file content is transferred from the server to the client. On an active server, the audit log file will grow very quickly.
Lines in the audit log appear in the form:
date time user@client clientIP command file#rev
For example:
2006/05/09 09:52:45 karl@nail 192.168.0.12 diff //depot/src/x.c#1
2006/05/09 09:54:13 jim@stone 127.0.0.1 sync //depot/inc/file.h#1
If a command is run on the machine that runs the Perforce Server, the clientIP is shown as 127.0.0.1.
Moving a Perforce server to a new machine
The procedure for moving an existing Perforce server from one machine to another depends on whether or not you're moving between machines
of different architecture and different text file format.
Additional considerations apply if the new machine has a different IP address/hostname.
The Perforce server stores two types of data under the Perforce root directory: versioned files and a database containing metadata describing those files. Your versioned files are the ones created and maintained by your users, and your database is a set of Perforce-maintained binary files holding the history and present state of the versioned files. In order to move a Perforce server to a new machine, both the versioned files and the database must be successfully migrated from the old machine to the new machine.
For more about the distinction between versioned files and database, as well as for an overview of backup and restore procedures in general, see Backup and recovery concepts.
For more about moving a Perforce server from one machine to another, see also the Perforce Tech Note at:
http://www.perforce.com/perforce/technotes/note010.html
Moving between machines of the same architecture
If the architecture of the two machines is the same (for example, SPARC/SPARC, or x86/x86), the versioned files and database can be copied directly between the machines, and you only need to move the server root directory tree to the new machine. You can use tar, cp, xcopy.exe, or any other method. Copy everything in and under the P4ROOT directory - the db.* files (your database) as well as the depot subdirectories (your versioned files).
1.
Back up your server (including a p4 verify before the backup) and take a checkpoint.
2.
3.
Copy the contents of your old server root (P4ROOT) and all its subdirectories on the old machine into the new server root directory on the new machine.
4.
Start p4d on the new machine with the desired flags.
5.
Run p4 verify on the new machine to ensure that the database and your versioned files were transferred correctly to the new machine.
(Although the backup, checkpoint, and subsequent p4 verify are not strictly necessary, it's always good practice to verify, checkpoint, and back up your system before any migration and to perform a subsequent verification after the migration.)
Moving between different architectures that use the same text format
If the internal data representation (big-endian vs. little-endian) convention differs between the two machines (for example, Linux-on-x86/SPARC, NT-on-Alpha/NT-on-x86), but their operating systems use the same CR/LF text file conventions, you can still simply move the server root directory tree to the new machine.
Although the versioned files are portable across architectures, the database, as stored in the db.* files, is not. To transfer the database, you will need to create a checkpoint of your Perforce server on the old machine and use that checkpoint to re-create the database on the new machine. The checkpoint is a text file that can be read by a Perforce server on any architecture. For more details, see Creating a checkpoint.
After you create the checkpoint, you can use tar, cp, xcopy.exe, or any other method to copy the checkpoint file and the depot directories to the new machine. (You don't need to copy the db.* files, because they will be re-created from the checkpoint you took.)
1.
On the old machine, use p4 verify to ensure that the database is in a consistent state.
2.
3.
p4d -jc checkpointfile
4.
Copy the contents of your old server root (P4ROOT) and all its subdirectories on the old machine into the new server root directory on the new machine.
(To be precise, you don't need to copy the db.* files, just the checkpoint and the depot subdirectories. The db.* files will be re-created from the checkpoint. If it's more convenient to copy everything, then copy everything.)
5.
On the new machine, if you copied the db.* files, be sure to remove them from the new P4ROOT before continuing.
6.
Re-create a new set of db.* files suitable for your new machine's architecture from the checkpoint you created:
p4d -jr checkpointfile
7.
Start p4d on the new machine with the desired flags.
8.
Run p4 verify on the new machine to ensure that the database and your versioned files were transferred correctly to the new machine.
Moving between Windows and UNIX
In this case, both the architecture of the system and the CR/LF text file convention are different. You still have to create a checkpoint, copy it, and re-create the database on the new platform, but when you move the depot subdirectories containing your versioned files, you also have to address the issue of the differing linefeed convention between the two platforms.
Depot subdirectories can contain both text and binary files. The text files (in RCS format, ending with ",v") and binary files (directories of individual binary files, each directory ending with ",d") need to be transferred in different ways in order to translate the line endings on the text files while leaving the binary files unchanged.
As with all other migrations, be sure to run p4 verify after your migration.
Windows is a case-insensitive operating system. Files that differ by case only on a UNIX server will occupy the same namespace when transferred to a Windows machine. For instance, files Makefile and file makefile on a UNIX server will appear to be the same file on a Windows machine.
Contact Perforce Technical Support for assistance when migrating a Perforce server from Windows to UNIX.
Changing the IP address of your server
If the IP address of the new machine is not the same as that of the old machine, you will need to update any IP-address-based protections in your protections table. See Administering Perforce: Protections for information on setting protections for your Perforce server.
If you are a licensed Perforce customer, you will also need a new license file to reflect the server's new IP address. Contact Perforce Technical Support to obtain an updated license.
Changing the hostname of your server
If the hostname of the new machine serving Perforce is different from that of its predecessor, your users must change their P4PORT settings. If the old machine is being retired or renamed, consider setting an alias for the new machine to match that of the old machine, so that your users won't have to change their P4PORT settings.
Using multiple depots
New depots are defined with the command p4 depot depotname. Depots can be defined as local, remote, or spec depots.
Just as Perforce servers can host multiple depots, Perforce client programs can access files from multiple depots. These other depots can exist on the Perforce server normally accessed by the Perforce client, or they can reside within other, remote, Perforce servers.
Local depots reside on the Perforce server normally accessed by the user's Perforce client program. When using local depots, a Perforce client program communicates with the Perforce server specified by the user's P4PORT environment variable or equivalent setting.
When using remote depots, the user's Perforce client program uses the Perforce server specified by the user's P4PORT environment variable or equivalent setting as a means to access a second, remote, Perforce server. The local Perforce server communicates with the remote Perforce server in order to access a subset of its files. Remote depots are primarily used to facilitate the sharing of code (that is, "code drops") between separate organizations, and are discussed in Remote depots and distributed development.
Remote depots are not a generalized solution for load-balancing or network access problems. To support shared development or to deal with load-balancing or network access problems, see Perforce Proxy.
The spec depot is a special case. If present, the spec depot tracks changes to user-edited forms such as client workspace specifications, jobs, branch mappings, and so on. There can be only one spec depot per server.
Naming depots
Depot names share the same namespace as branches, client workspaces, and labels. For example, //rel2 refers uniquely to one of the depot rel2, the workspace rel2, the branch rel2, or the label rel2; you can't simultaneously have both a depot and a label named rel2.
Defining new local depots
To define a new local depot (that is, to create a new depot in the current Perforce server namespace), call p4 depot with the new depot name, and edit only the Map: field in the resulting form.
For example, to create a new depot called book with the files stored in the local Perforce server namespace in a root subdirectory called book (that is, $P4ROOT/book), enter the command p4 depot book, and fill in the resulting form as follows:
Depot:       book
Type:        local
Address:     local
Suffix:      .p4s
Map:         book/...
The Address: and Suffix: fields do not apply to local depots and are ignored.
By default, the Map: field on a local depot points to a depot directory matching the depot name, relative to the server root (P4ROOT) setting for your server. To store a depot's versioned files on another volume or drive, specify an absolute path in the Map: field. This path need not be under P4ROOT. Absolute paths in the Map: field on Windows must be specified with forward slashes (for instance, d:/newdepot/) in the p4 depot form.
Enabling versioned specifications with the spec depot
In order for your users to retrieve change histories of user-edited forms, you must enable versioned specifications. The spec depot can have any name, but it must be of type spec, and there can only be one spec depot per server. (If you already have a spec depot, attempting to create another one results in an error message.)
After you have enabled versioned specs by creating the spec depot, all user-generated forms (such as client workspace specifications, jobs, branch mappings, and so on) are automatically archived as text files in the spec depot. Filenames within the spec depot are automatically generated by the server, and are represented in Perforce syntax as follows:
//specdepotname/formtype/objectname[suffix]
Creating the spec depot
To create a spec depot named //spec, enter p4 depot spec, and fill in the resulting form as follows:
Depot:       spec
Type:        spec
Address:     local
Map:         spec/...
Suffix:      .p4s
The Address: field does not apply to spec depots and is ignored.
Using a Suffix: is optional, but specifying a file extension for objects in the spec depot simplifies usability for users of graphical client programs such as P4V, because users can associate the suffix used for Perforce specifications with their preferred text editor. The default suffix for these files is .p4s.
For example, if you create a spec depot named spec, and use the default suffix of .p4s, your users can see the history of changes to job000123 by using the command
p4 filelog //spec/job/job000123.p4s
or by using P4V to review changes to job000123.p4s in whatever editor is associated with the .p4s file extension on their workstation.
Populating the spec depot with current forms
After you create a spec depot, you can populate it with the p4 admin updatespecdepot command. This command causes the Perforce Server to archive stored forms (specifically, client, depot, branch, label, typemap, group, user, and job forms) into the spec depot.
To archive all current forms, use the -a flag:
p4 admin updatespecdepot -a
To populate the spec depot with only one type of form (for instance, extremely large sites might elect to update only one table at a time), use the -s flag and specify the form type on the command line. For example:
p4 admin updatespecdepot -s job
In either case, only those forms that have not yet been archived are added to the spec depot; after the spec depot is created, you only need to use p4 admin updatespecdepot once.
Listing depots
To list all depots known to the current Perforce server, use the p4 depots command.
Deleting depots
To delete a depot, use p4 depot -d depotname.
To delete a depot, it must be empty; you must first obliterate all files in the depot with p4 obliterate.
For local and spec depots, p4 obliterate deletes the versioned files as well as all their associated metadata. For remote depots, p4 obliterate erases only the locally held client and label records; the files and metadata still residing on the remote server remain intact.
Before you use p4 obliterate, and especially if you're about to use it to obliterate all files in a depot, read and understand the warnings in Reclaiming disk space by obliterating files.
Remote depots and distributed development
Remote depots are designed to support shared code, not shared development. They enable independent organizations with separate Perforce installations to integrate changes between Perforce installations. Briefly:
A "remote depot" is a depot on your Perforce server of type remote. It acts as a pointer to a depot of type "local" that resides on a second Perforce server.
A user of a remote depot is typically a build engineer or handoff administrator responsible for integrating software between separate organizations.
Control over what files are available to a user of a remote depot resides with the administrator of the remote server, not the users of the local server.
See Restricting access to remote depots for security requirements.
When to use remote depots
Perforce is designed to cope with the latencies of large networks and inherently supports users with client workspaces at remote sites. A single Perforce installation is ready, out of the box, to support a shared development project, regardless of the geographic distribution of its contributors.
Partitioning joint development projects into separate Perforce installations does not improve throughput, and usually only complicates administration. If your site is engaged in distributed development (that is, developers in multiple sites working on the same body of code), it is usually preferable to set up a Perforce installation with all code in depots resident on one Perforce server, and to cache frequently accessed files at each development site with Perforce Proxy.
If, however, your organization regularly imports or exports material from other organizations, you might want to consider using Perforce's remote depot functionality to streamline your code drop procedures.
How remote depots work
The following diagram illustrates how Perforce client programs use a user's default Perforce server to access files in a depot hosted on another Perforce server.
In this example, an administrator of a Perforce server at oak:1234 is retrieving a file from a remote server at pine:1818.
Although it is possible to permit individual developers to sync files from remote depots into their client workspaces, this is generally an inefficient use of resources.
The preferred technique for using remote depots is for your organization's build or handoff administrator to integrate files from a remote depot into an area of your local depot. After the integration, your developers can access copies of the files from the local depot into which the files were integrated.
To accept a code drop from a remote depot, create a branch in a local depot from files in a remote depot, and then integrate changes from the remote depot into the local branch. This integration is a one-way operation; you cannot make changes in the local branch and integrate them back into the remote depot. The copies of the files integrated into your Perforce installation become the responsibility of your site's development team; the files on the depot remain under the control of the development team at the other Perforce installation.
Restrictions on remote depots
Prior to Release 99.2, remote depots were accessible only by Perforce servers running at the same release levels. At Release 99.2 and higher, remote depots are interoperable between release levels.
Remote depots facilitate the sharing of code between organizations (as opposed to the sharing of development within a single organization). Consequently, access to remote depots is restricted to read-only operations, and server metadata (information about client workspaces, changelists, labels, and so on) cannot be accessed using remote depots.
Using remote depots for code drops
Performing a code drop requires coordination between two organizations, namely the site receiving the code drop and the site providing the code drop. In most cases, the following three things must be configured:
The Perforce administrator at the site receiving the code drop must create a remote depot on his or her Perforce server that points to the site providing the code drop.
This is described in Defining remote depots.
The Perforce administrator at the site providing the code drop should configure his or her Perforce server to allow the recipient site's remote depot to access the providing site's Perforce server.
This is described in Restricting access to remote depots.
The configuration manager or integration manager at the receiving site must integrate the desired files from the remote depot into a local depot under his or her control.
This is described in Receiving a code drop.
Defining remote depots
To define a new remote depot:
1.
Create the depot with p4 depot depotname.
2.
Set the Type: to remote.
3.
Direct your Perforce server to contact the remote Perforce server by providing the remote server's name and listening port in the Address: field.
A remote server's host and port are specified in the Address: field just as though it were a P4PORT setting.
4.
Set the Map: field to map into the desired portion of the remote server's namespace.
For remote depots, the mapping contains a subdirectory relative to the remote depot namespace. For example, //depot/outbound/... maps to the outbound subdirectory of the depot named depot hosted on the remote server.
The Map: field must contain a single line pointing to this subdirectory, specified in depot syntax, and containing the "..." wildcard on its right side.
If you are unfamiliar with client views and mappings, see the P4 User's Guide for general information about how Perforce mappings work.
5.
The Suffix: field does not apply to remote depots; ignore this field.
In order for anyone on your site to access files in the remote depot, the administrator of the remote server must grant read access to user remote to the depots and subdirectories within the depots specified in the Map: field.
Example: Defining a remote depot
Lisa is coordinating a project and wants to provide a set of libraries to her developers from a third-party development shop. The third-party development shop uses a Perforce server on host pine that listens on port 1818. Their policy is to place releases of their libraries on their server's single depot depot under the subdirectory outbound.
Lisa creates a new depot from which she can access the code drop; she'll call this depot from-pine; she'd type p4 depot from-pine and fill in the form as follows:
Depot:       from-pine
Type:        remote
Address:     pine:1818
Map:         //depot/outbound/...
This creates a remote depot called from-pine on Lisa's Perforce server; this depot (//from-pine) maps to the third party's depot's namespace under its outbound subdirectory.
Restricting access to remote depots
Remote depots are always accessed by a virtual user named remote. This virtual user does not consume a Perforce license.
By default, all the files on any Perforce server can be accessed remotely. To limit or eliminate remote access to a particular server, use p4 protect to set permissions for user remote on that server. Perforce recommends that administrators deny access to user remote across all files and all depots by adding the following permission line in the p4 protect table:
list user remote *  -//...
Since remote depots can only be used for read access, it is not necessary to remove write or super access to user remote.
Example security configuration
Using the two organizations described in Receiving a code drop, a basic set of security considerations for each site would include:
On the local (oak) site:
Deny access to //from-pine to all users. Developers at the oak site have no need to access files on the pine server by means of the remote depot mechanism.
Grant read access to //from-pine to your integration or build managers. The only user at the oak site who requires access the //from-pine remote depot is the user (in this example, adm) who performs the integration from the remote depot to the local depot.
To accomplish this, the oak Perforce administrator should include the following lines to the p4 protect table:
list user * * -//from-pine/...
read user adm * //from-pine/...
On the remote (pine) site, access to code residing on pine is entirely the responsibility of the pine server's administrator. At a minimum, this administrator should:
Preemptively deny access to user remote across all depots from all IP addresses:
Adding these lines to the p4 protect table is sound practice for any Perforce installation whether its administrator intends to use remote depots or not.
Grant read access to user remote to only those areas of the pine server into which code drops are to be placed. In this example, outgoing code drops are published in the //depot/outbound/... subdirectory on the pine server.
Grant read access for user remote only to the IP address of the Perforce servers authorized to receive code drops. If oak's IP address is 192.168.41.2, the pine Perforce administrator should add the following to the p4 protect table:
Receiving a code drop
To perform a handoff or code drop between two Perforce installations:
1.
Developers on pine:1818 complete work on a body of code for delivery.
2.
The build or release manager on pine:1818 branches the deliverable code into an area of pine:1818 intended for outbound code drops. In this example, the released code is branched to //depot/outbound/...
3.
A Perforce administrator at oak:1234 configures a remote depot called //from-pine on the oak server. This remote depot contains a Map: field that directs the oak server to the //depot/outbound area of pine:1818.
4.
Upon notification of the release's availability, a build or release manager at oak:1234 performs the code drop by integrating files in the //from-pine/... remote depot into a suitable area of the local depot, such as //depot/codedrops/pine.
5.
Developers at oak:1234 can now use the pine organization's code, now hosted locally under //depot/codedrops/pine. Should patches be required to pine's code, oak developers can make such patches under //depot/codedrops/pine. The pine group retains control over its code.
Managing Unicode Installations
Overview
The Perforce server can be run in Unicode mode to activate support for:
Perforce identifiers (for example, user names) and specifications (for example, changelist descriptions or jobs) that contain Unicode characters
If you need to manage textual files that contain Unicode characters, but do not need the features listed above, you do not need to run your server in Unicode mode. For such installations, assign the Perforce utf16 file type to textual files that contain Unicode characters.
In Unicode mode, the Perforce server also translates unicode files and metadata to the character set configured for the client machine, and verifies that the unicode files and metadata contain valid UTF-8 characters.
To configure a Unicode-mode server and the client machines that access it, you must:
The following sections tell you how to configure your Perforce installation to manage such files.
The Perforce server limits the lengths of strings used to index job descriptions, specify filenames and view mappings, and identify client workspaces, labels, and other objects. The most common limit is 2048 bytes. Because no basic Unicode character expands to more than three bytes, you can ensure that no name exceeds the Perforce limit by limiting the length of object names and view specifications to 682 characters for Unicode-mode servers.
Configuring the Perforce Server
To enable the Perforce server to manage files and directories with names that include Unicode characters, you must configure your server to run in Unicode mode. In Unicode mode, the server:
Translates metadata and unicode files according to the client machine's P4CHARSET environment variable, and
Validates unicode files and metadata to ensure they are valid UTF-8
Enabling Unicode mode
To convert a server to Unicode mode, perform the following steps:
1.
Stop the server by issuing the p4 admin stop command.
2.
Create a server checkpoint, as described in the Perforce System Administrator's Guide.
3.
Convert the server to Unicode mode by invoking the server (p4d) and specifying the -xi flag, for example:
p4d -xi -r <p4root>
The server verifies that its existing metadata contains only valid UTF-8 characters, then creates and sets a protected counter called "unicode," which is used as a flag to ensure that the next time you start the server, it runs in Unicode mode. After validating metadata and setting the counter, p4d exits and displays the following message:
Server switched to Unicode mode.
4.
Restart p4d, specifying server root and port as you normally do. The server now runs in Unicode mode.
Localizing server error messages
By default, the Perforce server informational and error messages are in English. You can localize server messages. To ensure best results, contact Perforce Technical Support. The following overview explains the localization process.
To localize the Perforce server messages:
1.
2.
Edit the message file, translating messages to the target language. Each message includes a two-character language code. Change the language code from en to your own code for the target language. Do not change any of the key parameters or named parameters (which are specified between percent signs, for example, %depot% ). You can change the order in which the parameters appear in the message.
Example of correct translation:
Original English
@pv@ 0 @db.message@ @en@ 822220833 @Depot '%depot%' unknown - use 'depot' to create it.@
Correct translation to Portuguese (note reordered parameters)
@pv@ 0 @db.message@ @pt@ 822220833 @Depot '%depot' inexistente - use o comando 'depot' para criar-lo.@
3.
p4d -jr /fullpath/message.txt
To view localized messages, set the P4LANGUAGE environment variable on client machines to the language code you assigned to the messages in the translated message file. For example, to have your messages returned in Portuguese, set P4LANGUAGE to pt.
To view localized messages using P4V, you must set the LANG environment variable to the language code that you use in the messages file.
Configuring Client Machines
To correctly interoperate with Unicode-mode servers, you must configure client machines by setting the P4CHARSET environment variable. Recommendation: use separate workspaces for connections that require different character sets.
If you access your server from an incorrectly configured client machine, you risk data corruption! For example, if you submit a file using a P4CHARSET that is different than the one you used to sync it, the file is translated in a way that is likely to be incorrect.
Setting P4CHARSET on Windows
To set P4CHARSET for all users on a workstation, you need Perforce administrator privileges. Issue the following command:
p4 set -s P4CHARSET=character_set
To set P4CHARSET for the user currently logged in:
p4 set P4CHARSET=character_set
Your client machine must have a compatible True Type or Open Type font installed.
Setting P4CHARSET on Unix
You can set P4CHARSET from a command shell or in a startup script such as .kshrc, .cshrc, or .profile. To determine the proper value for P4CHARSET, examine the setting of the LANG or LOCALE environment variable. Common settings are as follows:
In general, for a Japanese installation, set P4CHARSET to eucjp, and for a European installation, set P4CHARSET to iso8859-1.
The following table lists common settings for P4CHARSET.
UNIX (LOCALE setting varies)
shiftjis or eucjp
High-ASCII
(recommended by ISO for use in modern European languages)
UNIX (LOCALE setting varies)
iso8859-1 or iso8859-15
Classic MacOS (LOCALE setting varies)
For details about the UTF-8 and UTF-16 variants, see UTF character sets and Byte Order Markers (BOMs).
Windows: Determining your Code Page
A code page maps characters to values. On Windows machines, the value that you assign to P4CHARSET depends on the code page that your client machine uses.
To determine the code page in use on a Windows machine, either:
From the control panel, launch the Regional and Language Options control panel. On the Languages tab, click the Details... button.
From the command prompt, issue the chcp.exe command Your current code page is displayed; for example:
Active code page: 1252
Note that the DOS environment can be assigned a code page that is different from the one that is inherited by programs that are launched from the Start menu.
UTF character sets and Byte Order Markers (BOMs)
Byte order markers (BOMs) are used in UTF files to specify the order in which multibyte characters are stored and to identify the file content as Unicode. Not all extended-character file formats use BOMs.
To ensure that such files are translated correctly by the Perforce server when the files are synced or submitted, you must set P4CHARSET to the character set that corresponds to the format used on your client machine by the applications that access them, such as text editors or IDEs. Typically the formats are listed when you save the file using the Save As... menu option.
The following table lists valid settings for P4CHARSET for specifying byte order properties of UTF files.
Client Unicode format
Big or
Little-Endian
Synced with a BOM according to the client platform byte order
Synced with a BOM according to the client platform byte order
If you set P4CHARSET to a UTF-8 setting, the Perforce server does not translate text files when you sync or submit them. Starting with release 2006.1, Perforce verifies that such files contain valid UTF-8 data.
Controlling translation of server output
If you set P4CHARSET to any utf16 or utf32 setting, you must set the P4COMMANDCHARSET to a non utf16 or utf32 character set in which you want server output displayed. "Server output" includes informational and error messages, diff output, and information returned by reporting commands.
To specify P4COMMANDCHARSET on a per-command basis, use the -Q flag. For example, to display all filenames in the depot, as translated using the winansi code page, issue the following command:
p4 -Q winansi files //...
Diffing files
The p4 diff2 command, which compares two depot file revisions, can only compare files that have the same Perforce file type.
Using other Perforce client applications
If you are using other Perforce client applications, note how they handle Unicode environments:
P4V (Perforce Visual Client): the first time you connect to a Unicode-mode server, you are prompted to choose the character encoding. Thereafter, P4V retains your selection in association with the connection.
P4Web: when you invoke P4Web, you can specify the character encoding on the command line using the -C flag. P4Web uses this flag when it sends commands to a Unicode-mode server. This approach means that each instance of P4Web can handle a single character encoding and that browser machines must have compatible fonts installed.
P4Merge: To configure the character encoding used by P4Merge, choose P4Merge's File>Character Encoding... menu option.
IDE plug-ins (SCC-based): the first time you connect to a Unicode-mode server, you are prompted to choose the character encoding. Thereafter, the plug-in retains your selection in association with the connection.
Troubleshooting Client Machines in Unicode installations
To prevent file corruption, it is essential that you configure your client machine correctly. The following section describes common problems and provides solutions.
This message is displayed if your client machine is configured with a character set that does not include characters that are being sent to it by the Perforce server. Your client machine cannot display unmapped characters. For example, if P4CHARSET is set to shiftjis and your depot contains files named using characters from the Japanese EUC character set that do not have mappings in shift-JIS, you see the "Cannot translate" error message when you list the files by issuing the p4 files command.
To ensure correct translation, do not use unmappable characters in Perforce user specifications, client specifications, jobs, or file names.
If you attempt to display an extended-character text file and see odd-looking text, your client machine might lack the font required to display the characters in the file. Typical symptoms of this problem include the display of question marks or boxes in place of characters. To solve this problem, install the required font.


Previous Table of Contents Index Next

Perforce 2009.2: System Administrator's Guide
Copyright 1997-2009 Perforce Software.