Using HPCC4J with HPCC on Bare Metal

Configuring Rowservice Signing Keys in HPCC Systems

This guide provides steps to generate and configure rowservice signing keys to allow for secure communication between an HPCC Systems cluster and external clients. These signing keys are required for authentication and secure reading and writing of data between HPCC4j clients and HPCC Systems clusters and must be properly configured on target HPCC Systems clusters.

Step 1: Generate Signing Keys

If signing keys do not already exist, they must be generated and placed in a directory that is accessible to the hpcc user. The default directory /home/hpcc/certificate will be used in the example configuration below, but on multi-node clusters it likely makes sense to change this directory.

Generate Signing Keys

sudo /opt/HPCCSystems/etc/init.d/setupPKI

This command generates a pair of signing keys:

• Private Key: /home/hpcc/certificate/key.pem
• Public Key: /home/hpcc/certificate/public.key.pem

Step 2: Configure Signing Keys in the HPCC Systems Environment

Once the keys are generated, they need to be referenced in the HPCC Systems environment.xml configuration file.

Add Keys Configuration Section

Modify the environment.xml file located at /etc/HPCCSystems/environment.xml to include the following under the <EnvSettings> node:

<EnvSettings>
<Keys>
   <ClusterGroup keyPairName="mythor" name="thorcluster_1"/>
   <ClusterGroup keyPairName="mythor" name="thorcluster_2"/>
   <KeyPair name="mythor" privateKey="/home/hpcc/certificate/key.pem" publicKey="/home/hpcc/certificate/public.key.pem"/>
</Keys>

Explanation:

• <ClusterGroup> entries define which Thor clusters will use the specified key pair.
• <KeyPair> defines the key pair used for signing and must reference the correct file paths.
• Each Thor cluster in the HPCC system must have an associated <ClusterGroup> entry specifying the keyPairName.

Step 3: Synchronize Configuration and Keys Across the Cluster

After updating the configuration, ensure that all nodes within the cluster have the updated environment.xml file and the necessary key files.

Sync environment.xml to All Nodes

scp /etc/HPCCSystems/environment.xml hpccadmin@nodeX:/etc/HPCCSystems/environment.xml

Repeat this step for each node in the HPCC cluster.

Sync Signing Keys Across the Cluster

scp /home/hpcc/certificate/key.pem hpccadmin@nodeX:/home/hpcc/certificate/key.pem
scp /home/hpcc/certificate/public.key.pem hpccadmin@nodeX:/home/hpcc/certificate/public.key.pem

Step 4: Verify Key Synchronization

To ensure that the signing keys have been correctly synchronized across all nodes, compute the MD5 hash of the key files and compare them.

Check MD5 Hash of Keys

Run the following command on each node:

md5sum /home/hpcc/certificate/key.pem /home/hpcc/certificate/public.key.pem

Compare the output across all nodes. If the MD5 hash values are identical, the keys have been correctly synchronized. If there are discrepancies, re-sync the keys and verify again.

Step 5: Restart HPCC Rowservice and ESP

Once the configuration and keys are updated across the cluster, the ESP and Dafilesrv services need to be restarted for these changes to take affect.

sudo /etc/init.d/dafilesrv restart
sudo /etc/init.d/hpcc-init -c myesp restart

Testing Configuration

The above configuration can be tested by using the FileUtility in the HPCC4j dfsclient library to attempt to read a file from the configured HPCC Systems cluster. The latest copy of the dfsclient jar can be found here: https://mvnrepository.com/artifact/org.hpccsystems/dfsclient

The following command will attempt to read 'example::hpccsystems::file' from 'http://your_cluster:8010', the should be updated to an already existing file on your target cluster and the url of your HPCC Systems ESP respectively.

java -Dotel.service.name=DFSClient.FileUtility \
     -cp dfsclient-9.10.1-0-jar-with-dependencies.jar \
     org.hpccsystems.dfs.client.FileUtility \
     -read_test example::hpccsystems::file \
     -url http://your_cluster:8010

If the keys have been successfully configured, you will see a similar result to the following indicating the example file was successfully read.

[{
  "bytesWritten": 0,
  "Read Bandwidth": "6.70 MB/s",
  "Write Bandwidth": "0.00 MB/s",
  "warns": [],
  "recordsWritten": 0,
  "recordsRead": 6250000,
  "bytesRead": 100000000,
  "time": "14.92 s",
  "operation": "FileUtility.ReadTest_example::hpccsystems::file",
  "errors": [],
  "successful": true
}]

Conclusion

Following these steps ensures that HPCC Systems can securely authenticate HPCC4j clients and allow them to read and write data within the target HPCC systems cluster.