Preface
This document describes the SDP Server Spec Naming Standard for Perforce Helix Core.
With this naming convention, server spec names (aka ServerID) provide info at a glance, such as where the server is physically located, whether it is filtered, and hints about its intended usage and capabilities.
This guide assumes some familiarity with Perforce Helix and does not duplicate the basic information in the Perforce Helix product. This document only relates to the Server Deployment Package (SDP). All other Helix Core documentation can be found here: Perforce Support Documentation.
Please Give Us Feedback
Perforce welcomes feedback from our users. Please send any suggestions for improving this document or the SDP to consulting@perforce.com.
1. General Form
The general form of a server spec name is:
<HelixServerTag>_<ReplicaTypeTag>[<N>]_<SiteTag>
1.1. Helix Server Tags
The HelixServerTag_ is one of:
-
p4d
: for a Helix Core server (including all distributed architecture usages such as master/replica/edge). -
p4broker
: A Helix Broker -
p4p
: A Helix Proxy -
gconn
: Helix4Git (H4G) Connector -
swarm
: Helix Swarm
As a special case, the HelixServerTag is omitted for the ServerID of the master server spec.
1.2. Replica Type Tags
The ReplicaType is one of:
-
master.<instance>
: The single master-commit server for a given SDP instance. SDP instance names are included in the ServerID for the master, as they intended to be unique within an enterprise. They must be unique to enable certain cross-instance sharing workflows, e.g. using remote depots and Helix native DVCS features. -
ha
: High Availability. This indicates a replica that was specifically intended for HA purposes and for use with thep4 failover
command. It further implies the following:-
The Services field value is
standby
. -
The
rpl.journalcopy.location=1
configurable is set, optimized for SDP deployment. -
The replica is not filtered in any way: No usage of the
-T
flag top4 pull
in the replicas startup.N configurables, and no usage of*DataFilter
fields in the server spec. -
Versioned files are replicated (with an
lbr.replication
value ofreadonly
). -
An HA replica is assumed to be geographically near its P4TARGET server, which can be a master server or an edge server.
-
It may or may not use the
mandatory
option in the server spec. Theha
tag does not indicate whether themandatory
option is used (as this is more transient thing not suitable for baking into a server spec naming standard).
-
-
ham
: Aham
replica is the same as anha
replica except it does not replicate versioned files. Thus is a metadata-only replica that shares versioned files with its P4TARGET server (master or edge) with anlbr.replication
value ofshared
. -
fr
: Forwarding Replica (unfiltered) that replicates versioned files. -
frm
: Forwarding replica (unfiltered) that shares versioned files with its target server rather than replicating them. -
fs
: Forwarding Standby (unfiltered) that replicates versioned files. This is the same as anha
server, except that it is not necessarily expected to be physically near its P4TARGET server. This could be suited for Disaster Recovery (DR) purposes. -
fsm
: Forwarding standby (unfiltered) that shares versioned files with its target server rather than replicating them. This is the same as aham
, except that it is not necessarily expected to be physically near its P4TARGET server. -
ffr
: Filtered Forwarding Replica. This replica uses some of filtering, such as usage of*DataFilter
fields of the server spec or-T
flag top4 pull
in the replicasstartup.<N>
configurables. Filtered replicas are not viable failover targets, as the filtered data would be lost. -
ro
- Read Only replica (unfiltered), replicating versioned files). -
rom
- Read Only metadata-only replica (unfiltered, sharing versioned files). -
edge
- Edge servers. (As edge servers are filtered by their nature, they are not valid failover targets).
1.2.1. Replication Notes
If a replica does not need to be filtered, we recommend using journalcopy
replication, i.e. using a replica with a Services:
field value of standby
or forwarding-standby
. Only use non-journalcopy replication when using filtered replicas (and edge servers where there is no choice).
Some general tips:
-
The
ha
,ham
replicas are preferred for High Availability (HA) usage. -
The
fs
andro
replicas are preferred for Disaster Recovery (DR) usage. -
Since DR implies the replica is far from its master, replication of archives (rather than sharing e.g. via NFS) may not be practical, and so
rom
replicas don’t have common use cases. -
The
fr
type replica is obsolete, and should be replaced withfs
(usingjournalcopy
replication).
1.3. Site Tags
A <SiteTag>
looks something like these samples:
syd: Sydney, Australia
bos: Boston, MA, USA
blr: Bangalore, India
Note that in the SDP, Site Tags are defined in the file /p4/common/config/SiteTags.cfg
. S sample file is:
# Valid Geographic site tags. # Each is intended to indciate a geography, and optionally a specific Data # Center (or Computer Room, or Computer Closet) within a given geographic # location. # # The format is: # Name:Description # The Name must be alphanumeric only. The Description may contain spaces. # Lines starting with # and blank lines are ignored. bej: Beijing, China bos: Boston, MA, USA blr: Bangalore, India chi: Chicago greater metro area cni: Chennai, India pune: Pune, India lv: Las Vegas, NV, USA mlb: Melbourne, Australia syd: Sydney, Australia
The site tag needs to distinguish the data centers used by a single enterprise, and so generally short tag names are appropriate.
Each site tag may be understood to be a true data center (Tier 1, Tier 2, etc.), a computer room, computer closet, or reserved space under a developer’s desk. In some cases organizations will already have their own familiar site tags to refer to different sites or data centers; these can be used.
In public cloud deployments, the public cloud provider’s region names can be used (e.g. us-east-1
), or an internal short form (e.g. awsuse1
) for the AWS data center in Northern Virginia, USA.
As a special case, the <SitgTag>`
is omitted for the master server spec.
2. Examples
Here are some sample server spec names based on this convention:
-
master.1
: A master server for SDP instance 1. -
p4d_ha_chi
: A High Availability (HA) server, suitable for use withp4 failover
, located in Chicago, IL. -
p4d_ha2_chi
: A second High Availability server, suitable for use withp4 failover
, located in Chicago, IL. -
p4d_ffr_pune
: A filtered forwarding replica in Pune, India. -
p4d_edge_blr
: An edge server located in Bangalore, India. -
p4d_ha_edge_blr
: An HA server with P4TARGET pointing to the edge server in Bangalore, India. -
p4d_edge3_awsnva
: A 3rd edge server in AWS data center in the us-east-1 (Northern Virginia) region.
2.1. Implications of Replication Filtering
Replicas that are filtered in any way are not viable candidate servers to failover to, because any filtered data would be lost.
2.2. Other Replica Types
The naming convention intentionally does not account for all possible server specs available with p4d. The standard accounts only for the distilled list of server spec types supported by the SDP mkrep.sh
script, which are the most useful and commonly used ones.
3. The SDP mkrep.sh
script
The SDP script mkrep.sh
adheres to this standard. For more information on creating replicas with this script, see using mkrep.sh in the SDP User Guide.