Configurable Environment Variables
When creating the OPC Router container, you can set environment variables that are visible within the container. The OPC Router can be configured using the environment variables specified here; these are read at startup.
note
These environment variables apply not only to the OPC Router Docker container but also to Windows installations. There, you create them as system environment variables; see Creating System Environment Variables. However, even for Windows installations, the “OPCRouter5-Service” and “OPCRouter5-Management” services must be restarted so that the modified environment variables are recognized.
General Environment Variables
| Environment Variable | Description | Example Value |
|---|---|---|
OR_I_ACCEPT_EULA | Setting this to true constitutes acceptance of the End User License Agreement. Required for the application to run. | true |
TZ | Container time zone – a standard variable of the container image that the OPC Router does not read itself; if not specified, the container operates in UTC. | Europe/Berlin |
OR_LOG_LEVEL | Specifies what is written to the log files: a comma-separated list consisting of Trace, Debug, Warning, and Error. This specification is not a threshold value, but a selection—exactly what is listed is logged. The variable overrides the setting in the Log Output group (see Log Files and Event Log); without the variable, the setting from the user interface applies. | Warning,Error |
You set up the initial user account for Web Management using INITIAL_USERNAME, INITIAL_PASSWORD, and INITIAL_PASSWORD_FILE. These variables are described in the section “Environment Variables for Authentication in Web Management.”
Environment variables for Web Management
| Environment Variable | Description | Example Value |
|---|---|---|
OR_WEB_HTTP_PORT | Specifies the port for HTTP connections. If HTTPS is available, the port refers to the HTTPS port. (Default: 8080) | 80 |
OR_WEB_HTTPS_PORT | Specifies the port for HTTPS connections. HTTPS requires a valid SSL certificate. (Default: 8443) | 443 |
OR_RUNTIME_HEALTH_ENDPOINT_PORT | Specifies the port through which Web Management accesses the OPC Router’s runtime health endpoint. (Default: 53200) | 53200 |
OR_ENABLE_HEALTH_ENDPOINT | Enables the Web Management health endpoint as well as redirection of the runtime health endpoint to /health/runtime. (Default: true) | true |
OR_WEB_HTTPS_CERTIFICATE_PEM | Sets a PEM-encoded SSL certificate. Use either this or OR_WEB_HTTPS_CERTIFICATE_PEM_FILE. | -----BEGIN CERTIFICATE----- |
OR_WEB_HTTPS_CERTIFICATE_PEM_FILE | Specifies the path to a PEM-encoded file on the container from which the SSL certificate is extracted. Use either this or OR_WEB_HTTPS_CERTIFICATE_PEM. | /inray/https.pem |
OR_WEB_HTTPS_CERTIFICATE_KEY_PEM | Sets the private key of the PEM-encoded SSL certificate. Use either this or OR_WEB_HTTPS_CERTIFICATE_KEY_PEM_FILE. | -----BEGIN RSA PRIVATE KEY----- |
OR_WEB_HTTPS_CERTIFICATE_KEY_PEM_FILE | Specifies the path to the private key of the PEM-encoded SSL certificate on the container. Use either this or OR_WEB_HTTPS_CERTIFICATE_KEY_PEM. | /inray/https.key |
OR_ENABLE_HTTP_LOGGING | Can be set to true to enable logging of web requests. | true |
OR_WEB_DISABLE_HTTPS | Can be set to false to enable HTTPS. (Default: true) | false |
OR_RATE_LIMITING_ENABLED | Can be set to false to disable rate limiting. (Default: true) | false |
Environment variables for authentication in Web Management
| Environment Variable | Description | Example Value |
|---|---|---|
INITIAL_USERNAME | Specifies the name of the initial local user account for Web Management. This variable is only required if a local password-based login is to be created. The initial user has the Admin role (see User Roles) and is automatically recreated with this role when the container is restarted. | or5 |
INITIAL_PASSWORD | Sets the password for the initial local user account for Web Management. Use either this or INITIAL_PASSWORD_FILE. | Don'tUseThis,ItWouldn'tBeSecure! |
INITIAL_PASSWORD_FILE | Specifies the path to a file on the container from which the password for the initial local user account for Web Management is retrieved. Use either this or INITIAL_PASSWORD. | /inray/defaultpw |
AUTH_DB_CONNECTION_STRING | Sets the connection string to the OPC Router authentication database. Use either this or AUTH_DB_CONNECTION_STRING_FILE. | Data Source=OPCRouterWebConfig.db; |
AUTH_DB_CONNECTION_STRING_FILE | Specifies the path to a file on the container from which the connection string to the OPC Router authentication database is retrieved. Use either this or AUTH_DB_CONNECTION_STRING. | /inray/authdbconn |
AZURE_AD_INSTANCE | Sets the Azure Active Directory instance. | https://login.microsoftonline.com/ |
AZURE_AD_DOMAIN | Sets the domain of the Azure Active Directory tenant. | contoso.onmicrosoft.com |
AZURE_AD_TENANT_ID | Sets the Azure Active Directory tenant ID. | 123456ab-1a2b-3c45-67de-1234ab-567cd8 |
AZURE_AD_CLIENT_ID | Sets the Azure client ID. | 11111111-1111-1111-1111-111111111111 |
AZURE_AD_CALLBACK_PATH | Sets the relative request path to which the user agent is passed. (Default: /signin-oidc) | /signin-oidc |
AZURE_AD_SIGNED_OUT_CALLBACK_PATH | Sets the relative request path to which the user agent is passed after logging out of the identity provider. See post_logout_redirect_uri in https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RedirectionAfterLogout. (Default value: /signout-callback-oidc) | /signout-callback-oidc |
AZURE_AD_DISABLE_AUTO_PROVISION | Disables the automatic creation of new Microsoft Entra ID users upon the first successful login. If set to true, only existing external users with a matching email address can log in. | true |
OR_EXTERNAL_USER_ADMIN_EMAILS | A comma-, semicolon-, or line-separated list of email addresses that are pre-provisioned as external users with the local role Admin at startup. Suitable for SSO scenarios such as Microsoft Entra ID or pronubes Auth Forward. | admin@example.com;ops@example.com |
OR_EXTERNAL_USER_EDITOR_EMAILS | A comma-, semicolon-, or line-separated list of email addresses that will be pre-provisioned as external users with the local role Editor at startup. | editor@example.com |
OR_EXTERNAL_USER_OBSERVER_EMAILS | A comma-, semicolon-, or line-separated list of email addresses that are pre-provisioned at startup as external users with the local role Observer. | observer@example.com |
OR_DISABLE_AUTH | Disables user authentication for Web Management when set to true. | true |
OR_DISABLE_WIN_AUTH | Disables Windows user authentication for Web Management when set to true. | true |
note
Operation with authentication enabled and without INITIAL_USERNAME / INITIAL_PASSWORD is possible if only external authentication methods such as Microsoft Entra ID or pre-provisioned external users are used. For Windows installations, Windows authentication is also an option.
If AZURE_AD_DISABLE_AUTO_PROVISION=true is set, Entra ID users must be created in advance as external users or provisioned via OR_EXTERNAL_USER_ADMIN_EMAILS, OR_EXTERNAL_USER_EDITOR_EMAILS, and OR_EXTERNAL_USER_OBSERVER_EMAILS.
Environment variables for licensing
| Environment Variable | Description | Example Value |
|---|---|---|
OR_LICENSE_KEY | The license key for the license. | <license-key> |
OR_LICENSE_KEY_FILE | Path to a file containing the license key. Use either this or OR_LICENSE_KEY. | /inray/licensekey |
OR_LICENSE_OPCROUTERID | The OPC Router ID of the license. | <router-id> |
OR_INSTANCE_NAME | Name for the licensed system. | <instance-name> |
OR_LICENSE_DEPLOYMENTTOKEN | Deployment token from the license portal for automatic license activation. | <deployment-token> |
OR_LICENSE_ACTIVATION_MODE | Controls whether automatic license activation is performed in the runtime or web management process. Valid values: runtime and web-management. (Default: runtime) | runtime |
OR_LICENSE_IGNORE_ACTIVATION_ERROR | Optional. If this parameter is set to true, activation errors are ignored. | true |
OR_LICENSE_HOLDER | Optional. Licensee name. | <license-holder> |
OR_LICENSE_LOCATION | Optional. System location. | <location> |
OR_LICENSE_DESCRIPTION | Optional. Additional description. | <description> |
Environment variables for redundancy
OR_REDUNDANCY_MODE
| Value | Meaning |
|---|---|
0 or disabled | Redundancy is disabled |
1 or primary | The OPC Router is active as the primary service |
2 or secondary | The OPC Router is active as the secondary service |
note
Case is not distinguished
| Environment Variable | Default | Description |
|---|---|---|
OR_REDUNDANCY_SHARED_KEY | String used for authenticating the OPC router. This key must be the same for both the primary and secondary services. An empty key is invalid and prevents a connection from being established. | |
OR_REDUNDANCY_SHARED_KEY_FILE | Alternatively, the key can be provided as a text file. | |
OR_REDUNDANCY_ADDRESS | Address of the primary service. This is specified in URL format (http(s):hostname/IP address:port). The port must be the port through which Web Management (the OPC router’s web interface) is accessible. Example: https://example.local:5000 | |
OR_REDUNDANCY_PRIMARY_TIMEOUT | 10 | Time in seconds after which the secondary service is considered disconnected if no heartbeat has been sent. |
OR_REDUNDANCY_SECONDARY_HEARTBEAT_INTERVAL | 5 | The interval in seconds during which the secondary service attempts to reach the primary service. Note: This value must be less than the primary service’s timeout so that the connection is not constantly considered disconnected by the primary service. |
OR_REDUNDANCY_ENABLE_PROJECT_SYNC | true | Enables project synchronization. |
OR_REDUNDANCY_PROJECT_SYNC_ALLOW_EXPERT | true | Enables expert mode for project synchronization. |
OR_REDUNDANCY_PROJECT_SYNC_PING_INTERVAL | 5 | Ping interval (in seconds) for project synchronization. |
OR_REDUNDANCY_LOCAL_MANAGEMENT_ADDRESS | Address at which the local management is accessible to the other OPC Router. | |
OR_REDUNDANCY_COMMUNICATION_GENERATION | 2 | Generation of redundancy communication. Generation 2 is required for project synchronization. |
Database Environment Variables
The OPC Router can use either an integrated MongoDB (only in the Runtime Image) or an external MongoDB (e.g., in the Service Image or in general, if desired).
A) Connection of the OPC Router application to MongoDB (internal or external)
note
For an external MongoDB instance, a minimum version of MongoDB 4.2 (Wire version 8) is required; the MongoDB driver used by OPC Router 5.7 and later versions will reject older MongoDB versions when establishing a connection. MongoDB 6.0 or newer is recommended; see System Requirements .
| Environment variable | Description | Example value |
|---|---|---|
OR_DATABASE_CONNECTION_STRING | Sets the connection string to establish a connection to an external MongoDB. Overrides the connection to the internal database, if one exists. Use either this or OR_DATABASE_CONNECTION_STRING_FILE. | mongodb://127.0.0.1:27017 |
OR_DATABASE_CONNECTION_STRING_FILE | Specifies the path to a file on the container from which the connection string to the external MongoDB is taken. Overrides the connection to the internal database, if one exists. | /inray/dbconnection |
OR_DATABASE_USERNAME | Sets the MongoDB user to be used for authentication. | root |
OR_DATABASE_PASSWORD | Sets the password for the MongoDB user. Use either this or OR_DATABASE_PASSWORD_FILE. | AlsoDontUseThis! |
OR_DATABASE_PASSWORD_FILE | Specifies the path to a file from which the password for the MongoDB user is read. | /inray/dbpw |
OR_DATABASE_NAME_PREFIX | Sets a name prefix for the config, runtime, and status databases. | OR5 |
OR_DATABASE_CERTIFICATE_FILE | Path to a file containing an x.509 certificate for authentication with MongoDB. | /inray/db.pem |
B) MongoDB Deployment in the Runtime Image (Integrated MongoDB)
These variables control only the integrated MongoDB in the Runtime Image (opcrouter/runtime).
When using the Service Image (opcrouter/service), these variables have no effect, as it does not contain MongoDB.
note
Default behavior of the built-in MongoDB (without the MONGO_* variables set):
- The WiredTiger cache uses 25% of the available container RAM.
- The cache is limited to at least 250 MB and a maximum of 2 GB.
- In addition, at least 2 GB of RAM is reserved for the OPC router application, provided that the container memory can be determined correctly. The MongoDB cache is adjusted downward accordingly.
- If the available container RAM cannot be determined (
containerMemory=unknown), a cache of 1 GB is used.
A container RAM of at least 4 GB is recommended for the runtime image; see System Requirements.
| Environment Variable | Description | Example Value | Default |
|---|---|---|---|
MONGO_BIND | Controls the IP addresses on which the integrated MongoDB listens. localhost is recommended if only the OPC Router in the container is to have access. | all, localhost | localhost |
MONGO_CACHE_GB | Sets the WiredTiger cache size for the integrated MongoDB as an absolute value in GB. Overrides all percentage-based and default rules. | 1.5 | |
MONGO_CACHE_PERCENT | Sets the WiredTiger cache size relative to the container’s RAM (as a percentage). Used only if MONGO_CACHE_GB is not set. | 25 | |
MONGO_CACHE_MAX_GB | Maximum allowed cache size for WiredTiger. Prevents unintended upscaling with large containers. | 2.0 | 2.0 |
MONGO_APP_RESERVED_GB | Reserves RAM for the OPC Router application. The MongoDB cache is limited so that this memory (if container RAM is known) remains available for the application. | 2.0 | 2.0 |
MONGO_MIN_FREE_GB | Warning threshold for free space in the MongoDB data directory. Values falling below this threshold are logged at startup. | 2.0 | 2.0 |
MONGO_LOG_TAIL_LINES | Number of log lines output for diagnostic purposes in the event of a MongoDB crash. | 200 | 200 |
MONGO_QUIET | Enables or disables the --quiet mode of the integrated MongoDB. | false | true |
MONGO_DIAG_DATA | Enables MongoDB Diagnostic Data Collection. | true | false |
MONGO_LOG_COMPONENT_VERBOSITY | Sets the MongoDB log verbosity per component as JSON and passes it to --setParameter logComponentVerbosity. | { "verbosity": 1 } | |
MONGO_SLOWMS | Time in milliseconds at which MongoDB queries are marked as slow (slowMS). | 200 |
Environment Variables for Metrics
The OPC Router internally collects metrics, such as those used for status displays in Web Management. The OpenTelemetry SDK reserves memory for each metric instrument to accommodate a fixed number of time series (tag combinations). The Metrics Export section describes how this limit works and when it needs to be increased.
| Environment variable | Description | Example value |
|---|---|---|
OR_METRICS_CARDINALITY_LIMIT | Maximum number of time series (tag combinations) per metric instrument. This value limits the memory requirements for metric collection per service process. Any additional time series exceeding this limit are consolidated into a single overflow point. For systems with a very large number of tag combinations on a single instrument, the limit can be increased. (Default value: 128) | 2000 |
Environment variables for importing project files
| Environment Variable | Description | Example Value |
|---|---|---|
OR_IMPORT_SOURCE | Path to an OPC Router project file on the container that is imported when Web Management starts. | /inray/project.rpe |
OR_IMPORT_CLEAR_CONFIG | If set to true, the existing configuration is reset before the import. | true |
OR_IMPORT_DONT_PUBLISH_CONFIG | For true, the configuration is not automatically published after the import. | true |
OR_IMPORT_OVERWRITE_EXISTING | For true, existing flows, templates, and plug-ins may be overwritten during the import. | true |
OR_IMPORT_AUTH | For true, authentication data contained in the project file is imported. | true |
OR_IMPORT_DECRYPTION_PASSPHRASE | Password for decrypting the authentication data from the project file. | your-secure-passphrase |
OR_IMPORT_DECRYPTION_PASSPHRASE_FILE | Path to a file on the container that contains the password for decrypting the authentication data from the project file. | /secrets/importpass |
Environment variables for the Solution Gallery
| Environment Variable | Description | Example Value |
|---|---|---|
OR_SOLUTION_GALLERY | Semicolon-separated list of sources for the Solution Gallery. | https://example.com/gallery |
OR_SOLUTION_GALLERY_AUTH_TOKEN | Token that is sent as a bearer token in the Authorization header when retrieving Gallery content. | my-gallery-token |
Environment variables for automatic connection to pronubes Management
Using the following environment variables, the OPC Router can automatically establish a connection to a pronubes Management tenant at startup. This causes the OPC Router to automatically appear in the tenant’s inbox without requiring manual registration.
| Environment Variable | Description | Example Value |
|---|---|---|
OR_CONNECT_TO_PRONUBES_MANAGEMENT | Enables automatic connection to pronubes Management when set to true. | true |
OR_ENABLE_PRONUBES_REMOTE_MANAGEMENT | Enables remote management features, such as remote access to the Web UI via pronubes Management, when set to true. Only useful in combination with OR_CONNECT_TO_PRONUBES_MANAGEMENT. | true |
OR_PRONUBES_TENANT_ADDRESS | Address (without https://) of the pronubes Management tenant. | example.pronubes.cloud |
OR_PRONUBES_TENANT_PORT | Port of the tenant. Optional when using the default port 443 (HTTPS). | 443 |
OR_ENABLE_PRONUBES_REMOTE_MANAGEMENT_AUTH_FORWARD | Enables authentication forwarding (Forward Auth) for WebUI access via pronubes Management when set to true. | true |
OR_PRONUBES_CORRELATION_ID | Explicit correlation ID for provisioning and upload to pronubes Management. | my-router-123 |
OR_PRONUBES_DISABLE_CERTIFICATE_AUTHORITY | Disables Certificate Authority validation when set to true. Enables connections using self-signed certificates. Recommended for testing purposes only; not for production use. | false |
note
For WebUI access via pronubes Auth Forward, corresponding local external users must exist. These can be pre-provisioned during setup via OR_EXTERNAL_USER_ADMIN_EMAILS, OR_EXTERNAL_USER_EDITOR_EMAILS, and OR_EXTERNAL_USER_OBSERVER_EMAILS.
Environment Variables for Reverse Proxies and External URLs
| Environment Variable | Description | Example value |
|---|---|---|
WEB_BASE_PATH | Path prefix under which the Web Management interface is accessible behind a reverse proxy. The value begins with a slash and is used by the application as the base path for all its own addresses. Set this in conjunction with ASPNETCORE_FORWARDEDHEADERS_ENABLED; see Reverse Proxy. (Default: empty) | /opc-router |
ASPNETCORE_FORWARDEDHEADERS_ENABLED | If set to true, the application's header information is transferred. This is required for establishing a connection with reverse proxies. (Default: false) | true |
OR_EXTERNAL_URI_PREFIX | The application’s external URI prefix when the OPC Router is running behind a reverse proxy. | https://example.com/opcrouter |
OR_ADDITIONAL_EXTERNAL_URI_PREFIXES | A comma-separated list of additional external URI prefixes under which the OPC Router can be reached. | https://a.example.com,https://b.example.com |