= SDP Server Spec Naming Standard
Perforce Professional Services <consulting@perforce.com>
:revnumber: v2020.1
:revdate: 2020-12-07
:doctype: book
:icons: font
:toc:
:toclevels: 5
:sectnumlevels: 4
:xrefstyle: full

== 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: https://www.perforce.com/support/self-service-resources/documentation[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.

:sectnums:
== General Form

The general form of a server spec name is:

```
<HelixServerTag>_<ReplicaTypeTag>[<N>]_<SiteTag>

```

=== Helix Server Tags

The HelixServerTag_ is one of:

* `p4d`:  for a Helix Core server (including all https://www.perforce.com/perforce/doc.current/manuals/p4sag/Content/P4SAG/deployment-architecture.html[distributed architecture] usages such as master/replica/edge).
* `p4broker`: A https://www.perforce.com/perforce/doc.current/manuals/p4sag/Content/P4SAG/chapter.broker.html[Helix Broker]
* `p4p`: A https://www.perforce.com/perforce/doc.current/manuals/p4sag/Content/P4SAG/chapter.proxy.html[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.

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

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

=== 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
----
include::../Server/Unix/p4/common/config/SiteTags.cfg[]
----

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.

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

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

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

== The SDP `mkrep.sh` script

The SDP script `mkrep.sh` adheres to this standard.  For more information on creating replicas with this script, see https://swarm.workshop.perforce.com/projects/perforce-software-sdp/view/r20.1/doc/SDP_Guide.Unix.html#_using_mkrep_sh[using mkrep.sh] in the https://swarm.workshop.perforce.com/projects/perforce-software-sdp/view/dev/doc/SDP_Guide.Unix.html[SDP User Guide].