Configuration Keys for C-DEngine.dll Version Number 1.1 (Draft) February 3rd, 2020
Configuration settings are using “Key/Value” pairs. This document describes the effect of values to their corresponding keys.
Local configuration file of an application hosting the C-DEngine.
Encrypted store with all settings changed by the NMI or auto-created by the C-DEngine. The file can be pushed from the C-DEngine Provisining Service.
The C-DEngine differentiates between four different setting stages:
- First Boot Only – parsed only when the node is started for the very first time (boot). For example if no cache folder exists or no cdeTPI exists
- Startup Only – parsed every time the node starts up
- Anytime at Runtime – These are settings that might be read and parsed multiple times during runtime and can be changed via the Provisioning service on the fly without restarting the node. Most of the CDE settings fall in the category
- Plugin only settings – plugins can add settings, either before the start of the node via the app.config or even store settings to the cdeTPI secure storage. This document will not cover these settings as they are plugin specific
There is one important setting that will render a node “Read-Only” and does prevent any setting from being written to the cdeTPI store:
UseRandomDeviceID=true
If set to true, the node will never write anything to disk including settings. All relevant settings have to be in the app.config and cdeTPI will be ignored.
- The default value of all Boolean keys is “false”.
- The default value of all string keys is “not Set”
- The default value of all Guid Keys is “Guid.Empty”
- String List use values separated with ; if not other specified
If AllowEnvironmentVars=true and AllowEnvironmentVarsToOverrideConfig=true
then ANY setting can be overwritten with environment variables. No matter if
they are declared in the app.config or in the cdeTPI. Please use with caution as
these values are globally visible on the hosting PC and cannot be managed by the
C-DEngine. All Environment variable have to start with “CDE_” and always use
upper case (i.e. the setting for the “ServiceRoute” would be “CDE_SERVICEROUTE”)
First boot settings are only parsed when the node is started for the very first time (No cache folder existed – no cdeTPI existed).
These setting are important for subsequent starts of the node. If these settings are in the app.config, they will be transferred to the secure cdeTPI storage and then no longer parsed from app.config (in subsequent node starts).
| Configuration Key | Type | stored in cdeTPI | Description |
|---|---|---|---|
| MyDeviceInfo | struct | Always during first boot* | Contains important information about the hardware/os and the DeviceID of the node. The DeviceID is a unique Identifier for the node. There must not be duplicates of DeviceIDs in a mesh solution. This setting is automatically created during boot of the node and cannot directly be set. |
| PresetDeviceID | Guid | Always during first boot* | If set, the DeviceID in MyDeviceInfo will use this Guid instead of calculating a new Guid during first boot |
| IsUsingUserMapper | bool | Always during first boot* | This setting cannot be changed after the first boot. If true, the C-DEngine will initialize the User Manager and once initialized the User Manager cannot be turned off anymore. If the setting is false, the node only allows Scope Access in the NMI. This is the default for “communication only nodes”. |
| Coufs | JSON string | Not stored | Contains a structure that “Creates user on first startup”. Can be used by MSI setups and App.Config to automatically create an admin user during the first boot. The key is removed from the app.config an ignored during subsequent starts of the node. |
| EasyScope | String | Stored as ScrambledScope | A node can be configured with a specific scope during first boot. The C-DEngine will delete this setting from the app.config after it has been read. |
| DontDeleteEasyScope | Bool | Not stored | If true, the EasyScope will not be deleted from the app.config (Docker scenario) |
| DontVerifyTrust | Bool | Always during first boot* | If set to true, the node is starting without validating the Plugins code signing certificates. A node cannot toggle between trust and no trust. If trust is turned off one time, it remains untrusted until the node is “wiped clean” again. Default value (FALSE) requires all plugins to be signed with the same certificate as the host application or C-DEngine.DLL. When TRUE, no signing is required (not recommended for production sites), as the C-DEngine is running in "Unsafe" mode and custom plugins can be installed. |
* If UseRandomDeviceID=true, the setting is not written to the cdeTPI
In general, if a setting is in the cdeTPI it will override the setting in app.config. This allows to set a default setting in app.config but the NMI UX can override and store the setting. Then the setting in app.config is no longer valid. A good example for this is the “CloudRoute”. It can be set in the app.config as a default route but admin users with NMI access can change the CloudRoute which will then be stored in the cdeTPI. If a setting is defined in app.config and cdeTPI, the value in cdeTPI will be used.
Many settings are not copied in the cdeTPI file and just reside in the App.config. The Provisioning service can write any setting and override anything that is in the app.config. Without a provisioning service present, only those settings marked “stored in cdeTPI” will be copied to the cdeTPI secure store.
Some settings will be removed (deleted) from the app.config after they were read for the first time. An example of this are the proxy settings or the EasyScope.
| Configuration Key | Type | Copied to cdeTPI | Deleted after copy | Startup only | Description |
|---|---|---|---|---|---|
| ActivationKeys | String list | A licensing key (or keys) needed for unlocking some capability or feature. ServiceHostInfo member: ActivationKeysToAdd. | |||
| Access-Control-Allow-Origin | String | CORS Setting response to OPTIONS Preflight by specific browser restricting access from specific clients. Default: * | |||
| Access-Control-Allow-Methods | String | CORS Setting response to OPTIONS Preflight by specific browser restricting access to only specific REST Methods. Default: * | |||
| Access-Control-Allow-Headers | String | CORS Setting response to OPTIONS Preflight by specific browser restricting access to specific headers: Default: * | |||
| AllowAdhocScopes | bool | Yes | Determines whether a cloud node allows a browser or device to set an scope. If “false” browsers cannot set scopes. This setting must only be set on special cloud solutions that are not used for Node Meshes. Example: https://ink2.me | ||
| AllowAnonymousAccess | bool | Yes | Whether to allow unauthenticated users access to the system. (for integrated NMI solutions only like phone apps or Desktop Applications) | ||
| AllowAutoUpdate | bool | yes | Whether to allow automatic updates of plugins. | ||
| AllowEnvironmentVars | Bool | yes | Whether the C-DEngine checks operating system environment variables for configuration settings. When this is allowed, the prefix "CDE_" is added to the configuration key to avoid conflicts with other sets of environment variables. | ||
| AllowEnvironmentVarsToOverrideConfig | Bool | yes | When set to TRUE, environment variable configuration settings are able to override app.config settings (see also AllowEnvironmentVars). | ||
| AllowForeignScopeIDRouting | Bool | Enables clouds to route customer scopes to unscoped cloud plugins | |||
| AllowLocalHost | Bool | If Set to true, the C-DEngine will accept http://localhost or IP Addresses as an additional inbound URL. MyStationURL is not enforced. | |||
| AllowMessagesInConnect | Bool | Debugging only! | |||
| AllowOnlineHSIChanges | Bool | Enable setting TheHostServiceInfo values from browser URL by referencing the page cdeSetPara.aspx with the keyname. | |||
| AllowPinLogin | Bool | NMI Only: If set to true, the NMI can be configured to allow login via PIN | |||
| AllowRemoteAdministration | Bool | Yes | If set to true, the Mesh Manager is allowed to remotely configure the node with this setting. Remote configuration includes: push updates, restart the node, update the node. | ||
| AllowRemoteThingCreation | Bool | Yes | If set to true, plug-ins on trusted nodes can create things on this nodes via TSM messages. | ||
| AllowSetScopeWithSetAdmin | Bool | NNI ONLY: if a user connects to a node that does not have a scope and no admin user set, this setting allows the user to enter both at the same time | |||
| AllowUnscopedMesh | Bool | If set to true, unscoped nodes can create their own mesh. | |||
| AsyncEngineStartup | Bool | If True, all plugins/services/engines will be registered and started asynchronously. | |||
| AzureAnalytics | string | Set to enable Windows Azure cloud analytics if you host the C-DEngine in Windows Azure. | |||
| BackupFrequency | Int | Timespan in second how often a backup should happen. Default once per day | |||
| BackupKeepLast | Int | Amount of backups to keep | |||
| BackupStart | DateTime | Start Date/Time of auto backups | |||
| BackupToCloud | Bool | If True, the Backup is sent to the provisioning service (if configured) | |||
| BlockCloudNMI | Bool | True | If True, the NMI is not meshed with any other node including the cloud. (HSI.IsCloudNMIBlocked) | ||
| CacheMaxAge | int | Maximum age of HTTP cache (in seconds). | |||
| ClientCertificateThumb | String | True | Thumbnail ID of the client certificate to use for Mesh Connections to next nodes | ||
| ClientCertificateUsage | Int | see below | |||
| CloudBlobURL | String | RETIRED | |||
| CloudServiceRoute | See ServiceRoute. RETIRED. | ||||
| CreateTextLog | bool | Create a file with all strings not formatted for localization (with "###" tags). User during development only! | |||
| CustomerToken | String | yes | Token that associates the node with a customer | ||
| CustomUA | string | A custom user agent used by the REST commands that can be overwritten for special Firewall policies. | |||
| DEBUGLEVEL | int | Indicates the amount of verbosity in the debugging output. | |||
| DefaultEventTimeout | int | Default timeout for firing of events (in milliseconds). | |||
| DefaultHomePage | String | default home page (i.e. nmiportal) | |||
| DefaultLCID | Short | Default locale ID. | |||
| DeviceToken | string | yes | Token that identifies the Node and its Node-Type for automatic provisioning | ||
| DisableCache | bool | If true, the C-DEngine will not cache any resources. | |||
| DisableConsole | Bool | Stop sending debugging messages to the host process console. | |||
| DisableNMI | Bool | Yes | NMI Model is not created and no NMI meshing will take place | ||
| DisableNMIMessages | Bool | NMI Model does not send any NMI updates | |||
| DisableRSAToBrowser | Bool | If set to true, prevents RSA encryption of credentials with browser. Only set this if you encounter RSA incompatibilities with browsers! (VERY rare). | |||
| DisableTls12 | Bool | When True, disables the requirement to use a minimum of TLS 1.2. | |||
| DisableWebSockets | Bool | Whether to prevent the use of the web sockets network API. | |||
| DisallowWebSocket8 | Bool | Yes | Disables the use of the WebSockets stack coming with Windows8 or later and forces the C-DEngine to use the WebSocketsSharp stack. Will result in HSI.IsWebSocket8Active=false | ||
| DisableWebWorker | Bool | NMI ONLY: If true, the NMI will use the old single threaded communication | |||
| DISCO_MX | Int | Discovery service MX setting. | |||
| DISCO_Subnet | IP | Only use discovery in this subnet | |||
| DontDeleteEasyScope | Bool | If True, the EasyScope will not be removed from the app.config (Docker scenario) | |||
| DontRelayNMI | Bool | Prevents NMI telegrams from being routed across the Cloud - cloud connected browsers will get telegrams. | |||
| DontVerifyTrust | Bool | yes | Default value (FALSE) requires all plugins to be signed with the same certificate as the host application or C-DEngine.DLL. When TRUE, no signing is required (not recommended for production sites), as the C-DEngine is running in "Unsafe" mode and custom plugins can be installed. | ||
| EasyScope | String | Yes | Yes | Identical with calling TheScopeManager.SetScopeIDFromEasyID. Will be removed from app.config as soon as it was read (Except DontDeleteEasyScope=true) | |
| EnableAutoBackup | Bool | Activates Auto Backups according to Backup settings | |||
| EnableAutoLogin | Bool | Allows Viewer apps to auto-login a user (only if IsViewer=true) | |||
| EnableCosting | Bool | Whether to enable support for recording resource usage towards charging users for premium access. | |||
| EnableFastSecurity | Bool | When True, security tokens/scrambled ScopeIDs will be handed from incoming subscriptions to outgoing publications. By default the CDE is re-scrambling the ScopeIDs. Therefore, this makes a mesh a little less secure – use carefully! | |||
| EnableHistorian | Bool | Enables a historian log output. Use for Debug only! | |||
| EnableIntegration | Bool | When set to true, the C-DEngine is running embedded/integrated in another web solution. Do not set this on customer relays/gates! It will disable some security features that should not be disabled in these environments! | |||
| EnableIsolation | Bool | Yes | Set to TRUE to enable isolation. If FALSE (default), the relay does not support isolation and will try to load all plugins into the host process. | ||
| EnableKPIs | Bool | When True, enables the capture of key performance indicators for TheThing and ICDEThing objects. | |||
| EnableTaskKPIs | Bool | When True, the node captures key performance indicators about the internal task/thread system. | |||
| EnableUserStatus | Bool | If true, cdeUserStatus.aspx can be called on a node | |||
| FallbackToSimulation | RETIRED | ||||
| FederationID | String | True | Currently not used – future use only | ||
| FireGlobalTimerSync | When True, the health timer fires synchronously. Otherwise, it fires asynchronously. | ||||
| ForceWebPlatform | int | For debugging purposes, this flag can be set to always force output on browsers to a specific platform. | |||
| HeadlessStartupDelay | Int | When true, a delay (in seconds) before starting initialization of engines. C-DEngine essentials are already initialized at this point. Only use for debugging purposes | |||
| HistorianBufferFastSave | Bool | Enables FastSaveLock for historians | |||
| IgnoreAdminCheck | Bool | yes | When true, does not require controlling process to have administrative privileges. (HttpInterceptor and WebSockets8 will not work without Admin privileges) | ||
| IgnoreServerCertificateErrors | Bool | Ignores all Certificate Errors | |||
| IgnoreServerCertificateNotAvailable | Bool | Ignores if a server certificate is not available | |||
| IgnoreServerCertificateNameMismatch | Bool | Ignores if a server Name is not matching the request | |||
| IgnoreServerCertificateChainErrors | Bool | Ignores if the certificate chain has errors | |||
| InstallUpdatesOnStart | Bool | If true, the CDE will install plugin Updates on start of the C-DEngine | |||
| IsCloudDisabled | Bool | Yes | When set to true, no connection to the next node will be established (ServiceRoute will be ignored). | ||
| IsCloudService | Bool | Yes | When True, C-DEngine runs code paths optimized for the Cloud. | ||
| IsConnectedToCloud | bool | Is true if the current node is currently connected to the cloud. All connections will be treated as “Cloud” connections (including local node-to-node connections) | |||
| ISMExtension | String | Set file extension for C-DEngine updates (default is ".CDEX"). | |||
| ISMMainExecutable | String | Enables setting executable name for main ISM program. | |||
| ISMScanForUpdatesOnUSB | Bool | If set to true, the C-DEngine will listen to USB ports for USB sticks containing updates and new plugins. | |||
| ISMScanOnStartup | Bool | If set to true, the C-DEngine will scan for new updates during the startup. | |||
| ISMUpdateDirectory | String | Enables setting update directory for ISM. | |||
| ISMUpdateVersion | Cannot be set | Will contain the version of an update found in the directory or a USB memory stick. | |||
| ISOEN | string | yes | Name of engine to run in the isolated engine process. If this is set, “IsIsolated” is set to “true” and the cdeNodeType will be set to “cdeNodeType.Active”. The node will then become a container for a single isolated plugin creating a mini-mesh with the “master” Node | ||
| IsolatedPlugins | String list | A list of plugins that will be hosted isolated, each in its own process. | |||
| IsOutputCompressed | Bool | Enabled compression for HTTP Response Bodies (gzip) | |||
| IsTLSEnforced | Bool | Yes | If set to true, the C-DEngine will not accept inbound connection on HTTP/WS but requires HTTPS/WSS. (HSI.IsSSLEnforced) | ||
| IsUserManagerInStorage | Bool | Store the user Manager data in IStorageEngine database. Requires a plugin that implements IStorgageEngine | |||
| IsViewer | Bool | When set to True, only one user is allowed to be logged in at any given time. (like a Phone App). | |||
| LocalServiceRoute | See ServiceRoute. RETIRED. | ||||
| LogFilePath | String | Path to the log file. | |||
| LogFilter | String | Filter to include by name specific engines from being included in system log files. (Example: "ContentService;TheCommCore"). Console Output will show all entries | |||
| LogFilterLevel | Int | Threshold to display a message. Compared against TSM.LVL in message. | |||
| LogIgnore | String list | Filter to exclude by name specific engines from being included in system log. (Example: "UPnP;TheCommonUtils") | |||
| LogOnly | String list | List of ENG names to log. All other entries will neither be shown in console nor in text log | |||
| LogWriteBuffer | Int | Number of messages to buffer in memory before writing to disk. | |||
| LogWriteFilterLevel | Int | Each message has a message level (LVL field in TSM). Don't log messages with values below this threshold value. | |||
| MaximumHops | int | Maximum number of node hops allowed for incoming messages. | |||
| MaxLogEntries | Int | Maximum number of entries to store (default is 500). Can dynamically change by calling TheSystemMessageLog.ChangeMaxLogEntries(count). | |||
| MaxLogFiles | Int | Maximum number of log files to write in the specified folder. | |||
| MaxLogFileSize | Int | Specify the maximum size for each log file (in megabytes). | |||
| MessageFilterLevel | Int | The value for eMsgLevel to include in messages. | |||
| MyAltStationURLs | String | A list of alternative URLs that this node might have and therefore would allow connections to. | |||
| MyStationIP | IP address | IPv4 address of current node. | |||
| MyStationName | String | Yes | Yes | Sets the friendly name of current node. (When not set, the primary URL of the node is used instead.) | |
| MyStationURL | String | Yes | Yes | The primary URL of the node. Incoming REST/WS requests are validated against this URL. If a request does not correctly specify this URL, the request is denied. (Similar to SNI on WebServices like IIS). If MyAltStationURLs is set, the CDE will allow these incoming URLs as well. If “AllowLocalhost=true” the incoming request will be allowed even if the URL was not correctly specified. | |
| UseTcpListenerInsteadOfHttpListener | Bool | If true, the C-DEngine will not use the HttpListener but the TcpListener. This allows to run the C-DEngine in user mode but is much slower handling requests | |||
| NodeBlacklist | String list | List of DeviceIDs that are not allowed to connect to the node | |||
| NodeName | String | Sets the friendly name for the current node. | |||
| NodeType | Int | An integer which represents a value for cdeNodeType. (0 = not set, 1 = relay, 2 = active device, 3 = passive, non-relaying node.) | |||
| ParallelPosts | Int | The number of simultaneous REST-POST for a connection. (Default is 1). This has no effect on WebSockets connections | |||
| PermittedUnscopedNodeIDs | String list | RETIRED | |||
| PresetDeviceID | Guid | Presets a node's device ID. | |||
| PreShutDownDelay | Int | Sets the delay (in milliseconds) to delay prior to shutting down, to allow long running tasks to properly and cleanly respond to the shutting down process. | |||
| ProvisioningFailureOption | Int | yes | An integer value for how to respond to provisioning failures. Valid values include: | ||
| 0 (zero) – Shutdown immediately without writing anything to the ClientBin folder. | |||||
| 1 – Wait a short time (15 seconds as of this writing) before trying again. | |||||
| 2 – Continue normal (non-provisioning) startup, ignoring any remote provisioning settings and proceed using the local settings | |||||
| ProvisioningService | Url | yes | The URL of a C-DEngine node where provisioning services are made available by the Mesh Manager plugin. | ||
| ProxyPWD | String | Yes | Yes | Proxy authentication - Password. | |
| ProxyUID | String | Yes | Yes | Proxy authentication - User ID. | |
| ProxyUrl | string | yes | Yes | Proxy network address. | |
| RejectIncomingSETP | Bool | If true, incoming SETP will not be processed - only use for High throughput Nodes in meshes where the NMI is not needed. SETP messages set properties on things. | |||
| RelayOnly | String list | A list of virtual plugins not running on the current node but are allowed to route telegrams through this node. | |||
| RemoveTrustedNodes | Bool | Yes | Yes | Removes all currently known trusted nodes | |
| RequireClientCertificate | RETIRED: Please use “ClientCertificateUsage” instead | ||||
| RequiredClientCertRootThumbprints | String list | List of Client Certificate Thumbprints. Only requests with certificates with these thumbprints are allowed to connect. The server behavior is determined by the “ClientCertificateUsage” option. | |||
| ResourcePath | String | Path for JavaScript resources if Engine is embedded in other cloud solutions. | |||
| RootDir | String | NMI root directory (if virtual directories are used in IIS) | |||
| ScopeUserLevel | Int | If User Manger is not enabled, any user logging in with the ScopeID will be using this user Level | |||
| ScrambledScope | String | Yes | Yes | Yes | Current (scrambled) scope of the node. This setting can be changed via API calls during the node runtime |
| SenderQueueSize | Int | Allows to change the queue size of the QueuedSender (Default 1000 telegrams) | |||
| ServiceRoute | string | Yes | Url and Path to a designated next node with the same ApplicationID. semicolon (;). | ||
| ShowLogInConsole | Bool | NMI ONLY: Shows all NMI log entries in the browser console (F12 tools) | |||
| ShutdownOnLicenseFailure | true | If set, the cdeEngine will shutdown when it encounters no activated license. | |||
| SIGNORE | RETIRED | ||||
| SIMROLE | RETIRED | ||||
| SKUID | Guid | The main product ID (SKU = "Stock Keeping Unit") of the current node. | |||
| STATIONPORT | Ushort | Yes | Yes | Port for HTTP requests to the node. (HSI.MyStationPort) | |
| STATIONWSPORT | Ushort | Yes | Yes | Port for WebSockets requests to the node (HSI.MyStationWSPort). If zero or not set, the node does not accept any incoming WebSockets requests | |
| StartISM | bool | Whether to start Intelligent Service Management (ISM) update service. Must be set prior to calling StartBaseApplication(). DEFAULT IS TRUE | |||
| StartISMDisco | RETIRED | ||||
| StartStation | RETIRED | ||||
| StartupDelay | Seconds | Yes | When true, a delay (in seconds) before starting initialization the C-DEngine. Only use for debugging purposes | ||
| StatusToken | String | Set a token for cdeStatus.aspx page that has to be added to the path to access the status page (i.e.: /cdeStatus.aspx?<token> | |||
| StorageMirrorFastSave | Bool | Enables FastSave for all Storage Mirrors | |||
| StoreLoggedMessages | Bool | If set to True, the system will store messages in a Distributed Storage Mirror. | |||
| ThingRegistryFastSave | Bool | Enables FastSave for TheThingRegistry | |||
| ThingRegistryStoreInterval | int | How frequently the ThingRegistry flushes changes to disk (in seconds). | |||
| TrustedNodes | String list | Yes | Yes | Contains an encrypted list of node/deviceIDs the node is trusting. | |
| UPnPDeviceType | string | This defines the “StandardDeviceType” for UPnP. Default is “DimmableLight”. | |||
| UseGELFLoggingFormat | String | Whether to send log data using GELF format. | |||
| UseHBTimerPerSender | Bool | Creates a separate timer for each QueuedSender (uses more resources which might be critical on smaller hardware) | |||
| UseRandomDeviceID | Bool | Not in cdeTPI | Yes | The default (False), data is persisted, including a static node ID along with other device data. When true, the C-DEngine does not store anything on the local node. No Thing properties are persisted. This cannot be set via the cdeTPI and must be configured in the app.config | |
| UseSysLogQueue | Bool | Switches SysLog to a BlockingCollection instead of a StorageMirror | |||
| VerifyTrustPath | True | When true, the C-DEngine will verify the Trust path of the code-signing certificate. Internet connection is REQUIRED. | |||
| WsJsThrottle | Int | Allows to throttle WebSocket Messages to JavaScript clients. Messages will not be sent faster than this number. (Default is 0, no throttling.) | |||
| WSTestCode | String | Requires a Access code for WebSockets connections in the cloud | |||
| WsTimeOut | int | Wait time until the C-DEngine will declare a WebSockets connect attempt as failed. |
- If set to 0 or does not exist, a client certificate is not used and not required (default mode of previous CDE versions)
- If Set to 1, client can present a client certificate. If no scopes are in the cert, scopes will be used as before (Mix operation between new and old security mode)
- If Set to 2, client must present a valid client certificate. If no scopes are in the cert, scopes will be used as before (was previous "RequireClientCertificate=true") (previous default mode but with Client Certificate turned on)
- If set to 3, all clients (including NMI browsers) need to present a client certificate (new enforced Client Certificate Mode only - older CDE Nodes will not able to connect)
- If the client certificate contains one or more SAN URLs of the scheme "com.c-labs.cdescope://" the client will only participate in scopes with that scopeID. The first cdescope is used as the ScopeID if no scope is presented in the message or connection
- In IIS, settings 2 and 3 require the "Client Certificates" setting in "SSL Settings" to be set as "Accept" or "Require" for NMI access