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.
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.
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.
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:
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.
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:
where seclevel is 0, 1, 2, or 3. After setting the counter, stop and restart the server.
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.
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.
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:
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.
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.
# 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
//...).
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 (
//...).
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.
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.
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.
you can delete the stlouis client workspace specification with:
Deleting a client workspace specification automatically reverts all files opened in that workspace, deletes pending changelists associated with the workspace, and any 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.
|
|
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.
|
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.
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.
Use p4 change with the
-f (force) flag:
The User: and
Description: fields for change
123 are edited, and change
124 is deleted.
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.
It is good practice to use p4 verify as follows before and after server upgrades:
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).
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.
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:
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.
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.
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.
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).
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:
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.
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.
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.
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.
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 -r
p4droot
|
•
|
p4dservice is the service name you choose for this Perforce server
|
|
•
|
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.
|
•
|
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.
|
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 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.
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.)
Use the p4 monitor command to obtain 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.
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.
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 show74612 R qatool 00:00:47 job 78143 R edk 00:00:01 filelog 78207 R p4admin 00:00:00 monitor
|
$ p4 monitor show -a74612 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
|
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 -e74612 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 -l74612 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
|
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.
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.
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.
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:
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.
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.
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.
date time user@
client clientIP command file#
rev
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.
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).
|
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.)
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.)
(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.)
|
6.
|
Re-create a new set of db.* files suitable for your new machine's architecture from the checkpoint you created:
|
|
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.
|
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.
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 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.
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 specifications, and so on. There can be only one
spec depot per server.
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.
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.
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 specifications, 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]
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
or by using P4V to review changes to job000123.p4s in whatever editor is associated with the
.p4s file extension on their workstation.
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 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:
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.
To delete a depot, use p4 depot -d depotname.
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 are designed to support shared code, not shared
development. They enable independent organizations with separate Perforce installations to integrate changes between Perforce installations. Briefly:
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.
In this example, an administrator of a Perforce server at oak:1234 is retrieving a file from a remote server at
pine:1818.
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.
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.
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:
|
4.
|
Set the Map: field to map into the desired portion of the remote server's namespace.
|
The Map: field must contain a single line pointing to this subdirectory, specified in depot syntax, and containing the "
..." wildcard on its right side.
|
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.
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.
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:
Since remote depots can only be used for
read access, it is not necessary to remove
write or
super access to user
remote.
Using the two organizations described in Receiving a code drop, a basic set of security considerations for each site would include:
|
•
|
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.
|
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:
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:
|
|
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.
|
|
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. 
|
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.
|
|
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.
|
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:
|
•
|
Validates unicode files and metadata to ensure they are valid UTF-8
|
|
4.
|
Restart p4d, specifying server root and port as you normally do. The server now runs in Unicode mode.
|
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 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 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.
To set P4CHARSET for all users on a workstation, you need Perforce administrator privileges. Issue the following command:
To set P4CHARSET for the user currently logged in:
p4 set P4CHARSET=
character_set
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.
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.
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 menu option.
The following table lists valid settings for P4CHARSET for specifying byte order properties of UTF files.
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.
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:
The p4 diff2 command, which compares two depot file revisions, can only compare files that have the same Perforce file type.
|
•
|
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 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.
|
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.
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.
Copyright 1997-2009 Perforce Software.
