Configuration

There are some configuration settings in the 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 the 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 the 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

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

auth-server

broker

connectware

container-manager

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_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.

REDINESS_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

system-control-server

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.