View on GitHub

cdeDocs

C-DEngine documentation

Configuration Keys for C-DEngine.dll Version Number 1.1 (Draft) February 3rd, 2020

Introduction to Configuration Keys

Overview

Configuration settings are using “Key/Value” pairs. This document describes the effect of values to their corresponding keys.

App.Config

Local configuration file of an application hosting the C-DEngine.

cdeTPI – C-DEngine Provisioning Info

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 Settings API (ICDESettings)

Configuration Keys Reference

The C-DEngine differentiates between four different setting stages:

  1. 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
  2. Startup Only – parsed every time the node starts up
  3. 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
  4. 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.

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 only settings

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

All other settings

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.