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, which are read at startup.
note
These environment variables apply not only to the OPC Router Docker container but also to Windows installations. However, even for Windows installations, the “OPCRouter5-Service” and “OPCRouter5-Management” services must be restarted so that the changed environment variables are recognized.
General Environment Variables
| Environment Variable | Description | Example Value |
|---|---|---|
OR_I_ACCEPT_EULA | Setting this to true accepts the End User License Agreement. Required for the application to run. | true |
INITIAL_USERNAME | Sets the name of the initial user account for Web Management. 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 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 user account for Web Management is retrieved. Use either this or INITIAL_PASSWORD. | /inray/defaultpw |
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 | Sets the port for HTTPS connections. HTTPS requires a valid SSL certificate. (Default: 8443) | 443 |
OR_RUNTIME_HEALTH_ENDPOINT_PORT | Sets the port through which Web Management reaches the OPC Router’s runtime health endpoint. (Default: 53200) | 53200 |
OR_ENABLE_HEALTH_ENDPOINT | Enables the Web Management health endpoint and the redirection of the runtime health endpoint at /health/runtime. (Default: true) | true |
OR_WEB_HTTPS_CERTIFICATE_PEM | Sets the 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 retrieved. 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 | Sets the name of the initial local user account for Web Management. This variable is only required if a local password login is to be created. | 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 taken. 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 redirected. (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 | Comma-, semicolon-, or line-separated list of email addresses that are 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 as external users with the local role Observer at startup. | 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 login 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 | Meaning |
|---|---|
OR_LICENSE_KEY | The license key of the license |
OR_LICENSE_KEY_FILE (alternative to OR_LICENSE_KEY) | Path to a file containing the license key. |
OR_LICENSE_OPCROUTERID | The OPC Router ID of the license |
OR_INSTANCE_NAME | Name of the licensed system |
OR_LICENSE_IGNORE_ACTIVATION_ERROR (optional) | If this parameter is set to true, activation errors are ignored. |
OR_LICENSE_HOLDER (optional) | Name of the license holder |
OR_LICENSE_LOCATION (optional) | Location of the system |
OR_LICENSE_DESCRIPTION (optional) | Additional description |
OR_LICENSE_DEPLOYMENTTOKEN | Deployment token from the license portal for automatic license activation |
OR_LICENSE_ACTIVATION_MODE | Controls whether automatic license activation is performed in the runtime or web management process |
Environment Variables for Redundancy
OR_REDUNDANCY_MODE
| Value | Meaning |
|---|---|
0 or disabled | Redundancy is inactive |
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 the connection from being established. | |
OR_REDUNDANCY_SHARED_KEY_FILE | Alternatively, the key can also be specified 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 under 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 in 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 | Redundancy communication generation. 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., with the Service Image or generally, if desired).
A) Connecting the OPC Router Application to MongoDB (internal or external)
| 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 present. 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 present. | /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 exclusively control 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 integrated MongoDB (without set MONGO_* variables):
- 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.
- Additionally, 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.
| Environment variable | Description | Example value | Default |
|---|---|---|---|
MONGO_BIND | Controls which IP addresses the integrated MongoDB listens on. localhost is recommended if only the OPC Router in the container is supposed to access it. | all, localhost | localhost |
MONGO_CACHE_GB | Sets the WiredTiger cache size of the integrated MongoDB to an absolute value in GB. Overrides all percentage/default rules. | 1.5 | |
MONGO_CACHE_PERCENT | Sets the WiredTiger cache size relative to the container RAM (in percent). Only used if MONGO_CACHE_GB is not set. | 25 | |
MONGO_CACHE_MAX_GB | Maximum allowed cache size for WiredTiger. Prevents unintended upscaling for 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. Falls below this threshold are logged at startup. | 2.0 | 2.0 |
MONGO_LOG_TAIL_LINES | Number of log lines output for diagnostics in the event of a MongoDB crash. | 200 | 200 |
MONGO_QUIET | Enables or disables the --quiet mode of the embedded 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 is passed to --setParameter logComponentVerbosity. | { "verbosity": 1 } | |
MONGO_SLOWMS | Time in milliseconds at which MongoDB queries are marked as slow (slowMS). | 200 |
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 true, the existing configuration is reset before the import. | true |
OR_IMPORT_DONT_PUBLISH_CONFIG | If true, the configuration is not automatically published after import. | true |
OR_IMPORT_OVERWRITE_EXISTING | If true, existing connections, templates, and plug-ins may be overwritten during import. | true |
OR_IMPORT_AUTH | If 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 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 | Tenant port. Optional if the default port 443 (HTTPS) is used. | 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 correlationID for provisioning and upload to pronubes Management. | my-router-123 |
OR_PRONUBES_DISABLE_CERTIFICATE_AUTHORITY | Disables Certificate Authority verification when set to true. Enables connection with self-signed certificates. Recommended for testing purposes only, not for production use. | false |
note
For WebUI access via pronubes Auth Forward, appropriate local external users must be available. These can be pre-provisioned at startup using 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 |
|---|---|---|
ASPNETCORE_FORWARDEDHEADERS_ENABLED | If set to true, the application's header information is forwarded. This is required for connecting to reverse proxies. (Default: false) | true |
OR_EXTERNAL_URI_PREFIX | External URI prefix of the application when the OPC Router is running behind a reverse proxy. | https://example.com/opcrouter |
OR_ADDITIONAL_EXTERNAL_URI_PREFIXES | Comma-separated list of additional external URI prefixes under which the OPC Router is accessible. | https://a.example.com,https://b.example.com |