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 the End User License Agreement is accepted. 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 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 value: 8443) | 443 |
OR_WEB_HTTPS_CERTIFICATE_PEM | Sets the PEM-encoded SSL certificate. Use either this or OR_WEB_HTTPS_CERTIFICATE_PEM_FILE. | |
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 for the PEM-encoded SSL certificate. Use either this or OR_WEB_HTTPS_CERTIFICATE_PEM_FILE. | |
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 variable | Description | Example value |
|---|---|---|
INITIAL_USERNAME | Sets the name of the initial user account for Web Management. | 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 |
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_TENNANT_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 http://openid.net/specs/openid-connect-session-1_0.html#RedirectionAfterLogout. (Default value: /signout-callback-oidc) | /signout-callback-oidc |
OR_DISABLE_AUTH | Disables user authentication for Web Management when set to true set. | true |
OR_DISABLE_WIN_AUTH | Disables Windows user authentication for Web Management when set to true . | true |
| 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 |
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 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 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. |
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 any. | /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 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.
- 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 embedded 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 as 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). Used only if MONGO_CACHE_GB is not set. | 25 | |
MONGO_CACHE_MAX_GB | Maximum allowed cache size for WiredTiger. Prevents unintended scaling up 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 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 is passed to --setParameter logComponentVerbosity. | { "verbosity": 1 } | |
MONGO_SLOWMS | Time in milliseconds after 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 import. | true |
OR_IMPORT_AUTH | If true, authentication data contained in the project file is imported. | true |
OR_IMPORT_DECRYPTION_PASSPHRASE | Password used to decrypt 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 |
Relevant ASP.NET Environment Variables
| 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 |