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:

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 the p4 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 to p4 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 of readonly).

    • 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. The ha tag does not indicate whether the mandatory option is used (as this is more transient thing not suitable for baking into a server spec naming standard).

  • ham: A ham replica is the same as an ha 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 an lbr.replication value of shared.

  • 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 an ha 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 a ham, 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 to p4 pull in the replicas startup.<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 and ro 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 with fs (using journalcopy 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:

Example/Format
# 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 with p4 failover, located in Chicago, IL.

  • p4d_ha2_chi: A second High Availability server, suitable for use with p4 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.