Superuser Tasks

Contents

  1. Reset Passwords
  2. Create Users
  3. Prevent Creation of New Users
  4. Delete obsolete users
  5. Revert files left open by obsolete users
  6. Obliterating files
  7. Edit changelists
  8. File verification by signature
  9. Verifying during server upgrades
  10. Define filetypes with p4 typemap
  11. Force operations with the -f flag
  12. Firewalls and SSH
  13. Specify IP addresses in P4PORT
  14. Run from inetd on UNIX
  15. trace flags
  16. Move versioned files between hosts
  17. Change IP address of a server
  18. Change hostname of a server
  19. Multiple Depots
  20. Define new depots
  21. Defining local depots
  22. Defining remote depots
  23. Naming depots
  24. Delete depots
  25. Limiting access from other servers
  26. Users working with multiple depots

 

Reset Passwords

To set a new password for any user:
p4 passwd username

 

Create Users

To create a new user as follows:
p4 user -f username
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 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.

 

Prevent Creation of New Users

To prevent Perforce from automatically creating new users, put all users into a Perforce group, and configure Perforce to only permit access to members of that group. For example, to set up a group called myusers, run...

p4 group myusers

...and fill in the form... 

    # 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:          myusers
    MaxResults:     unlimited
    Subgroups:
    Users:          user1
                    user2
                    user3
                    user4
...then use p4 protect to edit the protections table. Change...

write user * * //...
...to...

write group myusers * //...

 

Delete obsolete users

Each user on the system consumes one Perforce license. You can free up licenses from unused users by deleting them.

p4 user -d username
You must first revert (or submit) any open files opened by a user before deleting that user. If you attempt to delete a user who has opened files, Perforce will display an error message to that effect.

 

Revert files left open by obsolete users

If files have been left open by a nonexistent or obsolete user (for instance, a departing employee), a Perforce superuser can revert the files by deleting the client spec in which they were opened.

For example, if the output of p4 opened shows:

depot/main/code/file.c#8 - edit default change (txt) by sam@heracles
the "heracles" client spec can be deleted with:

p4 client -d -f heracles
Deleting a user's client spec automatically reverts all files opened by that client, and also 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.

 

Obliterating files

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

The depot is always growing, and 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 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.

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, and not as part of your normal software development process.

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
Revision ranges are also acceptable: To destroy revisions 5 through 7 of a file:

p4 obliterate -y file#5,7

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.

The p4 obliterate command has one more flag: -z. 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 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.

 

Edit changelists

You can use the -f (force) flag 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, but allows you to edit the change time, description, and/or username.

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

    The User: and Description: fields for change 123 are edited, and change 124 is deleted.

 

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.

 

Define 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 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:

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

 

Force 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 Function
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 -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 -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 -f [jobname] Allows the manual update of read-only fields
p4 label -f labelname Allows the modification date to be changed while editing the label specification
p4 label -f -d labelname Deletes the label, ignoring ownership
p4 user -f username Allows the update of all fields, ignoring ownership
p4 user -f -d username Deletes the user, ignoring ownership.

 

Firewalls and SSH

Secure shell (SSH) can forward arbitrary TCP/IP connections, which means you can make your Perforce client appear as though it's connecting from the firewall machine over the local network.

Suppose the Perforce server is on p4dbox.domain.com, and the firewall machine is called firewall.domain.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.domain.com:3710 firewall.domain.com
At this point, it may be necessary to provide a password to log into firewall.domain.com. Once the connection is established, ssh listens at port 4242 on the local machine, and forwards packets over its encrypted connection to firewall.domain.com; the firewall then forwards them by normal channels to port 3710 on p4dbox.domain.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.domain.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.domain.com:3710 firewall.domain.com sleep 9999999 &
on the remote system.

This tells ssh on firewall.domain.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.

 

Specify IP addresses in P4PORT

Under most circumstances, your Perforce server's P4PORT setting consists 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 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.

 

Run 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:

    p4dservice stream tcp nowait username /usr/local/bin/p4d p4d -i -rp4droot
and add the following to /etc/services:

    p4dservice nnnn/tcp
where:

  • p4dservice is the service name you choose for this Perforce server

  • /usr/local/bin is the directory holding your p4d binary

  • p4droot is the root directory (P4DROOT) to use for this Perforce server (for example, /usr/local/p4d)

  • username is the UNIX user name to use for running this Perforce server

  • nnnn is the port number for this Perforce server to use

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:

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

 

Trace flags

To turn on command tracing:

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

Trace output appears in logfile, and shows the date, time, username, IP address, and command for each request processed by the server. Before turning on logging, you should make sure that you have adequate disk space.

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

 

Move versioned files between hosts

If the architecture of the two machines is the same (e.g., SPARC/SPARC, x86/x86), the versioned files and database can be copied directly between the machines, and you only need to move the server root directory tree to the new machine. You can use tar, cp, xcopy.exe, or any other method. Copy everything in and under the P4ROOT directory - the db.* files (your database) as well as the depot subdirectories (your versioned files).

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

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

Although the backup, checkpoint, and subsequent p4 verify are not strictly necessary in this case, it's always good practice to perform these tasks before a migration.

If the internal data representation (big-endian vs. little-endian) convention differs between the two machines (e.g., 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 recreate the database on the new machine. The checkpoint is a text file which can be read by a Perforce server on any architecture.

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.

 

Change IP address of a server

If the IP address of the new machine is not the same as that of the old machine, you may need to update any IP-address-based protections in your protections table.

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.

 

Change hostname of a 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.

 

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 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 term "remote depot" is actually somewhat misleading. New Perforce customers tend to assume that if their users are geographically distributed, they need to set up separate Perforce installations (servers running p4d) and interconnect them with remote depot support.

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.

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

Users of remote depots encounter several restrictions:

  • 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 cannot be accessed using remote depots. Commands like p4 client only return specifications of entities defined in the local server's metadata.

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

 

Define new depots

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

 

Defining local depots

To define a new local depot (that is, 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:     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 if 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 than defining a local depot. Set the Type: to remote, provide the server's address in the Address: field, and set the Map: field to map into the remote depot namespace.

Example: Defining a remote depot

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

Michelle's first step towards accessing Colonel'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:     192.169.1.150:1666
    Map:         //depot/graphics/gui/...

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

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:

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

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

 

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.

You can list all depots known to the current Perforce server with the p4 depots command.

 

Delete depots

Delete depots with: p4 depot -d depotname.

To delete a depot, it must be empty; 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.

 

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:

read user remote * -//...
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 for users who will be working with more than one depot.