A distributed installation contains a Commit Server and one or more Edge Servers. For further detail on commit/edge server architecture, see the following
An Edge Server supports the full Perforce command set; however, there are a few differences in behavior which may affect applications.
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 traitlot (used by p4 attribute) numbers, Edge Server commands that create new changelists and trailots contact the commit server to issue the new changelist or traitlot. 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.
- Files of type +l are handled specially in a distributed installation. When +l filetypes 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 rpl.labels.global=1 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.
- 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 server.id 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 at 'text+C' and not RCS.
- 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.
p4 changes -s shelved file
Differences in Command Behavior
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:
p4 unlock -x
- Construct the change on the Edge Server
- Construct a shelf on the Edge Server (unless it was p4 submit -e)
- Run pre-submit checks on the Edge Server
- Run edge-submit triggers on the Edge Server
- If this is a revertunchanged submit, the reverts were performed, during the shelf construction in step 2
- Run edge-content triggers on the Edge Server
- Edge Server now asks Commit Server to submit the shelf
- 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
- Commit server asks the Edge Server to send the file contents, and waits until that completes
- Note that the Edge Server sends the file content from the shelved archives, not from the end user's workstation.
- Run pre-submit checks on the Commit Server
- Run change-submit triggers on the Commit Server
- Run change-content triggers on the Commit Server
- Commit the shelf on the Commit Server
- Run change-commit triggers on the Commit Server
- Run tempobj purging on the Commit Server
- Run ktext digest recalculation on the Commit Server
- 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.
- Edge Server performs client-state cleanup, according to the client and submit options
- If not "leave opened", delete working records
- Delete resolve records
- Refresh ktext files back to client
- Remove the pending changelist
- Submit is complete
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
These 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. Triggers
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.