Perforce Public Knowledge Base - Edge Servers
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Edge Servers

« Go Back



A distributed installation contains a Commit Server and one or more Edge Servers. This article assumes you've read and are familiar with commit/edge server architecture as described in the Helix Versioning Engine Administrator Guide: Multi-Site Deployment.

An Edge Server supports the full Helix Versioning Engine command set; however, there are a few differences in behavior which may affect applications. This article describes these differences in behavior. 



Edge Server Behavior Differences

  • A pending change can be viewed on an Edge Server other than the one where the change was created. In that case, the pending change will not display a list of open files; the open files are shown only on the owning server. A pending changelist can be updated or deleted only on the server where the change was created.

  • To ensure globally unique changelist and trait lot (used by p4 attribute) numbers, Edge Server commands that create new changelists and trait lots contact the commit server to issue the new changelist or trait lot. To ensure globally unique client and label names, Edge Server commands that create new clients and labels contact the commit server to issue the new client or label.

  • Exclusively locked file types (+l) are handled specially in a distributed installation. When +l file types are opened, the Edge Server contacts the Commit Server to ensure that the file is not locked on another Edge Server. The +l filetype performs exclusive file locking with the same semantics as in a non-Distributed Perforce installation.

  • By default, when an Edge Server submit fails, files in the change are globally locked. If this behavior isn't desired, consider setting the submit.unlocklocked configurable to 1 so when submit fails files are not left globally locked.

  • By default, labels are bound to the Edge Server on which they are created; the -g flag indicates the label is to be defined globally on all servers in the installation. Configuring reverses the default and causes the flag to have the opposite meaning. Both Edge Servers and Commit Servers can use autoreload labels providing an unload depot has been defined.

  • Client workspaces created on an Edge Server are bound to that Edge Server with the ServerID option in the client workspace spec; this is automatically added as the client workspace spec is saved on the Edge Server.

  • When moving your workspace from one server to another, using sync -k and reconcile makes it easy to migrate without needing to reload your work. An alternate mechanism is to unload your workspace on the old server and use reload -p to reload it onto the new server. In either case, shelves created by the workspace remain on the server where they were created. The unload/reload mechanism can also be used to move a locally-bound label from one Edge Server to another.

  • A spec depot on an Edge Server contains all the contents of the spec depot on the Commit Server. Additionally, the Edge Server spec depot contains entries for clients and labels bound to that Edge Server. Consider using a Typemap definition such as text+CS4 for client and label spec depot entries, or using a SpecMap field on the spec depot definition to ensure that the Edge Server spec depot does not grow excessively large.

  • An unload depot on an Edge Server contains all the contents of the unload depot on the Commit Server. Additionally, the Edge Server unload depot contains entries for clients and labels that were unloaded on that edge server.

  • Shelved files behave differently in a distributed configuration. By default, a shelf is accessible only on the Edge Server where it was created, unless it is promoted (see the discussion of the shelve command below).

  • When backing up your Edge Server(s), ensure that you checkpoint all database tables and retain rotated journals between checkpoints. Also, ensure that you back up any shelved file content, unloaded clients and labels, and spec depot entries for clients and labels that have been created on this Edge Server, as that data is local to this Edge Server and not contained in the backups of your Commit Server. Also backup the file and recover that as well when you recover an Edge Server.

  • Most commonly-used commands are executed directly on this Edge Server and are unaffected by resource constraints on other servers in your installation. However, there are certain performance implications of a distributed installation that you should anticipate:

    • ​Files using the RCS storage format undergo multiple file format conversions during submit. Use text+C or text+F storage formats instead to avoid this penalty, or consider the use of the lbr.autocompress configurable which makes it so files of type text are stored as individual gzipped archives (text+C) and not RCS text deltas for all revisions in a single archive file.

    • The submit command is slower than in a non-distributed installation, since the changelist must be copied from the Edge Server to the Commit Server during submit processing. If you are creating a new branch, use the populate command instead to avoid this overhead.

    • Updates to workspace and label definitions, requests for new change numbers, and opening or reverting +l files require messages to be sent to the Commit server.

    • Background pull threads in the Edge Server may contend for resources with commands run by Edge Server users.


Differences in Command Behavior

p4 changes -s shelved file:

Searching for shelves affecting particular files can be done only on the Edge Server where the shelf was created, or on the Commit Server if the shelf was promoted.

p4 client, p4 clients -a -s:

A client workspace is bound to its Edge Server when it is created, and may not be used on other Edge Servers. The p4 clients command displays only those clients bound to this Edge Server; use the -a flag to display the complete list of clients, or the -s serverID flag to display the list of clients bound to a specific Edge Server.

p4 describe, p4 change:

The files associated with a pending change are visible only on the Edge Server where the change was created.

p4 label, p4 labels -a -s:

A label is present only on the Edge Server where it was created. The p4 labels command displays only those labels bound to this Edge Server; use the -a flag to display the complete list of labels, or the -s serverID flag to display labels of a specific Edge Server. Labels created on the Commit Server are global, and are visible on all servers in the distributed installation.

p4 label -g, p4 labelsync -g, p4 tag -g:

The -g flag specifies that the label, labelsync, or tag command should execute on the Commit Server to create or update a globally-visible label; otherwise the label is present only on this Edge Server.

p4 labels file[revrange]:

When a file specification is provided, the p4 labels command displays the matching labels, but only shows labels bound to this Edge Server. The file specification argument is not allowed if the -a or -s flags are provided.

p4 lock, p4 lock -g -c, p4 unlock:

The lock and unlock commands against and Edge Server only prevent submissions from other clients on this Edge Server. If issued from a workspace connected to the Commit Server, the lock and unlock commands prevent submissions to the locked files from all Edge Server workspaces as well as from other workspaces on the Commit Server. The -g flag is used to lock the files locally and globally at the Commit Server in a distributed environment. It may only be run from an Edge Server, and must be used with the -c flag with a numbered changelist. These locks are removed by the unlock or any submit command for that change.

p4 logger:

In a distributed installation, p4 logger commands should be issued to the Commit Server, not to an Edge Server.

p4 obliterate:

The obliterate command removes submitted revision data from the Commit Server, and also removes any related client data for clients resident on the Commit Server. When the file removal operations are replicated to an Edge Server, that Edge Server automatically reverts any open changes to those files for clients resident on that Edge Server. Edge Server clients may still list the obliterated file(s) in the output of p4 have; the file(s) will be removed from their have list the next time that client issues a p4 sync.

p4 opened -a:

Displays only those files opened by other workspaces on this Edge Server; files opened on other Edge Servers do not appear.

p4 opened -x:

Displays information about exclusively locked files.

p4 reload -p:

Allows an unloaded client or label to be reloaded on a different server. Note that any shelves which were created by the client remain on the server where they were created.

p4 shelve, p4 unshelve:

A shelf is present only on the Edge Server where it is created, and can only be unshelved by workspaces on that Edge Server. A shelf can be promoted by specifying the -p flag; this causes the shelf data to be redundantly stored on the Commit Server as well as on this Edge Server. A promoted shelf is accessible by users on other Edge Servers, although there is a performance penalty as the shelf data must be retrieved on demand when it is referenced. Although it is accessible from other Edge Servers, the shelf can only be submitted from the Edge Server on which it was created. On an Edge Server which is running with lbr.replication=shared, all new shelves are automatically promoted without needing -p. If a workspace has promoted shelves, those shelves must be deleted prior to deleting, unloading, or migrating that workspace to another server. The dm.shelve.promote server configurable can be set to 1 to automatically promote shelved changes from an Edge Server.

p4 submit:

An Edge Server implements the p4 submit command. The submit command is implemented in a multi-step fashion. Behind the scenes, the Edge Server and the Commit Server cooperate, and the following occurs:

  1. Construct the change on the Edge Server.

  2. Construct a shelf on the Edge Server (unless it was p4 submit -e).

  3. Run pre-submit checks on the Edge Server.

  4. Run edge-submit triggers on the Edge Server.

  5. If this is a revertunchanged submit, the reverts were performed, during the shelf construction in step 2.

  6. Run edge-content triggers on the Edge Server.

  7. Edge Server now asks Commit Server to submit the shelf:

    1. Commit Server asks the Edge Server to send the shelf metadata, and waits until that completes. Shelf metadata comprises:

      • revsh data
      • workingx data
      • resolvex data
      • change data
      • description data
      • fix data
    2. Commit server asks the Edge Server to send the file contents, and waits until that completes.

      Note: The Edge Server sends the file content from the shelved archives, not from the end user's workstation.

    3. Run pre-submit checks on the Commit Server.

    4. Run change-submit triggers on the Commit Server.

    5. Run change-content triggers on the Commit Server.

    6. Commit the shelf on the Commit Server.

    7. Run change-commit triggers on the Commit Server.

    8. Run tempobj purging on the Commit Server.

    9. Run ktext digest recalculation on the Commit Server.

  8. Edge Server does a journalWait to wait for the metadata to be replicated back to the Edge Server. The submitting client will block on the submit until the journalWait completes.

  9. Edge Server performs client-state cleanup, according to the client and submit options

    1. If not "leave opened", delete working records.

    2. Delete resolve records.

    3. Refresh ktext files back to client.

    4. Remove the pending changelist.

  10. Submit is complete.

p4 unlock -x:

Releases exclusive locks which have become orphaned due to network outages between the Edge Server and the Commit Server.

p4 unsubmit, p4 resubmit:

These commands are not available on an Edge Server.

p4 user -i -f:

Automatic creation of new user specs is disabled on Edge Servers. To create a new user, the administrator should run p4 user -f.

p4 archive, p4 attribute -f, p4 labelsync -g, p4 obliterate p4 populate p4 restore, p4 retype, p4 snap, p4 tag -g:

When one of these commands is issued to an Edge Server, the command is forwarded to the Commit Server for processing. In this case, specify any arguments to the command using depot syntax, not client syntax nor local syntax. In order to use client or local syntax for these commands, you must issue the command directly to the Commit Server (and use a workspace bound to the Commit Server).

p4 attribute -p (without -f), p4 edit, p4 delete, p4 integrate, p4 copy p4 reconcile, p4 resolve, p4shelve, p4 unshelve, p4 submit:

If propagating attributes are not in use, the above commands work against edge servers as they normally do. See p4 attribute for further details on how attributes, and propagating attributes are created. When propagating attributes have been created using p4 attribute -p, the above commands are not supported when run from an Edge Server with files which contain propagating attributes. These commands may be used with propagating< attributes only from a Commit Server.

Spec Depot:

The spec depot may have different contents on each Edge Server. Clients and labels bound to an Edge Server are recorded in the spec depot on that Edge Server only. The depot -d command for the spec depot does not verify that the Edge Server spec depots are empty.


The submit command on the Edge Server will run the edge-submit and edge-content triggers, if defined, prior to transferring the changelist to the Commit Server for final submission. The submit command on the Commit Server will run the standard trigger types; however, if the change was submitted from an Edge Server, the change and describe commands must not be used in the trigger. The %serverid% variable in the trigger command should be used for trigger definitions which need to detect which server is running the trigger.

Unload Depot:

The unload depot may have different contents on each Edge Server. Clients and labels bound to an Edge Server are unloaded into the unload depot on that Edge Server. Specify the -s or -a flag to the p4 clients -U and p4 labels -U commands on the Edge Server to view unloaded clients or labels for another Edge Server. Be sure to include the unload depot as part of your Edge Server backups. Since the Commit Server does not verify that the unload depot is empty on every Edge Server, you must specify depot -d -f in order to delete the unload depot from the Commit Server.

Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255