Each of the tasks described in this chapter requires that you be a Perforce superuser as defined in the Perforce protections table. For more about controlling Perforce superuser access, and protections in general, see "Administering Perforce: Protections" on page 61.

Basic Perforce Administration

• User operations, including resetting passwords, creating new users, disabling the automatic creation of new users, and cleaning up files left open by former users,

• Administrative operations, including obliterating files to reclaim disk space, editing previously submitted changelists, verifying server integrity, defining filetypes to fine-tune Perforce's file type detection mechanism, and the use of the -f flag to force operations.

Resetting user passwords

• Release 99.1 and later:
  p4 passwd username

(Perforce prompts the superuser for a new password for user username.)

• Pre-99.1 releases:
  p4 user -f username

(The user specification form for username appears, and the new password may be entered.)

Creating new users

p4 user -f username

The p4 user command also has an option (-i) to take its input from the standard input instead of the forms editor. If you wish to create a large number of new users at once, you can write a script which creates output in the same format as that used by the forms editor and then pipes each pre-generated "form" to p4 users -i -f username, where the username is also specified by a variable within your calling script.

Preventing creation of new users

To prevent Perforce from automatically creating new users, all users must be explicitly listed in the protections table. The easiest way to ensure that this is the case is to put all users into a Perforce group, and to configure Perforce to only permit access 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:  A limit on the data size of operations for users in #               this group, or 'unlimited'. #  Subgroups:   Other groups automatically included in this group. #  Users:       The users in the group.  One per line. Group:  p4users MaxResults:     unlimited Subgroups: Users:         edk         lisag         sarahm

He then uses p4 protect to edit the protections table. The relevant line of the default protections table looks like this:

write user * * //...

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 //...).

After using p4 group p4users  to create the Perforce group p4users, he uses p4 protect to change this line in the protections table to read:

write group p4users * //...

The replacement protection grants only write access to users whose group matches p4users. Members of p4users may 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 permission to all users, all users are now defined within p4 protect, and the server will no longer automatically create new user entries when new users attempt to access Perforce.

For a more in-depth description of Perforce protections, see "Administering Perforce: Protections" on page 61.

Deleting obsolete users

p4 user -d username

Reverting files left open by obsolete users

For example, if the output of p4 opened shows:

//depot/main/code/file.c#8 - edit default change (txt) by jim@stlouis

p4 client -d -f stlouis

Reclaiming disk space by obliterating files

Warning!

Use p4 obliterate with caution. This is the only command in Perforce that actually removes file data.

Because p4 delete merely marks files as deleted in their head revisions, it can't be used to free up disk space on the server. This is where p4 obliterate can be useful. Superusers 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.

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.

If you need to destroy only one revision of a file (perhaps someone inadvertently stored some line art as a 20-megabyte uncompressed TIFF in place of its 500K-long compressed equivalent), 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

p4 obliterate -y file#5,7

Warning!

If you mean to obliterate a revision range, be certain you've specified it properly. If you omit the specify revision range, all revisions of the file will be obliterated! The safest way to use p4 obliterate is to use it without the -y (confirmation) flag until you're certain you've specified the files and revisions correctly.

Unlike the -y flag, the -z flag increases disk space usage by removing the lazy copies. It's generally not a flag you'll use often, as its only use is to undo lazy copies in order to allow you to manually remove archive files without breaking any linked metadata pointing to the deleted files.

If a user sees the following error message while trying to access files:

Operation:user-sync
Librarian checkout path failed

Deleting changelists and editing changelist descriptions

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.

File verification by signature

To generate signatures and store them in the Perforce database, use the -u flag. Subsequent verifications will be compared against the stored signatures; if a new signature does not match the signature in the Perforce database for that file revision, Perforce adds the characters BAD! after the signature.

If you ever see a BAD! signature during a p4 verify command, your database or versioned files may have been corrupted, and you should contact Perforce Technical Support.

Because subsequent verifications can only be performed against previously stored signatures, the p4 verify -u command should be used regularly. A good strategy, for instance, might be to run p4 verify on a nightly basis before performing your system backups, proceeding with the backup only if the p4 verify reports no corruption. Generation and storage of new checksums (p4 verify -u) following a successful p4 verify could be performed nightly, or even weekly.

Verifying during server upgrades

1. Before the upgrade, run:
   p4 verify -qu //...

   to generate the new checksums.

2. Take a checkpoint and copy the checkpoint and your versioned files to a safe place.

3. Perform the server upgrade.

4. After the upgrade, run:
   p4 verify -q //...

   to verify the integrity of your system.

Defining filetypes with p4 typemap

In previous releases, Perforce automatically determined if a file was of type text or binary based on an analysis of the first 1024 bytes of a file. If the high bit was clear in each of the first 1024 bytes, Perforce assumed it to be text; otherwise, it was binary. Although this default behavior could be overridden by the use of the -t filetype flag, it was easy to overlook this, particularly in cases where files' types were usually (but not always) detected correctly.

The p4 typemap command solves this problem by allowing system administrators to set up a table that links Perforce file types with file name specifications. If an entry in the typemap table matches an entry in the table, it overrides the file type that would otherwise be assigned by the Perforce client.

One common use for p4 typemap is for users dealing with Adobe PDF (Portable Document Format) files. Some PDF files start with a series of comment fields and textual data, and if the comments are sufficiently long, the files will be erroneously detected by Perforce as being of type text. Similarly, files in RTF (Rich Text Format) format may sometimes be erroneously detected as text.

Perforce superusers may use p4 typemap to tell the Perforce server to regard all such files as binary by modifying the typemap table as follows:

The first three periods ("...") in the specification are a Perforce wildcard specifying that all files beneath the root directory are to be included as part of the mapping. The fourth period and the file extension specify that the specification applies to files ending in ".pdf" (or ".rtf").

For more information, see the p4 typemap page in the Perforce Command Reference.

Forcing operations with the -f flag

Advanced Perforce Administration

Running Perforce through a firewall

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 which 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

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.ssh.org. 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). More information can be found at the Open SSH page (http://www.openssh.org).

The ssh FAQ (Frequently Asked Questions) list can also be found online, either at the main site (http://www.uni-karlsruhe.de/~ig25/ssh-faq), or at the FAQ archive at MIT: (ftp://rtfm.mit.edu/pub/usenet/news.answers/computer-security/ssh-faq).

Solving the problem

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 our own machine to set up and forward the TCP/IP connection would be:

ssh -L 4242:p4dbox.bigcorp.com:3710 firewall.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

ssh -n -L 4242:p4dbox.bigcorp.com:3710 firewall.bigcorp.com sleep 9999999 &

This tells ssh on firewall.bigcorp.com to run the sleep command for a very long time. The -n flag tells ssh not to read from stdin, and the & tells the OS to run the process in the background. 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 allow 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

If, however, you specify both an IP address and a port number in P4PORT when starting p4d, the Perforce server takes the IP address into account, and 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 tell p4d to listen only to a specific network interface or IP address, you can make your Perforce server ignore all non-local connection requests by setting P4PORT=localhost:port.

Running from inetd on UNIX

If you wish to do this, add the following line to /etc/inetd.conf:

p4dservice stream tcp nowait username /usr/local/bin/p4d p4d -i -rp4droot

p4dservice nnnn/tcp

• 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

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 which invokes several thousand p4 commands, each of which spawns an instance of p4d via inetd may cause inetd to temporarily disable the service. Depending on your system, you may 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 multi-platform development

For example, //depot/main/foo.c and //depot/MAIN/FOO.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.

If you are running a pre-97.2 server on Windows, please contact [email protected] to discuss upgrading your server and database. 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 which users can run into when sharing development projects across UNIX and Windows.

To summarize:

• The Perforce server on UNIX supports case-sensitive names.

• The Perforce server on Windows ignores case differences.

• Case is always ignored in keyword-based job searches, regardless of platform

  Case-sensitive	UNIX server	Windows server
  Pathnames and filenames	Yes	No
  Database entities (clients, labels, etc.)	Yes	No
  Job search keywords	No	No

Perforce server on UNIX

Conversely, Windows users will have to be careful to use case consistently in file and path names when adding new files. They may not realize that files added as //depot/main/foo.c and //depot/MAIN/bar.c will appear in two different directories in 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 examples, 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

For example, users who try something like this:

p4 add foo/file1
p4 add foo/file2
p4 add FOO/file3

Perforce server trace flags

p4d -r /usr/perforce -v server=1 -p 1666 -L /usr/perforce/logfile

In most cases, the Perforce server trace flags are useful only to administrators working with Perforce Technical Support to diagnose or investigate a problem.

Migrating to a new machine

• of identical architecture,

• of different architectures using the same text file (CR/LF) format, or

• of different architecture and different text file format.

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" on page 25.

Moving your versioned files and Perforce database

Between machines of the same architecture

1. Back up your server (including a p4 verify before the backup) and take a checkpoint.

2. On the old machine, stop p4d.

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.

Between different architectures using the same text format

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 recreate the database on the new machine. The checkpoint is a text file which can be read by a Perforce server on any architecture. For more details, see "Creating a checkpoint" on page 26.

After creating 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 recreated from the checkpoint you took.)

1. On the old machine, use p4 verify to ensure that the database is in a consistent state.

2. On the old machine, stop p4d.

3. On the old machine, create a checkpoint:
   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 recreated 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. Recreate 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.

Between Windows and UNIX

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") will need to be transferred differently 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.

Contact Perforce Technical Support for assistance when migrating a Perforce server from Windows to UNIX or vice-versa.

Changing the IP address of your server

If you are a licensed Perforce customer, you will also need a new license file to reflect the new IP address. Contact Perforce technical support to obtain an updated license.

Changing the hostname of your server

Using Multiple Depots

When using local depots, the user's 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 uses its default Perforce server as a proxy client to a second, remote, Perforce server. Because of this proxy behavior, the client doesn't need to know where the files are actually stored, and doesn't need direct access to the remote Perforce server.

The use of depots on remote servers ("remote depots") is limited to read-only operations; a Perforce client may not add, edit, integrate into, or delete files that reside in depots on other servers. Depots sharing the same Perforce server as the client ("local depots") are not subject to this limitation.

The following diagram illustrates how remote depots use a user's default Perforce server as a proxy.

Remote depot notes

This is not the case. 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.

Remote depots are designed to support shared code, not shared development. They enable independent organizations with their own Perforce installations to view files and integrate changes from depots in other installations. Remote depots are not a generalized solution for load-balancing or network access problems.

When and when not to use remote depots

If, however, you regularly import works from other organizations as part of your own organization's body of software, you may wish to consider using Perforce's remote depot features. This is what remote depots were designed for: facilitating the sharing of code, not development, across organizations.

Restrictions on remote depots

• Access is restricted to read-only operations. You cannot submit files into a remote depot. You cannot edit files in remote depots. You can, however, 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, as you cannot make changes in the local branch and integrate them back into the remote depot.

• Remote depots may be accessed only by Perforce servers running at the same release levels.

• Windows and UNIX servers are incompatible; you will get unpredictable results accessing remote depots on Windows from a UNIX server or vice versa.

• A Perforce server's metadata (information about client workspaces, changelists, labels, and so on) cannot be accessed using remote depots. Commands like p4 client only return specifications of entities defined in the local server's metadata.

Defining new depots

Defining local depots

Although you can set the Map: field to point to a depot directory other than one matching the depot name, there is rarely any advantage to be had by doing so, and it can make life confusing if you (as an administrator) ever need to work with the directories in the server root.

Defining remote depots

Example:  Defining a remote depot

Lisa is working on a GUI porting project. She and Ed are using different Perforce servers; his is on host pine, and it's listening on port 1818. Lisa wants to grab Ed's GUI routines for her own use; she knows that Ed's color routine files are located on his Perforce server's single depot under the subdirectory graphics/GUI.

Lisa's first step towards accessing Ed's files is to create a new depot. She'll call this depot gui; she'd type p4 depot GUI and fill in the form as follows:

Depot:       gui Type:        remote Address:     pine:1818 Map:         //depot/graphics/gui/...

This creates a remote depot called gui on Lisa's Perforce server; this depot (gui) maps to Ed's depot's namespace under its graphics/gui subdirectory.

The Map: field

• For local depots, the mapping should contain a subdirectory relative to the file space of the Perforce server root directory. For example, graphics/gui/... maps to the graphics/gui subdirectory of the server root.

• For remote depots, the mapping should contain a subdirectory relative to the remote depot namespace. For example, //depot/graphic/gui/... would map to the graphic/gui subdirectory of the remote server depot named depot.

If you are unfamiliar with client views and mappings, please consult the Perforce User's Guide for general information about how Perforce mappings work.

Other depot operations

Naming depots

Listing depots

Deleting depots

To delete a depot, it must be empty; you must first obliterate all files in the depot with p4 obliterate.

For local 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 using 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" on page 41.

Limiting access from other servers

To limit or eliminate remote access to a particular server, use p4 protect to set permissions for user remote on that server. For example, to eliminate remote access to all files in all depots on a particular server, set the following permission on that server:

read user remote *  -//...

Users working with multiple depots

The Perforce User's Guide contains detailed information for users who will be working with more than one depot.