USAGE for mkrep.sh v2.6.0:
mkrep.sh -i <SDP_Instance> -t <Type> -s <Site_Tag> -r <Replica_Host> [-f <From_ServerID>] [-p] [-L <log>] [-v<n>] [-n] [-D]
or
mkrep.sh [-h|-man|-V]
DESCRIPTION:
This script simplifies the task of creating Helix Core replicas and
edge servers, and helps ensure they are setup with best practices.
This script does all the metadata configuration to be executed on the
master server that must be baked into a seed checkpoint for creating
the replica/edge. It also provides enough information to create,
transfer, and load seed checkpoints into the replica/edge. This
essentially captures the planning for a new replica, and can be
done before the physical infratructure (hardware and storage) is
ready.
Before using this script, a set of geograpic site tags must be defined.
See the FILES: below for details on a site tags.
This script adheres to the these SDP Standards:
* Server Spec Naming Standard: https://swarm.workshop.perforce.com/view/guest/perforce_software/sdp/main/doc/ServerSpecNamingStandard.html
* Journal Prefix Standard: https://swarm.workshop.perforce.com/view/guest/perforce_software/sdp/main/doc/JournalPrefixStandard.html
This script does the following to help create a replica or edge server:
* Generates the server spec for the the replica.
* Generates a server spec for master server (if needed).
* Sets configurables ('p4 configure' settings) for replication.
* Selects the correct 'Services' based on replica type.
* Creates service user for the replica, and sets a password.
* Creates service user for the master (if needed), and sets a password.
* Addes newly created service users to the group 'ServiceUsers'.
* Verifies the group ServiceUsers is granted super access in the
protections table (and with the '-p', updations Protections).
After these steps are completed, detailed instructions are presented
to the user through the remaining steps needed to complete the
deployment of the replica. This starts with creating a new
checkpoint to capture all the metadata changes made by this
script.
SERVICE USERS:
Service users created by this type are always of type 'service',
and so will not consume a licensed seat.
Service users also have an 'AuthMethod' of 'perforce' (not
'ldap') as is required by 'p4d' for 'service' users. Passwords
set for service users are long 32 character random strings
that are not stored, as they are never needed. Login tickets for
service users are generated using: p4login -service -v
OPTIONS:
-i <SDP_Instance>
Specify the SDP Instance.
-t <Type>
Specify the replica type tag. The type corresponds to the 'Type:' and
'Services:' field of the server spec, which describes the type of services
offered by a given replica.
Valid values are:
* ha: High Availability standby replica, for 'p4 failover' (P4D 2018.2+)
* ham: High Availability metadata-only mandatory standby replica, for 'p4 failover' (P4D 2018.2+)
* ro: Read-Only standby replica.
* rom: Read-Only standby replica, Metadata only.
* fr: Forwarding Replica (Unfiltered).
* fs: Forwarding Standby (Unfiltered).
* frm: Forwarding Replica (Unfiltered, Metadata only).
* fsm: Forwarding Standby (Unfiltered, Metadata only).
* ffr: Filtered Forwarding Replica. Not a valid failover target.
* edge: Edge Server. Filtered by definition.
Replicas with 'standby' are always unfiltered, and use the 'journalcopy'
method of replication, which copies a byte-for-byte verbatim journal file
rather than one that is merely logically equivalent.
The tag has several purposes:
1. Short Hand. Each tag represents a combination of 'Type:' and fully
qualified 'Services:' values used in server specs.
2. Distillation. Only the most useful Type/Services combinations have a
shorthand form.
3. For forwarding replicas, the name includes the critical distinction of
whether any replication filtering is used; as filtering of any kind disqualifies
a replica from being a potential failover target. (No such distinction is
needed for edge servers, which are filtered by definition).
-s <Site_Tag>
Specify a geographic site tag indicating the location and/or data center where
the replica will physically be located. Valid site tags are defined in the site
tags file:
/p4/common/config/SiteTags.cfg
-r <Replica_Host>
Specify the target replica host.
-f <From_ServerID>
Specify ServerID of the P4TARGET server from which we are replicating.
This is used to populate the 'ReplicatingFrom' field of the server
spec. The value must be a valid ServerID.
By default, this is determined dynamically by checking the ServerID
of the master server. This option should be used if the target is
something other than the master. For example, to create an HA replica
of an edge server, you might specify something like '-f p4d_edge_syd'.
-p This script performs a check to ensure that the Protections table grants
super access to the group ServiceUsers.
By default, an error is displayed if the check fails, i.e. if super user
access for the group ServiceUsers cannot be verified. This is
because, by default, we want to avoid making changes to the Protections
table. Some sites have local policies or custom automation that requires
site-specific procedures to update the Protections table.
If '-p' is specified, an attempt is made to append the Protections table
an entry like:
super group ServiceUsers * //...
-v<n> Set verbosity 1-5 (-v1 = quiet, -v5 = highest).
-L <log>
Specify the path to a log file, or the special value 'off' to disable
logging. By default, all output (stdout and stderr) goes in the logs
directory referenced by $LOGS environment variable, in a file named
mkrep.<timestamp>.log
NOTE: This script is self-logging. That is, output displayed on the screen
is simultaneously captured in the log file. Do not run this script with
redirection operators like '> log' or '2>&1', and do not use 'tee.'
-n No-Op. Prints commands instead of running them.
-D Set extreme debugging verbosity.
HELP OPTIONS:
-h Display short help message
-man Display man-style help message
-V Dispay version info for this script and its libraries.
FILES:
This Site Tags file defines the list of valid geographic site tags:
/p4/common/config/SiteTags.cfg
The contains one-line entries of the form:
<tag>: <description>
where <tag> is a short alphanumeric tag name for a geographic location,
data center, or other useful distinction. This tag is incorporated into
the ServerID of replicas or edge servers created by this script. Tag
names should be kept short, ideally no more than about 5 characters in
length.
The <description> is a one-line text description of what the tag
refers to, which may contain spaces and ASCII punctuation.
Blank lines and lines starting with a '#' are considered comments
and are ignored.
REPLICA SERVER MACHINE SETUP:
The replica/edge server machine must be have the SDP structure installed,
either using the mkdirs.sh script included in the SDP, or the Helix
Installer for 'green field' installations.
When setting up an edge server, a replica of an edge server, or filtered
replica, confirm that the JournaPrefix Standard (see URL above) structure
has the separate checkpoints folder as identified in the 'Second Form' in
the standard. A baseline SDP structure can typically be extended by running
commands like like these samples (assuming a ServerID of p4d_edge_syd or
p4d_ha_edge_syd):
mkdir /hxdepots/p4/1/checkpoints.edge_syd
cd /p4/1
ln -s /hxdepots/p4/1/checkpoints.edge_syd
EXAMPLES:
EXAMPLE 1 - Set up a High Availability (HA) Replica of the master.
Add an HA replica to instance 1 to run on host bos-helix-02:
mkrep.sh -i 1 -t ha -s bos -r bos-helix-02
EXAMPLE 2 - Add an Edge Server to the topology.
Add an Edge server to instance acme to run on host syd-helix-04:
mkrep.sh -i acme -t edge -s syd -r syd-helix-04
EXAMPLE 3 - Setup an HA replica of an edge server.
Add a HA replica of the edge server to instance acme to run on host syd-helix-05:
mkrep.sh -i acme -t ha -f p4d_edge_syd -s syd -r syd-helix-05