Security

• 1: Enable RBAC for the MQTT Broker
• 2: Firewall Rules
• 3: Setup PKI for the MQTT Broker

1 - Enable RBAC for the MQTT Broker

Enable RBAC

Enable RBAC by upgrading the value in the Helm chart.

To do so, run the following command:

sudo $(which helm) upgrade --set mqtt_broker.rbacEnabled=true united-manufacturing-hub united-manufacturing-hub/united-manufacturing-hub -n united-manufacturing-hub --reuse-values --version $(sudo $(which helm) get metadata united-manufacturing-hub -n united-manufacturing-hub --kubeconfig /etc/rancher/k3s/k3s.yaml -o json | jq '.version') --kubeconfig /etc/rancher/k3s/k3s.yaml

Now all MQTT connections require password authentication with the following defaults:

• Username: node-red
• Password: INSECURE_INSECURE_INSECURE

Change default credentials

1. Open a shell inside the Pod:

   sudo $(which kubectl) exec -it united-manufacturing-hub-hivemqce-0 -n united-manufacturing-hub --kubeconfig /etc/rancher/k3s/k3s.yaml -- /bin/sh
   

2. Navigate to the installation directory of the RBAC extension.

   cd extensions/hivemq-file-rbac-extension/
   

3. Generate a password hash with this command.

   java -jar hivemq-file-rbac-extension-<version>.jar -p <password>
   

   • Replace <version> with the version of the HiveMQ CE extension. If you are not sure which version is installed, you can press Tab after typing java -jar hivemq-file-rbac-extension- to autocomplete the version.
   • Replace <password> with your desired password. Do not use any whitespaces.

4. Copy the output of the command. It should look similar to this:

   $2a$10$Q8ZQ8ZQ8ZQ8ZQ8ZQ8ZQ8Zu
   

5. Exit the shell by typing exit.

6. Edit the ConfigMap to update the password hash.

   sudo $(which kubectl) edit configmap united-manufacturing-hub-hivemqce-extension -n united-manufacturing-hub --kubeconfig /etc/rancher/k3s/k3s.yaml
   

   This command will open the default text editor with the ConfigMap contents. Change the value inbetween the <password> tags with the password hash generated in step 4.

   You can use a different password for each different microservice. Just remember that you will need to update the configuration in each one to use the new password.

7. Save the changes.

8. Recreate the Pod:

   sudo $(which kubectl) delete pod united-manufacturing-hub-hivemqce-0 -n united-manufacturing-hub --kubeconfig /etc/rancher/k3s/k3s.yaml
   

What’s next

• Setting up HiveMQ PKI

2 - Firewall Rules

Some enterprise networks operate in a whitelist manner, where all outgoing and incoming communication is blocked by default. However, the installation and maintenance of UMH requires internet access for tasks such as downloading the operating system, Docker containers, monitoring via the Management Console, and loading third-party plugins. As dependencies are hosted on various servers and may change based on vendors’ decisions, we’ve simplified the user experience by consolidating all mandatory services under a single domain. Nevertheless, if you wish to install third-party components like Node-RED or Grafana plugins, you’ll need to whitelist additional domains.

Before you begin

The only prerequisite is having a firewall that allows modification of rules. If you’re unsure about this, consider contacting your network administrator.

Firewall Configuration

Once you’re ready and ensured that you have the necessary permissions to configure the firewall, follow these steps:

Whitelist management.umh.app

This mandatory step requires whitelisting management.umh.app on TCP port 443 (HTTPS traffic). Not doing so will disrupt UMH functionality; installations, updates, and monitoring won’t work as expected.

Optional: Whitelist domains for common 3rd party plugins

Include these common external domains and ports in your firewall rules to allow installing Node-RED and Grafana plugins:

• registry.npmjs.org (required for installing Node-RED plugins)
• storage.googleapis.com (required for installing Grafana plugins)
• grafana.com (required for displaying Grafana plugins)
• catalogue.nodered.org (required for displaying Node-RED plugins, only relevant for the client that is using Node-RED, not the server where it’s installed on).

Depending on your setup, additional domains may need to be whitelisted.

DNS Configuration (Optional)

By default, we are using your DHCP configured DNS servers. If you are using static ip or want to use a different DNS server, contact us for a custom configuration file.

Bring your own containers

Our system tries to fetch all containers from our own registry (management.umh.app) first. If this fails, it will try to fetch docker.io from https://registry-1.docker.io, ghcr.io from https://ghcr.io and quay.io from https://quay.io (and any other from management.umh.app) If you need to use a different registry, edit the /var/lib/rancher/k3s/agent/etc/containerd/config.toml.tmpl to set your own mirror configuration.

Troubleshooting

I’m having connectivity problems. What should I do?

First of all, double-check that your firewall rules are configured as described in this page, especially the step involving our domain. As a quick test, you can use the following command from a different machine within the same network to check if the rules are working:

curl -vvv https://management.umh.app

3 - Setup PKI for the MQTT Broker

If you want to use MQTT over TLS (MQTTS) or Secure Web Socket (WSS) you need to setup a Public Key Infrastructure (PKI).

Read the blog article about secure communication in IoT to learn more about encryption and certificates.

Structure overview

The Public Key Infrastructure for HiveMQ consists of two Java Key Stores (JKS):

• Keystore: The Keystore contains the HiveMQ certificate and private keys. This store must be confidential, since anyone with access to it could generate valid client certificates and read or send messages in your MQTT infrastructure.
• Truststore: The Truststore contains all the clients public certificates. HiveMQ uses it to verify the authenticity of the connections.

Before you begin

You need to have the following tools installed:

• OpenSSL. If you are using Windows, you can install it with Chocolatey.
• Java

Create a Keystore

Open a terminal and run the following command:

keytool -genkey -keyalg RSA -alias hivemq -keystore hivemq.jks -storepass <password> -validity <days> -keysize 4096 -dname "CN=united-manufacturing-hub-mqtt" -ext "SAN=IP:127.0.0.1"

Replace the following placeholders:

• <password>: The password for the keystore. You can use any password you want.
• <days>: The number of days the certificate should be valid.

The command runs for a few minutes and generates a file named hivemq.jks in the current directory, which contains the HiveMQ certificate and private key.

If you want to explore the contents of the keystore, you can use Keystore Explorer.

Generate client certificates

Open a terminal and create a directory for the client certificates:

mkdir pki

Follow these steps for each client you want to generate a certificate for.

1. Create a new key pair:

   openssl req -new -x509 -newkey rsa:4096 -keyout "pki/<servicename>-key.pem" -out "pki/<servicename>-cert.pem" -nodes -days <days> -subj "/CN=<servicename>"
   

2. Convert the certificate to the correct format:

   openssl x509 -outform der -in "pki/<servicename>-cert.pem" -out "pki/<servicename>.crt"
   

3. Import the certificate into the Truststore:

   keytool -import -file "pki/<servicename>.crt" -alias "<servicename>" -keystore hivemq-trust-store.jks -storepass <password>
   

Replace the following placeholders:

• <servicename> with the name of the client. Use the service name from the Network > Services tab in UMHLens / OpenLens.
• <days> with the number of days the certificate should be valid.
• <password> with the password for the Truststore. You can use any password you want.

Import the PKI into the United Manufacturing Hub

First you need to encode in base64 the Keystore, the Truststore and all the PEM files. Use the following script to encode everything automatically:

• Windows
• macOS/Linux

Get-ChildItem .\ -Recurse -Include *.jks,*.pem | ForEach-Object {
    $FileContent = Get-Content $_ -Raw
    $fileContentInBytes = [System.Text.Encoding]::UTF8.GetBytes($FileContent)
    $fileContentEncoded = [System.Convert]::ToBase64String($fileContentInBytes)
    $fileContentEncoded > $_".b64"
    Write-Host $_".b64 File Encoded Successfully!"
}

find ./ -regex '.*\.jks\|.*\.pem' -exec openssl base64 -A -in {} -out {}.b64 \;

You could also do it manually with the following command:

openssl base64 -A -in <filename> -out <filename>.b64

Now you can import the PKI into the United Manufacturing Hub. To do so, create a file named pki.yaml with the following content:

_000_commonConfig:
  infrastructure:
    mqtt:
      tls:
        keystoreBase64: <content of hivemq.jks.b64>
        keystorePassword: <password>
        truststoreBase64: <content of hivemq-trust-store.jks.b64>
        truststorePassword: <password>
        <servicename>.cert: <content of <servicename>-cert.pem.b64>
        <servicename>.key: <content of <servicename>-key.pem.b64>

Now, send copy it to your instance with the following command:

scp pki.yaml <username>@<ip-address>:/tmp

After that, access the instance with SSH and run the following command:

sudo $(which helm) upgrade -f /tmp/pki.yaml united-manufacturing-hub united-manufacturing-hub/united-manufacturing-hub -n united-manufacturing-hub --reuse-values --version $(sudo $(which helm) get metadata united-manufacturing-hub -n united-manufacturing-hub --kubeconfig /etc/rancher/k3s/k3s.yaml -o json | jq '.version') --kubeconfig /etc/rancher/k3s/k3s.yaml

What’s next

• Learn more about HiveMQ’s TLS configuration in the HiveMQ documentation.