Environment Variables Documentation
This document provides an overview of the environment variables that customers need to configure or be aware of when using Cedalo's Premium Mosquitto distribution and related Platform products. The variables are categorized by product.
Environment Variables (Env Vars) are key-value pairs used to configure software behavior without changing the source code. They allow for flexible setup of features such as licensing, security, endpoint URLs, and runtime options depending on the deployment environment.
In the Cedalo Premium Mosquitto and MQTT Platform products, environment variables can be set differently based on deployment method:
- RPM (RedHat Package Manager): Environment variables are configured in a file located at /etc/opt/cedalo/mosquitto-platform/environment for the platform. This environment file should contain all relevant key-value pairs for the service and is read during startup. For help look into the environment.example file to give an understanding of the file structure.
- Docker Compose: Environment variables are typically defined in the docker-compose.yml file under the service's environment section or in an .env file referenced by Docker Compose.
- OpenShift and Kubernetes: Env Vars are specified in the deployment manifests (Deployment, StatefulSet etc.) under the env: section for containers, often referencing ConfigMaps and Secrets to securely manage sensitive data.
- Portainer: Environment Variables can be set through the container configuration interface under the "Env" tab or by attaching environment files during container creation.
Correct configuration of environment variables is essential for enabling the features and secure operation of the Cedalo MQTT products across different infrastructure setups.
Mosquitto Core Variables
These variables configure core Mosquitto broker features like licensing, security, identity, and persistence.
| Variable | Category | Valid Inputs | Description | Default Value |
|---|---|---|---|---|
| CEDALO_LICENSE_FILE | License Management | Path to license file | License file path. Related to CEDALO_LICENSE_KEY and CEDALO_LICENSE_MODE. | |
| CEDALO_LICENSE_KEY | License Management | Base64 license data | License data. Recommended to use CEDALO_LICENSE_FILE instead. | |
| INFLUX_TOKEN | Security & Authentication | (string) | Token for InfluxDB metrics plugin; alternatively set in mosquitto.conf. | |
| MOSQUITTO_DYNSEC_PASSWORD | Security & Authentication | Minimum 12 characters | Password to initialize Dynsec admin user on fresh broker startup. | |
| MOSQUITTO_PERSISTENCE_LOCATION | Data & Persistence | Path to directory | Overrides persistence_location in mosquitto.conf. | |
| PUID | Security & Authentication | Decimal integer | Run container under this user ID if started as root. | |
| PGID | Security & Authentication | Decimal integer | Run container under this group ID if started as root. | |
| UMASK_SET | Security & Authentication | Octal integer | File creation umask setting. | |
| HOSTNAME | Networking & Host Configuration | ASCII string | Used in HA and MongoDB Bridge features. Default: <Unknown>. | |
| SERVICENAME | Networking & Host Configuration | ASCII string | Service name for Docker Swarm name lookup. |
Mosquitto Platform Variables
Environment variables configuring MQTT Platform features such as API endpoints, licensing, authentication, and session management.
| Variable | Category | Description | Default Value |
|---|---|---|---|
| API_INTERNAL_HOST | Platform UI Configuration | Hostname for internal container communication, usually container name. | localhost |
| AUTH_TRUST_HOST | Networking & Host Configuration | Needed variable set to true for Platform to trust NEXTAUTH_URL | |
| BASE_URL | Networking & Host Configuration | Public-facing URL of the Platform. | |
| NEXTAUTH_URL | Networking & Host Configuration | Authentication URL, often same as BASE_URL. | |
| HOSTNAME | Networking & Host Configuration | Hostname the Platform listens on. | |
| PORT | Networking & Host Configuration | Port the Platform listens on. | |
| CEDALO_LICENSE_KEY | License Management | Platform license key, takes precedence over MOSQUITTO_PLATFORM_LICENSE_FILE. | |
| MOSQUITTO_PLATFORM_LICENSE_FILE | License Management | License file path for the Platform. | |
| AUTH_SECRET | Security & Authentication | Secret used for authentication and session management. | |
| SESSION_MAXAGE | Session & Usage Limits | Maximum session age. | |
| SYSTOPIC_HISTORY_LIMIT | Session & Usage Limits | Limits history size for system topics. |
Platform Enterprise Variables
Environment variables exclusive to Platform Enterprise edition, mostly configuring HTTPS, SSO, LDAP integration, and rate-limiting.
| Variable | Category | Description |
|---|---|---|
| ENABLE_HTTP_REDIRECT | Platform UI Configuration | Enables HTTP redirect if HTTPS is activated. |
| HTTP_PORT | Platform UI Configuration | Port number for HTTP redirect. |
| MOSQUITTO_PLATFORM_HTTPS_CA_PATH | Enterprise Security & Authentication | Path to CA file for HTTPS. |
| MOSQUITTO_PLATFORM_HTTPS_CERT_PATH | Enterprise Security & Authentication | Path to HTTPS certificate file. |
| MOSQUITTO_PLATFORM_HTTPS_KEY_PATH | Enterprise Security & Authentication | Path to private key file for HTTPS. |
| AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS | Enterprise Security & Authentication | Whitelist of emails allowed to sign up via SSO. |
| AUTH_CUSTOM_DEBUG | Enterprise Security & Authentication | Enables debug logging for SSO flows. |
| AUTH_CUSTOM_INFER_NAME | Enterprise Security & Authentication | Attempts to extract user name from SSO claims. |
| AUTH_CUSTOM_LOGO_URL | Enterprise Security & Authentication | URL to logo displayed on SSO button. |
| AUTH_CUSTOM_NAME | Enterprise Security & Authentication | Overrides default label on SSO button. |
| AUTH_CUSTOM_OIDC_CLIENT_ID | Enterprise Security & Authentication | Client ID for OIDC authentication. |
| AUTH_CUSTOM_OIDC_TOKEN_URL | Enterprise Security & Authentication | Token URL endpoint for OIDC. |
| AUTH_CUSTOM_SAML_IDP_URL | Enterprise Security & Authentication | Identity Provider URL for SAML. |
| AUTH_LDAP_URL | Enterprise Security & Authentication | LDAP server connection URL. |
| AUTH_LDAP_ADMIN_DN | Enterprise Security & Authentication | LDAP admin distinguished name for binding. |
| AUTH_LDAP_ADMIN_PASSWORD | Enterprise Security & Authentication | Password for LDAP admin user. |
| AUTH_LDAP_SCOPE | Enterprise Security & Authentication | LDAP search scope. |
| RATE_LIMIT_ENABLE | Rate Limiting & Usage Controls | Enables rate limiting on requests. |
| RATE_LIMIT_MAX | Rate Limiting & Usage Controls | Maximum allowed requests within rate limit window. |