HMSSystemComponents.md #1

HMS v1.0 System Components

HMS v1.0 consists of the following components.

  • Command Line Interface - The /p4/common/bin/hms script.

  • Helix Toplogy Config File - A Helix Topology Configuration File that defines the global topology. It knows every machine that contains Helix topology components of any kind (p4d, p4broker, p4p, etc.), and knows about SDP instances in your environment.

  • Naming Conventions - HMS provides and requires a naming convention for ServerID values, server specs, and replication service users. See the Server Spec Naming Standard.

  • Broker Tidbit - A custom p4broker entry allows some hms commands to be called from any client machine, such as p4 hms status all. It looks like:

# Implement Helix Management System (hms) commands.
command: ^hms$
{
   action  = filter;
   execute = /p4/common/hms/scripts/broker_wrapper;
}

  • Bash 4.3 - Some HMS scripts use modern bash features such as associative arrays and regular expression comparisons. Scripts that require Bash 4.x+ have a safety check to verify that a current enough version of bash is used.

  • SSH Keys - The SSH keys for the perforce user must be maintained to allow ssh access without a password (as needed for automation) among all managed machines. SSH access must be bi-directional for any machines that are potential failover targets. It need only be enabled mono-directional, outbound from the central server, for other replica types.

  • HMS Server - The HMS Server is merely a dedicated SDP instance named "hms" (/p4/hms). The sdp_sync.sh scirpt is used to manage all SDP scripts and configuration files, including HMS-related files, on all Perforce server machines , be they simple proxy machines, replicas or edge servers, or master/commit servers. The sdp_sync.sh script encourages you to run a tight ship, taking advantage of Perforce to manage your production Perforce server machines. For example, it detects unversioned changes to backup and failover scripts that might otherwise go unnoticed and possibly foil failvoer. It tracks other details that can foil failover, such as incorrect crontab files for the perforce user on various machines.

    The job of the HMS Server is to keep the scripts and configuration files in sync during routine operation. The HMS Server is not required to execute a failover.

  • Swarm A Swarm instance associated with the hms SDP instance, for the usual things Swarm provides (web interface, code review, change notification via email, etc.).

# HMS v1.0 System Components

HMS v1.0 consists of the following components.

* **Command Line Interface** - The `/p4/common/bin/hms` script.

* **Helix Toplogy Config File** - A Helix Topology Configuration File that defines the global topology.  It knows every machine that contains Helix topology components of any kind (p4d, p4broker, p4p, etc.), and knows about SDP instances in your environment.

* **Naming Conventions** - HMS provides and requires a naming convention for ServerID values, server specs, and replication service users. See the [Server Spec Naming Standard](https://swarm.workshop.perforce.com/projects/perforce-software-sdp/view/main/doc/SDP_Guide.Unix.html#_server_spec_naming_standard).

* **Broker Tidbit** - A custom p4broker entry allows some hms commands to be called from any client machine, such as `p4 hms status all`.  It looks like:

```
# Implement Helix Management System (hms) commands.
command: ^hms$
{
   action  = filter;
   execute = /p4/common/hms/scripts/broker_wrapper;
}
```

* **Bash 4.3** - Some HMS scripts use modern bash features such as associative arrays and regular expression comparisons.  Scripts that require Bash 4.x+ have a safety check to verify that a current enough version of bash is used.

* **SSH Keys** - The SSH keys for the `perforce` user must be maintained to allow ssh access without a password (as needed for automation) among all managed machines.  SSH access must be bi-directional for any machines that are potential failover targets.  It need only be enabled mono-directional, outbound from the central server, for other replica types.

* **HMS Server** - The HMS Server is merely a dedicated SDP instance named "hms" (`/p4/hms`).  The `sdp_sync.sh` scirpt is used to manage all SDP scripts and configuration files, including HMS-related files, on all Perforce server machines , be they simple proxy machines, replicas or edge servers, or master/commit servers.  The `sdp_sync.sh` script encourages you to *run a tight ship*, taking advantage of Perforce to manage your production Perforce server machines.  For example, it detects unversioned changes to backup and failover scripts that might otherwise go unnoticed and possibly foil failvoer.  It tracks other details that can foil failover, such as incorrect crontab files for the `perforce` user on various machines.

 The job of the HMS Server is to keep the scripts and configuration files in sync during routine operation.  The HMS Server is not required to execute a failover.

* **Swarm** A Swarm instance associated with the hms SDP instance, for the usual things Swarm provides (web interface, code review, change notification via email, etc.).
# Change User Description Committed
#1 31797 C. Thomas Tyler p4 merge -b HMS_to_P4MS; p4 resolve -as; p4 submit
//guest/perforce_software/hms/dev/p4/common/site/hms/doc/HMSSystemComponents.md
#2 29677 C. Thomas Tyler Updated URL for Server Spec Naming Standard, which has been incorporated into
the SDP Guide documentation.

Replaced HTML <PRE> tag with Markdown format.
#1 29182 C. Thomas Tyler Moved HMS files from /p4/common/bin -> /p4/common/site/bin.
Moved HMS files from /p4/common/lib -> /p4/common/site/lib.
Removed dependency on SDP libs so that HMS can be deployed
with a wider variety of SDP versions.
//guest/perforce_software/hms/dev/p4/common/hms/doc/HMSSystemComponents.md
#3 26282 C. Thomas Tyler Formatting tweak.
#2 25533 C. Thomas Tyler Copied updated and new files from SDP into the new HMS "overlay" structure.

A 'p4 copy' was done in all cases, so files in this change match what they did in
the SDP.  Corresponding files in the SDP are to be deleted.  Some files will need
modification to adapt to the new HMS structure, e.g. the 'setup' tree.
#1 25531 C. Thomas Tyler Refactored to receive merge from SDP.

This structure emphasizes that HMS will be layered on the SDP. The tree is
now structured to make it clear where files appear in an as-deployed
configurtion, overlaid into the '/p4/common' structure of the SDP.

The test suite is outside this structure, as it will not be deployed (due
to dependencies on infratructure that won't likely appear in SDP production
deployments).
//guest/perforce_software/hms/dev/SystemComponents.md
#1 20309 C. Thomas Tyler Populate -o -b perforce_software-hms-dev.
//guest/perforce_software/hms/main/SystemComponents.md
#2 20080 C. Thomas Tyler Adjusted URLs.
#1 20079 C. Thomas Tyler Updated and refactored.