Perforce 2000.1 System Administrator's Guide (2000.1.sa.3)
<< Previous Chapter
Supporting Perforce:
Backup and Recovery
 Table of Contents
Index
Perforce on the Web
 Next Chapter >>
Administering Perforce:
Protections
Chapter 3
Administering Perforce:
Superuser Tasks
This chapter describes both basic tasks associated with day-to-day Perforce administration as well as setting up advanced Perforce configurations, dealing with cross-platform development issues, migrating Perforce servers from one machine to another, and setting up remote and local depots.

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 43.

Basic Perforce Administration


The following tasks commonly performed by Perforce administrators are covered:

Resetting user passwords

From time to time, it is inevitable that users will forget Perforce passwords. A Perforce superuser can set a new password for any user with:

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

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

Creating new users

By default, Perforce creates a new user in its database whenever a command is issued by a username it hasn't seen before. You can use the -f (force) flag to create a new user as follows:

Fill in the form fields with the information for the user you wish to create.

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

As mentioned, Perforce's default behavior is to create a new user in its database whenever a command is issued by a username it hasn't seen before. As of Release 98.2, Perforce groups can be used to control user access. Using groups, a Perforce superuser can disable the automatic creation of new users by assigning all authorized users to a group, and denying write access to users not in the authorized group.

You can create a Perforce group by using:

and adding users in the Users: field of the resulting form, one per line.

To grant write access to only those users in the newly-created group, use p4 protect and edit the protections table. The relevant line of the default protections table looks like this:

It grants write permission to all users in all areas of the depot. After using p4 group groupname to create the Perforce group groupname, use p4 protect to change the protections table to read:

This will restrict write access only to users who are part of the Perforce group groupname. Other users will not be able to automatically create new Perforce users until they have been added to this group. For a more in-depth treatment of Perforce protections, see "Administering Perforce: Protections" on page 43.

Reverting files opened by obsolete users

If files have been left open by a nonexistent or obsolete username (e.g., an ex-employee), a Perforce superuser can revert the files by deleting the client spec in which they were opened.

For example, if the output of p4 opened shows:

the "stlouis" client spec can be deleted with:

Deleting a client spec reverts all files opened by that client, and removes that client's "have list". Note that it does not affect any files in the workspace actually used by that client; the files can still be accessed by other employees.

Reclaiming diskspace by obliterating files

The depot is always growing; this is not always desirable: a submit might have been performed incorrectly, creating hundreds of unneeded files, or perhaps there are simply a lot of old files around that are no longer being used.

Because p4 delete merely marks files as deleted in their head revisions, it can't be used to free up diskspace. This is where p4 obliterate can be useful. p4 obliterate filename can be used by superusers to remove all traces of a file from a depot, making the file indistinguishable from one that never existed in the first place.

Note

The purpose of a software configuration management system is to allow your site to maintain a history of which operations were performed on which files. The p4 obliterate command defeats this purpose; as such, it is only intended to be used when cleaning up messes in the depot; not as part of your normal software development process.

In fact, p4 obliterate is so destructive that we haven't even told you how it really works yet. By default, p4 obliterate filename does nothing; it merely reports on what it will do; to actually destroy the files, use p4 obliterate -y filename.

There is an additional flag to p4 obliterate; the -z flag. When you branch a file from one area of the depot into another, a "lazy copy" is created - the file itself isn't copied, only a record that the branch has occurred. If, for some reason, you wish to undo the "lazy copy" and create a new copy of the branched file's contents in your depot subdirectories, you could "obliterate" the lazy copy and create a new one by using p4 obliterate -z filename. Unlike the -y flag, the -z flag increases diskspace usage by removing the lazy copies. It's generally not a flag you'll use often; 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:

where path is the path of a previously-obliterated file, odds are the user has encountered a problem that resulted from an earlier use of p4 obliterate from an older (pre-98.2/10314) Perforce server. Contact Perforce technical support for a workaround.

Deleting changelists and editing changelist descriptions

The -f (force) flag can be used with p4 change to change the description or username of a submitted changelist. The syntax is p4 change -f changenumber; this presents the standard changelist form, in which the change time, description, and/or username may be edited.

The -f flag can also be used to delete any submitted changelists that have been emptied of files with p4 obliterate. The full syntax is p4 change -d -f changenumber.

File verification by signature

The p4 verify filenames command can be used to generate 128-bit MD5 signatures of each revision of the named files. A list of signatures stored by p4 verify -u 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.

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

It is also good practice to use p4 verify during server upgrades:

  1. Before the upgrade, run:

    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:

    to verify the integrity of your system.

Defining filetypes with p4 typemap

As of Release 2000.1, Perforce supports a new command: 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 will override the file type that would otherwise have been 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:

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 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 Command Reference.

Forcing operations with the -f flag

Certain commands allow the superuser to use the -f flag to force certain operations unavailable to ordinary users. This flag can be used with p4 branch, p4 change, p4 client, p4 job, p4 label, and p4 user. The usages and meanings of this flag are as follows:

Command
 Syntax
 Function

p4 branch

p4 branch -f branchname

Allows the modification date to be changed while editing the branch specification

p4 branch -f -d branchname

Deletes the branch, ignoring ownership

p4 change

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#

Deletes empty, committed changelists

p4 client

p4 client -f clientname

Allows the modification date to be changed while editing the client specification

p4 client -f -d clientname

Deletes the client, ignoring ownership, even if the client has opened files

p4 job

p4 job -f [jobname]

Allows the manual update of read-only fields

p4 label

p4 label -f labelname

Allows the modification date to be changed while editing the label specification

p4 label -f -d labelname

Deletes the label, ignoring ownership

p4 user

p4 user -f username

Allows the update of all fields, ignoring ownership

p4 user -f -d username

Deletes the user, 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 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 will 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.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

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

At this point, it may be necessary to provide a password to log into firewall.bigcorp.com. Once the connection is established, ssh will listen at port 4242 on the local machine, and forward anything it is told over its encrypted connection to firewall.bigcorp.com, and the firewall will then forward 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

on the remote system.

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

Under most circumstances, your Perforce server's P4PORT setting will consist solely of a port number.

If, however, you specify both an IP address and a port number in P4PORT when starting p4d, the Perforce server will take the IP address into account, ignoring 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. For instance, by setting P4PORT=localhost:port, you can make your Perforce server ignore all non-local connection requests.

Running from inetd on UNIX

Under a normal installation, the Perforce server is run on UNIX as a background process which waits for connections from clients. It is possible, however, to have p4d start up only when connections are made to it, using inetd and p4d -i.

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

and add the following to /etc/services:

where:

Note the "extra" p4d on the /etc/inetd.conf line must be there; 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:

Case-sensitivity and multi-platform 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 NT. 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 NT, 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 NT, please contact [email protected] to discuss upgrading your server and database.) As of Release 97.3, this was changed; 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 NT.

To summarize: the Perforce server on UNIX supports case-sensitive names. The Perforce server on NT ignores case differences. Case is always ignored in keyword-based job searches:

Case-sensitive
 UNIX server
 NT server

Pathnames and filenames

Yes

No

Database entities (clients, labels, etc.)

Yes

No

Job search keywords

No

No

Users can run p4 info to find out what platform their Perforce server runs on.

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 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, etc. 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 an NT workstation named ROCKET, his client workspace will be 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 NT

If your Perforce server is running on NT, 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:

should be aware that all three files will be stored in the same depot directory. The depot path and filenames assigned to the NT server will be those first referenced. (in this case, the depot path name would be foo, and not FOO.

Perforce server trace flags

You can turn on command tracing in the Perforce server by adding the -v server=1 flag to the p4d startup command. Use P4LOG or the -L logfile flag to name a log file. For example:

Trace output will appear in the specified log file, and will show the date, time, username, IP address, and command for each request processed by the server. You should make that you have adequate diskspace before turning on logging.

95/98/NT

Prior to Release 98.1, you could not set this trace flag when running Perforce as an NT service; you could set this flag on NT only when running p4d.exe a server process from the MS-DOS command line.

As of Release 98.1, you can use the p4 set command to set P4DEBUG as a registry variable to "server=1" and thereby use this trace flag with Perforce installed as a service on NT.

Prior to Release 97.3, the server trace flag was unavailable on any server platform.

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


The procedure for moving an existing Perforce installation from one machine to another depends on whether or not you're moving between machines

There are also additional considerations if the new machine has a different IP address or 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 the backup and restore procedure in general, see "Backup and Recovery Concepts" on page 19.

Moving your versioned files and Perforce database

Between machines of the same architecture:

If the architecture of the two machines is the same (e.g., Solaris/Solaris, NTx86/NTx86, or even SunOS 4.x/Solaris), the versioned files and database can be copied directly between the machines, and you need only 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. On the old machine, stop p4d.

  2. 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.

  3. Start p4d on the new machine with the desired flags.

Between different architectures using the same text format:

If the internal data representation (big-endian vs. little-endian) convention differs between the two machines (e.g., HP/Sun, NT-on-Alpha/NTx86), 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.

While the versioned files are portable across architectures, the database, as stored in the db.* files, is not. To overcome this problem, create a checkpoint of your Perforce server database 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 20.

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 won't need to copy the db.* files, because they will be recreated from the checkpoint you took.)

  1. On the old machine, stop p4d.

  2. On the old machine, create a checkpoint:

  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.

    (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, copy everything.)

  4. On the new machine, if you copied the db.* files, be sure to remove them from the new P4ROOT before continuing.

  5. Recreate a new set of db.* files suitable for your new machine's architecture from the checkpoint you created:

  6. Start p4d on the new machine with the desired flags.

Between NT and UNIX:

In this case, both the architecture of the system and the CR/LF text file convention are different. You will still have to create a checkpoint, copy it, and recreate the database on the new platform, but when you move the depot subdirectories containing your versioned files, you will also have to deal with 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") will need to be transferred differently in order to translate the line endings on the text files while leaving the binary files unchanged.

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

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 may need to update IP-address-based protections in your protections table. See "Administering Perforce: Protections" on page 43 for information on setting protections for your Perforce server.

If you are a licensed Perforce customer, you will also need to get 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

If the hostname of the new machine serving Perforce is different from that of its predecessor, your users will need to 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


Just as Perforce servers can host multiple depots, Perforce client programs can access files from multiple depots. These other depots may reside within the Perforce server normally accessed by the Perforce client, or they may reside within other, remote, Perforce servers.

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 following diagram illustrates how remote depots use a user's default Perforce server as a proxy.

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.

Remote depot notes

The term "remote depot" is actually somewhat misleading; new Perforce customers tend to assume that if their users are geographically distributed, they will need to set up separate Perforce installations (i.e. servers running p4d) and interconnect them with remote depot support.

This is not, in fact, the case. Perforce is designed to cope with the latencies of large networks, it 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 you're doing distributed development, you probably want to use a single Perforce installation, with all code in depots managed by one Perforce server. Partitioning joint development projects into separate Perforce installations will not improve throughput, and usually only complicates administration.

If, however, you're regularly importing 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:

Users of remote depots will encounter several restrictions:

In general, most of the restrictions associated with remote depots are either insignificant (e.g., lack of remote access to metadata) or beneficial (e.g., read-only access) if you're using remote depots for their intended purpose: the sharing of code, not development, between separate organizations.

Defining new depots

New depots (local or remote) in a server namespace are defined with the command p4 depot depotname.

Define the default depot

As of Release 99.2, if you wish to create a new depot and have not already defined the default depot, you must first define the default depot to tell Perforce to set up its metadata for use with multiple depots.

Note

If you don't define the default depot before attempting to create a new depot, Perforce will attempt to overwrite the default depot's metadata with that of your new depot; this is generally not the desired behavior!

To define the default depot, run p4 depot with the default depotname of depot. The p4 depot command will bring up the following form:

Depot:      depot
Type:       local
Address:    subdir
Map:        depot/...

When p4 depot depot is invoked, the form is filled in with values representing the state of the default depot. Its name is depot. It resides in the local Perforce server namespace; so its type is local, (as opposed to remote). The Map: field indicates the location of the depot subdirectory relative to the root directory of the Perforce server; in this default case, the depot called depot starts in the depot subdirectory directly underneath the server root. (i.e. $P4ROOT/depot)

Now that you've defined the default depot, you can define other depots as you require.

Defining local depots

To define a new local depot (that is, a new depot in the current Perforce server namespace), p4 depot is called with the new depot name, and only the Map: field in the resulting form need be changed. 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 (i.e., $P4ROOT/book), the command p4 depot book would be typed, and the resulting form would be filled in as follows:

Depot:       book
Type:        local
Address:     subdir
Map:         book/...

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 should you (as an administrator) ever need to work with the directories in the server root.

Defining remote depots

Defining a new depot on a remote Perforce server is only slightly more complicated. The Type: is remote; the server address must be provided in the Address: field, and the Map: field must be given a mapping into the remote depot namespace.

The Map: field

The Map: field is analogous to a client's view, except that the view may contain multiple mappings and the Map: field always contains a single mapping. This single client mapping format changes depending on whether the depot being defined is local or remote:

Note that the mapping subdirectory must always contains the "..." wildcard on its right side.

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

Depot names share the same namespace as branches, clients, and labels. For example, //foo refers uniquely to one of the depot foo, the client foo, the branch foo, or the label foo; you can't simultaneously have both a depot and a label named foo.

Listing depots

All depots known to the current Perforce server can be listed with the p4 depots command.

Deleting depots

Depots may be deleted with p4 depot -d depotname.

Limiting access from other servers

Remote depots are always accessed by a virtual user named remote. which does not consume a Perforce license. By default, all the files on any Perforce server may 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. For example, to eliminate remote access to all files in all depots on a particular server, set the following permission on that server:

Since remote depots can only be used for read access, it is not necessary to remove write or super access.

Users working with multiple depots

If your users will be using remote depots as well as local depots, they should be aware of certain caveats regarding the behavior of files in remote depots as opposed to local depots, as described in the preceding sections.

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

Perforce 2000.1 System Administrator's Guide (2000.1.sa.3)
<< Previous Chapter
Supporting Perforce:
Backup and Recovery
 Table of Contents
Index
Perforce on the Web
 Next Chapter >>
Administering Perforce:
Protections
Please send comments and questions about this manual to [email protected].
Copyright 1999, 2000 Perforce Software. All rights reserved.
Last updated: 10/11/00