HTTPS (HTTP over TLS)

TBMQ supports running the HTTP server that hosts the Web UI and serves REST API calls over SSL.

Most TBMQ environments use the load balancer as a termination point for the SSL connection between the client and the broker. In other words, internet traffic is encrypted between the user browser and the load balancer, but is decrypted between the load balancer and broker services. The advantage of this option is minimal configuration overhead. Most cloud load balancers (AWS, Google Cloud, etc.) have built-in certificate generation tools and rich documentation on how to configure SSL.

Nevertheless, it is possible to configure TBMQ to enable SSL and avoid SSL termination on the load balancer. Use valid SSL certificates from trusted CA authorities. Avoid spending time resolving issues with self-signed certificates. See the instructions below on how to configure SSL for certificates stored in PEM file format or Java Keystore.

Configure the following environment variables via the configuration file, docker-compose, or Kubernetes scripts.

export SSL_ENABLED=true
export SSL_CREDENTIALS_TYPE=PEM
export SSL_PEM_CERT=server.pem
export SSL_PEM_KEY=server_key.pem
export SSL_PEM_KEY_PASSWORD=secret

Where:

• SSL_ENABLED — Enable/disable SSL support.
• SSL_CREDENTIALS_TYPE — Server credentials type. PEM — PEM certificate file; KEYSTORE — Java keystore.
• SSL_PEM_CERT — Path to the server certificate file. Holds server certificate or certificate chain; may also include the server private key.
• SSL_PEM_KEY — Path to the server certificate private key file. Optional by default; required if the private key is not present in the server certificate file.
• SSL_PEM_KEY_PASSWORD — Optional server certificate private key password.

After completing the setup, start or restart the TBMQ server.

Configure the following environment variables via the configuration file, docker-compose, or Kubernetes scripts.

export SSL_ENABLED=true
export SSL_CREDENTIALS_TYPE=KEYSTORE
export SSL_KEY_STORE_TYPE=PKCS12
export SSL_KEY_STORE=keystore.p12
export SSL_KEY_STORE_PASSWORD=tbmq
export SSL_KEY_PASSWORD=tbmq

Where:

• SSL_ENABLED — Enable/disable SSL support.
• SSL_CREDENTIALS_TYPE — Server credentials type. PEM — PEM certificate file; KEYSTORE — Java keystore.
• SSL_KEY_STORE_TYPE — Type of the key store (JKS or PKCS12).
• SSL_KEY_STORE — Path to the key store that holds the SSL certificate or certificate chain; also includes the server private key.
• SSL_KEY_STORE_PASSWORD — Password used to access the key store.
• SSL_KEY_PASSWORD — Password used to access the server private key.

After completing the setup, start or restart the TBMQ server.

To generate self-signed certificates for testing purposes, refer to the Self-signed certificates generation section in the MQTT over SSL guide.

Make sure you have the following files:

• server.pem — the public certificate (may include the chain).
• server_key.pem — the private key.
• ca.pem — root or intermediate CA certificates (optional).

Run the following command to create a PKCS12 keystore file (keystore.p12):

openssl pkcs12 -export \
  -in server.pem \
  -inkey server_key.pem \
  -certfile ca.pem \
  -out keystore.p12 \
  -name tbmq \
  -passout pass:changeit

The -certfile ca.pem line is optional — include it if you have a CA certificate chain. Replace changeit with your desired keystore password; you will reference this in your environment variables.

Tips and best practices:

• For production use, PKCS12 (.p12) format is recommended as it is more interoperable than JKS.
• Make sure your certificate chain is complete (including intermediates) when exporting.