# Environment Variables Set environment variables to configure Connectware before you start the system. How you do this depends on your deployment method. * **Docker Compose**: Define the required environment variables in your `.env` and `docker-compose.yml` configuration files. * **Kubernetes with Helm**: Configure settings through Helm values in the `values.yaml` file (see [Connectware Helm Chart](https://docs.cybus.io/2-0-4/documentation/connectware-on-kubernetes/connectware-helm-chart)). If both a Helm value and the related environment variable are defined, the environment variable is ignored to prevent conflicting configurations. {% hint style="info" %} For Kubernetes deployments, do not use environment variables for settings that have a corresponding Helm value. Configure those settings exclusively through the Connectware Helm chart. {% endhint %} ## Docker Compose When using Docker Compose, we recommend that you define all environment variable values in a `.env` file located in the same directory as your `docker-compose.yml` file. Those two files are in your Connectware installation directory. If you have used the default values during installation, the installation directory is `/opt/connectware`. ### Environment Variables for `.env` | Variable | Default Value | Choices | Description | | ------------------------------------------ | ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | **admin-web-app** | | | | | `CYBUS_NETWORK_MASK` | 172.30.0.0/24 | AAA.BBB.CCC.DDD/XX | Network configuration used to manually set masks for the internal Connectware network. | | **auth-server** | | | | | `CYBUS_ADMIN_USER_ENABLED` | true | true, false | Should the default ‘admin’ user be enabled? | | `CYBUS_AUTH_PASSWORD_POLICY_RULES` | {“min”:5} | | Password policy rules in JSON format. | | `CYBUS_MS_ENTRA_ID_ENABLED` | false | true, false | | | `CYBUS_MS_ENTRA_ID_CLIENT_ID` | | | | | `CYBUS_MS_ENTRA_ID_TENANT_ID` | | | | | `CYBUS_MS_ENTRA_ID_CALLBACK_DOMAIN` | | | | | `CYBUS_MS_ENTRA_ID_CLIENT_SECRET` | | | | | `CYBUS_MS_ENTRA_ID_ISSUER_URL` | | | | | `CYBUS_MS_ENTRA_ID_USERNAME_MAPPING_FIELD` | | | | | `CYBUS_INITIAL_ADMIN_USER_PASSWORD` | YWRtaW4= | | The initial password of ‘admin’ user, as base64-encoded value. It must comply with any password policy rules if there are some. | | `CYBUS_LDAP_ENABLED` | false | true, false | Enable LDAP authentication. | | `CYBUS_LDAP_MODE` | group | | LDAP mode for authentication. | | `CYBUS_LDAPS_TRUST_ALL_CERTS` | false | | Trust all certificates for LDAPS (LDAP over SSL). | | `CYBUS_LDAP_BIND_DN` | ‘’ | | Distinguished Name (DN) for LDAP binding. | | `CYBUS_LDAP_BIND_PASSWORD` | ‘’ | | Password for LDAP binding. | | `CYBUS_LDAP_ROLES_ATTRIBUTE` | employeeType | | LDAP attribute to determine user roles. | | `CYBUS_LDAP_MEMBER_ATTRIBUTE` | memberOf | | LDAP attribute to determine group membership. | | `CYBUS_LDAP_SEARCH_BASE` | ‘’ | | LDAP search base for user authentication. | | `CYBUS_LDAP_SEARCH_FILTER` | ‘’ | | LDAP search filter for user authentication. | | `CYBUS_LDAP_URL` | ‘’ | | LDAP server URL for user authentication. | | `CYBUS_LDAP_USER_RDN` | cn | | LDAP user relative distinguished name. | | `CYBUS_LDAP_NEST_GROUP_SUPPORT` | ‘’ | | Support for nested LDAP groups. | | `CYBUS_LDAPS_CA_FILE` | ‘’ | | File path for LDAPS (LDAP over SSL) CA certificate. | | `CYBUS_LDAP_AUTO_ENFORCE_MFA` | ‘’ | true, false | LDAP users get enforced to enroll MFA after first login | | `CYBUS_MFA_ENABLED` | false | true, false | Enables the MFA feature when set to `true`. Disables MFA when set to `false` | | `CYBUS_MFA_ENCRYPTION_SECRET` | | | The key used for MFA encryption | | `CYBUS_MFA_ENCRYPTION_SALT` | | | Additional random element used in the MFA encryption process | | `CYBUS_MFA_MAX_INVALID_OTPS_PER_USER` | | | Specifies the max number of incorrect OTPs a user can input during MFA login before their account is temporarily deactivated | | `CYBUS_MFA_BAN_DURATION_MINUTES` | | | Defines the duration (in minutes) of temporary account deactivation after multiple failed OTP attempts during MFA login | | **connectware** | | | | | **container-manager** | | | | | `CYBUS_REGISTRY_PASS` | ‘’ | | The password for connecting to the Cybus registry. | | `CYBUS_REGISTRY_USER` | license | | The username for connecting to the Cybus registry. | | **ingress-controller** | | | | | **nats** | | | | | **postgresql** | | | | | **protocol-mapper** | | | | | **resource-status-tracking** | | | | | **service-manager** | | | | | **system-control-server** | | | | | `CYBUS_REGISTRY_PASS` | ‘’ | | The password for connecting to the Cybus registry. | | `CYBUS_PROXY` | ‘’ | | HTTP proxy server for network connections. | | `CYBUS_NO_PROXY` | ‘’ | | A comma separated list of hosts that should not be accessed via the proxy. | | `CYBUS_INGRESS_DNS_NAMES` | | | Specifies all external hostnames that can be used to access Connectware, separated by commas. | | **workbench** | | | | | `CYBUS_WORKBENCH_PROJECTS_ENABLED` | false | true, false | Whether projects are enabled in the Cybus Workbench. | | `CYBUS_PROXY` | ‘’ | | HTTP proxy server for network connections. | | `CYBUS_NO_PROXY` | ‘’ | | A list of hosts that should not be accessed via the proxy. | ### Environment Variables for `docker-compose.yml` {% hint style="danger" %} The following environment variable settings are provided for advanced configuration and should typically not be modified unless you have a deep understanding of their implications. Incorrect changes to these variables can impact the stability and security of the system. Proceed with caution and only make changes if you are confident in their necessity and the potential consequences. We strongly recommend consulting Customer Success or following the guidance provided in the documentation before altering any of these values. Modifying these settings without proper understanding can lead to unexpected behavior and may compromise the functionality of the system. {% endhint %} | Variable | Default | Choices | Description | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **admin-web-app** | | | | | **auth-server** | | | | | `CYBUS_AUTH_TOKEN_EXPIRE_TIME_IN_HOURS` | 12 | |

Defines how long (in hours) a user stays signed in before being logged out for security reasons. After the configured time has passed, the user session expires and a new login is required.

The Admin UI displays a ten-minute countdown in the top right corner, and users receives a warning ten minutes before the session ends. If the variable is not set, or if the value is negative or not a valid number, the system uses the default duration of 12 hours.

| | **broker** | | | | | **connectware** | | | | | **container-manager** | | | | | `CYBUS_SENSITIVE_ENVIRONMENT_VARIABLES` | predefined list of sensitive vars | | Specifies the environment variable names, as a comma-separated list, that must be hidden when container (core and service) data is sent to a client. | | **ingress-controller** | | | | | `CYBUS_ALLOW_INSECURE_TLS_CIPHERS` | `false` | `true`, `false` | Controls the use of insecure Transport Layer Security (TLS) cipher suites in Connectware. When set to `false`, Connectware enforces stronger encryption standards by disabling insecure cipher suites. When set to `true`, Connectware allows the use of insecure TLS cipher suites, which can reduce connection security. | | **nats** | | | | | `CYBUS_NATS_WRITE_DEADLINE` | 15s | | Defines how long (in seconds) the NATS server maintains information about slow-running operations. **Important**: Do not specify values below the default value. Changing this variable may impact system stability. | | **postgresql** | | | | | **protocol-mapper** | | | | | `CYBUS_DATAPLANE_SCHEME` | mqtt, mqtts (when `CYBUS_USE_MUTUAL_TLS` is set to `true`) | | Defines the MQTT scheme for stream server and data connections. | | `CYBUS_MQTT_USERNAME` | ‘’ | | MQTT username for authentication. | | `CYBUS_PROTOCOL_MAPPER_PASSWORD` | ‘’ | | Password for the Protocol Mapper. | | `CYBUS_MQTT_TOPIC_MAX_DEPTH` | 20 | | Maximum depth for MQTT topics. | | `CYBUS_DATAPLANE_HOST` | '' | | Defines the MQTT host for data connections. If `CYBUS_DATAPLANE_HOST` is not defined, the hostname defined for `CYBUS_HOSTNAME_INGRESS` is used. | | `CYBUS_DATAPLANE_PORT` | 1883 (if `CYBUS_DATAPLANE_USE_TLS` or `CYBUS_USE_MUTUAL_TLS` is set to `false`), 8883 (if `CYBUS_DATAPLANE_USE_TLS` or `CYBUS_USE_MUTUAL_TLS` is set to `true`) | | Defines the MQTT port for data connections. | | `CYBUS_STREAMSERVER_PORT` | 4223 (if `CYBUS_USE_MUTUAL_TLS` is set to `false`), 4222 (if `CYBUS_USE_MUTUAL_TLS` is set to `true`) | | Defines the NATS port for stream server connections | | `CYBUS_DATAPLANE_USE_TLS` | ‘’ | | Enables TLS encryption for data connections. If `CYBUS_DATAPLANE_USE_TLS` is not defined, the value defined for `CYBUS_USE_MUTUAL_TLS` is used. | | `CYBUS_STREAMSERVER_SCHEME` | wss | | Defines the NATS scheme for stream server connections. If `CYBUS_USE_MUTUAL_TLS` is set to `true`, the scheme switches to `nats`. | | `CYBUS_STREAMSERVER_HOST` | | | Defines the NATS host for stream server connections. If `CYBUS_STREAMSERVER_HOST` is not set, `CYBUS_HOSTNAME_INGRESS` is used. | | `CYBUS_AUTH_SERVER_HOST` | auth-server | | The hostname of the Auth Server. | | `CYBUS_HOSTNAME_INGRESS` | ‘’ | | Defines the general hostname of Connectware ingress. This is the primary configuration switch to point the agent to Connectware. | | `CYBUS_HTTP_PORT` | 443 | | The HTTP port. | | `CYBUS_HTTP_ROOT` | /api | | The root path for the HTTP server. | | `CYBUS_LOG_LEVEL` | info | | Log level for the Protocol Mapper. | | `CYBUS_LOG_DROP_MILLISECONDS` | 1000 | | Drop milliseconds for log entries. | | `CYBUS_STORAGE_DIR` | /data | | The directory for storing data. | | `CYBUS_NETWORK_BIND_ADDRESS` | 127.0.0.1 | | The network bind address. | | `CYBUS_AGENT_MODE` | centralized | centralized, distributed | The mode of the agent (centralized or distributed). | | `CYBUS_AGENT_NAME` | protocol-mapper | | The name of the agent. | | `CYBUS_USE_MUTUAL_TLS` | false | true, false | Whether to use mutual TLS for connections. This variable overrides `CYBUS_DATAPLANE_USE_TLS=true`. | | `CYBUS_TRUST_ALL_CERTS` | false | true, false | Whether to trust all certificates. | | `CYBUS_SERVICE_MANAGER_HOST` | service-manager | | The hostname of the Service Manager. | | `CYBUS_MAX_TRIES_TO_REACH_SERVICE_MANAGER` | 1500 | 0-N | The default setting of 1500 tries translates to 5 minutes of operation since each attempt includes a 200ms delay. In contrast, setting the value to “0” results in an indefinite number of retries. | | `READINESS_PROBE_PORT` | 9999 | | The port for readiness probes. | | `AGENT_KEY` | /connectware/certs/client/tls.key | | The TLS key for the agent. | | `AGENT_CERT` | /connectware/certs/client/tls.crt | | The TLS certificate for the agent. | | `CA` | /connectware/certs/ca/ca-chain.pem | | The CA certificate. | | `CYBUS_ENABLE_WARMUP_PROGRESSIVE_SERVICE_DEPLOYMENT` | false | true, false | Enables or disables the progressive service deployment warmup mechanism. When enabled, service deployment is gradually ramped up to avoid sudden load. | | `CYBUS_WARMUP_DURATION_MINUTES` | 3 | | Defines the duration (in minutes) for which the warmup mechanism is active. After this time expires, the delay falls back to `CYBUS_NATS_STREAMS_SERVICESCRUD_PROCESSING_DELAY_MILLISECONDS` (default is 0). | | `CYBUS_WARMUP_MINIMUM_DELAY_MS` | 500 | | The minimum (in milliseconds) for the delay an agent can apply during the warmup period. | | `CYBUS_WARMUP_MAXIMUM_DELAY_MS` | 800 | | The maximum (in milliseconds) for the delay an agent can apply during the warmup period. | | `CYBUS_NATS_STREAMS_SERVICESCRUD_PROCESSING_DELAY_MILLISECONDS` | 0 | | The base processing delay (in milliseconds) for NATS Streams Services CRUD operations. This value is used once the warmup duration has expired. | | **resource-status-tracking** | | | | | **service-manager** | | | | | `CYBUS_RESOURCES_CONFIG_SENSITIVE_PROPERTY_PATH_PATTERNS` | \*\* | comma separated list | Specifies JSON pointer paths to sensitive properties within a resource configuration. Values at these paths will be automatically masked. Can be combined with `CYBUS_RESOURCES_CONFIG_SENSITIVE_PROPERTY_NAME_PATTERN`. | | `CYBUS_RESOURCES_CONFIG_SENSITIVE_PROPERTY_NAME_PATTERN` | pass\|secret\|key\|token | regex expression | Defines a regular expression to identify sensitive property names in a resource configuration. Matching properties will be masked. Can be combined with `CYBUS_RESOURCES_CONFIG_SENSITIVE_PROPERTY_PATH_PATTERNS`. By default, all properties with a name containing `pass`, `secret`, `key`, or `token` will have the value `*****`. | | `CYBUS_SERVICE_REINSTALL_DELAY_SECONDS` | 5 | | Defines the waiting period (in seconds) required after deleting a service before you can reinstall another service with the same service ID. Additionally, the endpoint `/v2/services/:id/deletion-status` will return the time remaining until the service is completely deleted. | | **system-control-server** | | | | | **workbench** | | | | ## Kubernetes When you're installing Connectware on Kubernetes, you must use the provided [Connectware Helm chart](https://docs.cybus.io/2-0-4/documentation/connectware-on-kubernetes/connectware-helm-chart). This chart includes a `values.yaml` file that provides default configurations for the necessary settings. The only mandatory value that you must set is the `licensekey` of your Connectware license. To understand all available configuration options: 1. The Helm chart's `README.md` file contains a summary of all configurable options. 2. The `values.yaml` file contains detailed documentation for each property and instructions on how to use them. {% hint style="warning" %} While the Helm chart provides many default settings, you may need to customize these based on your specific deployment requirements. Always review the documentation thoroughly to ensure you're configuring Connectware correctly for your Kubernetes environment. {% endhint %}