Preface
This document describes the SDP Standard for the journalPrefix configurable in Perforce Helix Core.
This is related to the SDP Server Spec Naming Standard.
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. Overview
The Perforce Helix configurable journalPrefix
determines where the active journal is rotated to when it becomes a numbered journal file during the journal rotation process. It also defines where checkpionts are created.
In the SDP structure, the journalPrefix is set so that numbered journals and checkpoints land on the /hxdepots
volume. This volume contains critical digital assets that should be reliably backed up should sufficient storage for large digital assets.
2. SDP Scripts that set journalPrefix
The SDP configure_new_server.sh
, which applies SDP standards to fresh new p4d
servers, sets the journalPrefix
for the master server according to this standard.
The SDP mkrep.sh
script, which creates new replicas, sets `journalPrefix for replicas according to this standard.
3. First Form of journalPrefix
Value
The first form of the journalPrefix
value applies to the master servers’s metadata set. This value is of this form, where N
is replaced with the SDP instance name:
/p4/N/checkpoints/p4_N
If the SDP instance name is the default 1
, then files with a p4_1
prefix would be stored in the /p4/1/checkpoints
directory on the filesytem. Journal files in that directory would have names like p4_1.320.jnl
and checkpoints would have names like p4_1.320.ckp.gz
.
This journalPrefix
value and the corresponding /p4/1/checkpoints
directory should be used for the master server. It should also be used for any replica that is a valid failover target for the master server. This includes all completely unfiltered replicas of the master, such as standby
and forwarding-standby
replicas with a P4TARGET
value referencing the master server.
A standby replica, also referred to as a journalcopy replica due to the underlying replication mechaninsm, cannot be filtered. It is commonly deployed for High Availability (HA) and/or Disaster Recovery (DR) purposes.
|
3.1. Detail on "Completely Unfitered"
A "completely unfiltered" replica is one in which:
-
None of the
*DataFilter
fields in the replica’s server spec are used -
The
p4 pull
command configured to pull metadata from the the replica’sP4TARGET
server, as defined in the replica’sstartup.N
configurable, does not use filtering options such as-T
. -
The replica is not an Edge server (i.e. one with a
Services
value in the server spec ofedge-server
.) Edge servers are filtered by their vary nature, as they exclude various database tables from being replicated. -
The replica’s seed checkpoint was created without the
-P ServerID
flag top4d
. The-P
flag is used when creating seed checkpoints for filtered replicas and edge servers. -
The replicas
P4TARGET
server references something other than the master server, such as an edge server.
4. Second Form of journalPrefix
Value
A second form of the journalPrefix
is used when the replica is filtered, including edge servers. The second form of the journalPrefix
value incorporates a shortened form of the ServerID to indicate that the data set is specific to that ServerID. Because the metadata differs from the master, checkpoints for edge servers and filtered replicas are stored in a different directory, and use a prefix that identifies them as separate and divergent from the master’s data set.
Filtered replicas are a strict subset of the master server’s metadata. Edge servers filter some database tables from the master, but also have their own indepdent metadata (mainly workspace metadata) that varies from the master server and is potentially larger than the master’s data set for some tables. |
The "shortened form" of the ServerID removes the p4d_
prefix (per the SDP Server Spec Naming Standard. So, for example an edge server with a ServerID` of p4d_edge_uk
would use just the edge_uk
portion of the ServerID in the journalPrefix
, which would look like:
/p4/N/checkpoints.edge_uk/p4_N.edge_uk
If the SDP instance name is the default 1
, then files with a p4_1.edge_uk
prefix would be stored in the /p4/1/checkpoints.edge_uk
directory on the filesytem. Journal files in that directory would have names like p4_1.edge_uk.320.jnl
and checkpoints would have names like p4_1.edge_uk.320.ckp.gz
.
5. Scripts for Maintaining the offline_db
The SDP has two scripts for the offline_db
, daily_checkpoint.sh
and sync_replica.sh
.
The daily_checkpoint.sh
is used on the master server. When run on the master server, this script rotates the active journal to a numbered journal file, and then maintains the master’s offline_db
using the numbered journal file immediately after it is rotated.
The daily_checkpoint.sh
is also used on edge servers and filtered replicas. When run on edge servers and filtered replicas, this script maintains the replica’s offline_db
in a manner similar to the master, except that the journal rotation is skipped (as that can be done only on the master).
The SDP sync_replica.sh
script is intended to be deployed on unfiltered replicas of the master. It maintains the offline_db
by copying (via rsync) the checkpoints from the master, and then replays those checkpoints to the local offline_db
. This keeps the offline_db
of the replica current, which is good to have should the replica ever need to take over for the master.
INFO: For HA/DR and any purpose where replicas are not filtered, we promote that replicas of type standby
and forwarding-standby
displace replicas of type replica
and forwarding-replica
.
6. SDP Structure and journalPrefix
On every server machine with the SDP structure where a p4d
service runs (excluding broker-only and proxy-only hosts), a structure like the following should exist for each instance:
-
A
/hxdepots/p4/N/checkpoints
directory -
In
/p4/N
, and symlinkcheckpionts
that links to/hxdepots/p4/N/checkpoints
, such that it can be referred to as/p4/N/checkpoints
.
In addtion, edge servers and filtered replicas will also have a structure like the following for each instance that runs an edge server or filtered replica:
-
A
/hxdepots/p4/N/checkpoints.ShortServerID
directory -
In
/p4/N
, and symlinkcheckpionts.ShortServerID
that links to/hxdepots/p4/N/checkpoints.ShortServerID
, such that it can be referred to as/p4/N/checkpoints.ShortServerID
.
The SDP mkdirs.sh
script, which sets up the initial SDP structure, initializes this structure on initial install.
7. Replicas of Edge Servers
As edge servers have unique data, they are commonly deployed with their own standby
replica with a P4TARGET
value referencing a given edge server rather than the master. This enables faster recovery option for the edge server.
As a special case, a standby
replica of an edge server should have the same journalPrefix
value as the edge server it targets. Thus, the ServerID baked into the journalPrefix of a replica of an edge is the ServerID of the target edge server, not the replica.
So for example, an edge server with a ServerID of p4d_edge_uk
has a standby
replica with a ServerID of p4d_ha_edge_uk
. The journalPrefix of that edge should be the same as the edge server it targets, e.g.
/p4/1/checkpoints.edge_uk/p4_1.edge_uk
8. Goals of this Standard
Some design of goals this standard:
-
Make it so the
/p4/N/checkpoints
folder is reserved to mean checkpoints created from the master server’s full metadata set. -
Make the
/p4/N/checkpoints
folder be safe to rsync from the master to any machine in the topology (as may be needed in certain recovery situations for replicas and edge servers). -
Make it so the SDP
/hxdepots
volume can be NFS-mounted across multple SDP machines safely, such that two or more edge servers (or filtered replicas) could share versioned files, while writeing to separate checkpoints directories on a per-ServerID basis. -
Support all replication uses cases, including support for 'Workspace Servers', a name referring to a set of edge servers deployed in in the same location, typically sharing
/hxdepots
via NFS. Use of Workspace Servers can be used to scale Helix Core horizontally for massive user bases (typically several thousand users).