Configuration¶
There are some configuration settings in Connectware which need to be set before starting the system. This section explains how to configure these settings.
Environment Variables¶
The system-wide settings of Connectware are set by defining environment variables before starting the system.
The specific places to define those depend on the deployment orchestration tool which is used for Connectware: Either docker-compose, or Kubernetes.
Docker-compose¶
For a docker-compose installation, we recommend defining the values of all
environment variables in the file named .env in the same directory as the
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.
Available exposed environment variables (.env)¶
Variable |
Default |
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 |
172.30.0.0/24 |
true, false |
Should the default ‘admin’ user be enabled? |
CYBUS_AUTH_PASSWORD_POLICY_RULES |
{“min”:5} |
Password policy rules in JSON format. |
|
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 |
Flag to enable or disable the MFA feature for Connectware |
CYBUS_MFA_ENCRYPTION_SECRET |
‘’ |
The key for MFA encryption. |
|
CYBUS_MFA_ENCRYPTION_SALT |
‘’ |
The salt as extra layer of randomness for MFA encryption. |
|
CYBUS_MFA_MAX_INVALID_OTPS_PER_USER |
5 |
Maximum number of invalid OTPs a user can enter during the MFA login flow before the account gets temporarily deactivated. |
|
CYBUS_MFA_BAN_DURATION_MINUTES |
5 |
Duration in minutes for temporarily user account deactivation after failing multiple times entering invalid OTPs during MFA login flow. |
|
broker |
|||
CYBUS_BROKER_USE_MUTUAL_TLS |
no |
yes, no |
Use mutual TLS for broker connections. |
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. |
|
doc-server |
|||
ingress-controller |
|||
postgresql |
|||
protocol-mapper |
|||
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. |
|
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. |
|
Available exposed environment variables (docker-compose.yml)¶
Warning
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.
It is strongly recommended to consultCustomer Success or follow 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.
Variable |
Default |
Choices |
Description |
|---|---|---|---|
admin-web-app |
|||
CYBUS_ADMIN_WEB_APP_VRPC_TIMEOUT |
6000 |
The RPC timeout used for inter-service communications. Useful for configuring higher values for some high load scenarios. |
|
auth-server |
|||
broker |
|||
connectware |
|||
container-manager |
|||
CYBUS_CM_RPC_TIMEOUT |
6000 |
The RPC timeout used for inter-service communications. Useful for configuring higher values for some high load scenarios. |
|
doc-server |
|||
ingress-controller |
|||
postgresql |
|||
protocol-mapper |
|||
CYBUS_MQTT_SCHEME |
mqtt |
The scheme for MQTT communication. |
|
CYBUS_MQTT_HOST |
broker |
The MQTT broker host. |
|
CYBUS_MQTT_PORT |
1883 |
The MQTT broker port. |
|
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_MQTT_DATA_HOST |
‘’ |
MQTT data host. |
|
CYBUS_MQTT_DATA_PORT |
‘’ |
MQTT data port. |
|
CYBUS_AUTH_SERVER_HOST |
auth-server |
The hostname of the Auth Server. |
|
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_PM_RPC_TIMEOUT |
6000 |
The RPC timeout used for inter-service communications. Useful for configuring higher values for some high load scenarios. |
|
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. |
|
USE_MUTUAL_TLS |
false |
true, false |
Whether to use mutual TLS for connections. |
TRUST_ALL_CERTS |
true |
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. |
CYBUS_HOSTNAME_INGRESS |
see CYBUS_MQTT_HOST |
See CYBUS_MQTT_HOST. |
|
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. |
|
service-manager |
|||
CYBUS_SM_RPC_TIMEOUT |
6000 |
The RPC timeout used for inter-service communications. Useful for configuring higher values for some high load scenarios. |
|
system-control-server |
|||
CYBUS_SCS_RPC_TIMEOUT |
6000 |
The RPC timeout used for inter-service communications. Useful for configuring higher values for some high load scenarios. |
|
workbench |
|||
Kubernetes¶
For a Kubernetes installation a Helm Chart is provided which includes a values.yaml file which provides defaults for most of the needed configuration. The only mandatory value that needs to be set is licensekey which needs to be set to your Connectware license key.
The Helm Chart’s README.md provides a resume of all the available options and the values.yaml itself documents each of the properties and how to use them.
LDAP Configuration¶
For the optional LDAP authentication feature, some extra configuration is needed.
MFA Configuration¶
Required configuration to enable the MFA feature.