Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Environment Variables

Environment variables for configuring Connectware.

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 and Helm Chart Reference). If both a Helm value and the related environment variable are defined, the environment variable is ignored to prevent conflicting configurations.

Environment Variables for Agents

When deploying agents, use the environment variables listed in the protocol-mapper section of the docker-compose.yml table below.

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

preferred_username

The claim from the Microsoft Entra ID token that Connectware maps to the Connectware username.

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

5

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

5

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

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.

CYBUS_METRICS_BINDHOST

::

Network interface the metrics HTTP server binds to. The default :: exposes the endpoint on all interfaces. Set to localhost to restrict access to the host only.

CYBUS_METRICS_COLLECTINTERVALMS

5000

How often collected values are stored into Prometheus counters and gauges, in milliseconds. Scrape intervals shorter than this value will return cached data.

CYBUS_METRICS_RATELIMIT_COUNT

1

Maximum number of scrape requests accepted within the rate limit window. When the limit is reached, the cached value for each metric is returned.

CYBUS_METRICS_RATELIMIT_WINDOWMS

1000

Duration of the rate limit window, in milliseconds.

CYBUS_POSTGRESQL_MAX_TRIES

24

1-N

Number of attempts that the Auth Server and the Service Manager make to reach the database at startup, and that the Auth Server makes to run its database migrations. If all attempts fail, the component exits.

CYBUS_POSTGRESQL_MIGRATION_LOCK_TIMEOUT_MS

5000

0-N

Maximum time, in milliseconds, that the Auth Server waits for a database lock during its database migrations at startup. If the lock does not become free in time, the migration attempt fails and the Auth Server retries it, as set by CYBUS_POSTGRESQL_MAX_TRIES and CYBUS_POSTGRESQL_RETRY_DELAY. Set to 0 to wait without a limit.

CYBUS_POSTGRESQL_RETRY_DELAY

5000

0-N

Time, in milliseconds, that the Auth Server and the Service Manager wait between the attempts set by CYBUS_POSTGRESQL_MAX_TRIES.

CYBUS_POSTGRESQL_SSL_MODE

verify-full

disable, require, verify-full

TLS mode of the database connection. With verify-full, the connection is encrypted, and the server certificate must be signed by a CA in CYBUS_POSTGRESQL_SSL_ROOT_CERT and match the database host name. With require, the connection is encrypted, but the server certificate is not verified. With disable, the connection does not use TLS. Set the same value on the auth-server, service-manager, and topic-explorer containers.

CYBUS_POSTGRESQL_SSL_ROOT_CERT

/connectware_certs/cybus_combined_ca.crt

Path to the CA certificate bundle that verifies the database server certificate when CYBUS_POSTGRESQL_SSL_MODE is verify-full. The default bundle contains the CA that signs the certificate of the bundled PostgreSQL database. Set the same value on the auth-server, service-manager, and topic-explorer containers.

broker

connectware

CYBUS_MAX_DOWNSTREAM_CONNECTIONS

250000

Maximum number of client connections that Connectware accepts at the same time, across all ports (HTTPS, HTTP, MQTT, OPC UA, NATS, and TCP routes 40000–40100). When the limit is reached, Connectware rejects new connections until existing ones close.

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.

CYBUS_ENVOY_ACCESS_LOG_JSON

false

true, false

Set to true to write the access logs of HTTP and HTTPS requests as structured JSON instead of plain text, which makes them easier to forward to log aggregation tools. The access logs appear in the logs of the connectware container.

CYBUS_LOG_LEVEL

info

debug, info, warn, error

Controls the verbosity of Ingress Controller logs. Use debug when diagnosing routing or connection issues.

CYBUS_ROUTE_TIMEOUT

30

Maximum time in seconds that the Ingress Controller waits for the service behind a route to complete a response before it terminates the request. This applies to the routes of the core services and to the routes that services create. Increase this value if long-running requests are cut off, or set it to 0 to disable the timeout. If the value is negative or not a valid number, the Ingress Controller uses the default of 30 seconds.

MAX_TCP_CONNECTIONS

10000

Maximum number of concurrent connections that the Ingress Controller opens to each upstream target. Each incoming MQTT or OPC UA connection consumes one upstream connection, so this value also caps how many clients can connect through the Ingress Controller at the same time. Increase this value if you expect more concurrent clients. The value must be a whole number from 1 to 4294967295. Any other value, including 0, stops the Ingress Controller from starting. The alias CYBUS_MAX_TCP_CONNECTIONS also works.

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

CYBUS_POSTGRESQL_SSL

on

on, off

Turns TLS on or off for the bundled PostgreSQL database. With on, the database accepts TLS connections with a server certificate that the system-control-server creates. If you set it to off, also set CYBUS_POSTGRESQL_SSL_MODE to disable on the auth-server, service-manager, and topic-explorer containers, because their default verify-full requires TLS.

protocol-mapper

Agents: When running protocol-mapper as an agent, use the following environment variables for agent configuration.

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

connectware

Defines the general hostname of Connectware ingress. This is the primary configuration switch to point the agent to Connectware.

CYBUS_PROTOCOL_MAPPER_PORT

8443

The port of the HTTP server of the Protocol Mapper.

CYBUS_HTTP_ROOT

/api

The root path for the HTTP server.

CYBUS_LOG_LEVEL

info

trace, debug, info, warn, error, fatal

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_FILE_LOCAL_ROOTS

/mnt

Colon-separated list of absolute directories that File connections with the local transport can read from. The basePath of a connection must be inside one of them. See File.

CYBUS_FILE_DOWNSTREAM_STABLE_MS

5000

After the connection to the MQTT broker was lost, File endpoints continue reading once the connection has been back for this many milliseconds without interruption. 0 turns the wait off. See File.

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.

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

8000

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.

CYBUS_RESOURCE_CATEGORIES_GRAPH_ENDPOINTS_DEPEND_ON_MAPPINGS

false

true, false

Configures resource deployment order between mappings and endpoints. When set to true, mappings are deployed before endpoints, preventing data loss when read endpoints receive initial data before mappings are ready to process it. When set to false (default), endpoints are deployed before mappings, ensuring write endpoints are fully initialized before mappings can publish to them.

CYBUS_METRICS_BINDHOST

::

Network interface the metrics HTTP server binds to. The default :: exposes the endpoint on all interfaces. Set to localhost to restrict access to the host only.

CYBUS_METRICS_COLLECTINTERVALMS

5000

How often collected values are stored into Prometheus counters and gauges, in milliseconds. Scrape intervals shorter than this value will return cached data.

CYBUS_METRICS_RATELIMIT_COUNT

1

Maximum number of scrape requests accepted within the rate limit window. When the limit is reached, the cached value for each metric is returned.

CYBUS_METRICS_RATELIMIT_WINDOWMS

1000

Duration of the rate limit window, in milliseconds.

resource-status-tracking

CYBUS_METRICS_BINDHOST

::

Network interface the metrics HTTP server binds to. The default :: exposes the endpoint on all interfaces. Set to localhost to restrict access to the host only.

CYBUS_METRICS_COLLECTINTERVALMS

5000

How often collected values are stored into Prometheus counters and gauges, in milliseconds. Scrape intervals shorter than this value will return cached data.

CYBUS_METRICS_RATELIMIT_COUNT

1

Maximum number of scrape requests accepted within the rate limit window. When the limit is reached, the cached value for each metric is returned.

CYBUS_METRICS_RATELIMIT_WINDOWMS

1000

Duration of the rate limit window, in milliseconds.

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.

CYBUS_METRICS_BINDHOST

::

Network interface the metrics HTTP server binds to. The default :: exposes the endpoint on all interfaces. Set to localhost to restrict access to the host only.

CYBUS_METRICS_COLLECTINTERVALMS

5000

How often collected values are stored into Prometheus counters and gauges, in milliseconds. Scrape intervals shorter than this value will return cached data.

CYBUS_METRICS_RATELIMIT_COUNT

1

Maximum number of scrape requests accepted within the rate limit window. When the limit is reached, the cached value for each metric is returned.

CYBUS_METRICS_RATELIMIT_WINDOWMS

1000

Duration of the rate limit window, in milliseconds.

system-control-server

workbench

Last updated

Was this helpful?