General
The Connect Server is usually configured using JSON files, which are located in the installation directory of the application. In special cases, overriding via environment variables or via command line parameters is possible.
Standard configuration
The default configuration is located in the appsettings.Default.json file. This file should not be changed directly, because these changes may be overwritten by a later upgrade.
Installation specific configuration
If an installation-specific configuration is to be created, it is recommended to copy the file "appsettings.Default.json" into a file with the name "appsettings.json". This file will not be overwritten in case of an upgrade, so the configuration settings stored here will remain.
The default configuration is still taken into account here. The installation-specific configuration must therefore only contain the desired deltas.
Environment-specific configuration
If an installation directory is used in different environments (e.g. in a template for containers), environment-specific configurations can be created. For this purpose, the file "appsettings.Default.json" is converted into a file with the name "appsettings.{environment}.json" copied ({environment} must be replaced by the name of the corresponding environment).
In this scenario, the environment can be specified at runtime using the environment variable "ASPNETCORE_ENVIRONMENT". Usually the values "Development", "Staging" and "Production" are used here, the default value is "Production".
The default configuration and any existing installation-specific configuration are still taken into account. The environment-specific configurations must therefore only contain the desired deltas.
The use of the "Development" environment should be avoided in production environments, as this activates additional debugging functionalities.
Explicit configuration
If required, additional configuration files can be specified in the command line via the argument "settings=...", "-settings=...", "--settings=..." or "/settings=...". This will check if the specified configuration file exists and will print an error message if necessary. This check can be disabled by appending a question mark to the file name. Thus also optional configuration files can be specified in the command line.
The default configuration as well as the installation-specific configuration and the environment-specific configuration(s) are still taken into account. The explicit configurations in this case only have to contain the desired deltas.
Structure of the configuration file
The configuration file for the Connect Server is a JSON file with a JSON object as the root element. The corresponding child elements are described in the following chapters.
The AllowedHosts section (JSON value of type String).
This section allows you to restrict the host names to which the web server can be bound. Thus, access via unwanted host names or via IP addresses can be prevented. Multiple values can be separated by a semicolon. For more information, see the following link:
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?view=aspnetcore-3.1#host-filteringExample
... "AllowedHosts": "connect.mycompany.com;localhost", ...
The Debug section (JSON object)
This section contains settings for error analysis.
The section HttpLogging (JSON Object)
In this section, logging of incoming and outgoing HTTP traffic can be enabled. Please note that a considerable amount of data can be written to the logs when this is done and that logging has a noticeable impact on the performance of the overall system. The functionality should only be enabled if the target of the logging is a file or the console. The following values can be stored here:
Property | Type | Function |
Enabled | Boolean | This option enables or disables logging of incoming from outgoing HTTP traffic. Since this functionality can also be enabled or disabled at runtime via the GUI if required, it is recommended to leave this preset at the value "false". |
Include | Array with values of type String | This value contains a list of regular expressions. Only URIs that match one of the regular expressions listed here are included in the logging. If this value is not defined, all URIs are generally included in the logging. |
Exclude | Array with values of type String | This value contains a list of regular expressions. Only URIs that do not match one of the regular expressions listed here will be considered for logging. If this value is not defined, no URIs will be excluded from logging. |
ForceHexDump | Boolean | If this value is not defined or is set to false, the Connect Server decides, based on the content type, to what extent the content of an HTTP message is displayed as text or as a hexdump. If this value is set to true, the content of HTTP messages is forced to be displayed as a hexdump (regardless of the content). |
The EnableBackgroundExceptions section (JSON value of type Boolean).
This value controls the handling of exceptions that occur during background processing. If possible, this option should not be defined or set to the value false. The value true only makes sense during debugging or within unit tests.
Example
...
"Debug": {
"HttpLogging": {
"Enabled": false,
"Include": [
".*"
],
"Exclude": [
"^(http|https)://[^/]+/_content/",
"^(http|https)://[^/]+/_framework/",
"^(http|https)://[^/]+/api/",
"^(http|https)://[^/]+/css/",
"^(http|https)://[^/]+/font/",
"^(http|https)://[^/]+/js/",
"^(http|https)://[^/]+/lib/",
"^(http|https)://[^/]+/[sS]erver/",
"^(http|https)://[^/]+/$",
"^(http|https)://[^/]+/favicon.ico$",
"^(http|https)://[^/]+/index.html$",
"^(http|https)://[^/]+/[sS]erver$",
"^(http|https)://[^/]+/[^/]+.css$"
],
"ForceHexDump": false
},
"EnableBackgroundExceptions": false
},
...
The Endpoints section (JSON Array)
This section is used to configure the integrated web server and contains an array with information about the enpoints. The individual elements of the array have the following properties:
Property | Type | Function |
Uri | String | This property contains the URI of the desired endpoint. Schema and host are mandatory, the specification of a port is optional. If no port is specified, the respective default ports (80 for HTTP and 443 for HTTPS) are used. If no IP address is specified as the host, the specified name is converted to an IP address using DNS lockup. The IP addresses 0.0.0.0 or * represent all available IP addresses of the server. |
Certificate | JSON object | This property is only required when using HTTPS. The JSON object specified here requires the following properties: Source File UserStore SystemStore Store Path Name Password SerialNumber (or Serial or SerialNo) SubjectName (or Subject) Selection criterion: The subject of the certificate to be used. Thumbprint The selection criteria are only evaluated if the certificate is to be read from a certificate store. Not all possible selection criteria have to be specified, but the certificate search must lead to a unique result. If several certificates meet the selection criteria, the web server cannot be started. The use of multiple certificates on the same endpoint is currently not supported. If an endpoint can be reached via different hostnames, these must be listed in a certificate. Wildcard certificates are supported without restrictions. |
Example
...
"Endpoints": [
{
"Uri": "http://*:80"
},
{
"Uri": "https://*:443",
"Certificate": {
"Source": "File",
"Path": "C:\Certificates",
"Name": "Certificate.pfx",
"Password": "CertificatePassword"
}
},
{
"Uri": "https://192.168.100.100:444",
"Certificate": {
"Source": "Store",
"SerialNumber": "0123456789"
}
}
],
...
The "Frontend" section (JSON object)
The SupportedLanguages section (JSON array with string type values).
This section defines the languages that can be selected in the dialog for maintaining language-dependent texts. Both generic language keys (such as "en" or "de") and area-specific language keys (such as "en-US", "en-UK", "de-DE" or "de-AT") are supported.
Example
...
"Frontend": {
"SupportedLanguages": [ "de", "en", "es", "fr", "it", "nl" ]
},
...
The Logging section (JSON object)
This section contains another JSON object called "LogLevel" which defines the level of detail of the log output. The property "Default" contains the default setting, other properties may define different settings for specific .NET namespaces. The following values are supported for the level of detail: "Trace", "Debug", "Information", "Warning" and "Error".
Example
...
"Logging": {
"LogLevel": {
"Default": "Information",
"IdentityServer4": "Warning",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
...
If required, the level of detail can be specified depending on the logging target (console, event log, etc.). Further information can be found under the following link:
https://docs.microsoft.com/en-us/dotnet/core/extensions/loggingThe Security section (JSON object)
The IpFiltering section (JSON object)
In this section, access to the Connect Server can be restricted to specific IP addresses. The following values can be stored here:
Property | Type | Function |
Enabled | Boolean | This option enables or disables filtering by IP addresses. |
Blacklist | Array with values of type String | This value contains a list of IP addresses or networks (CIDR addresses) that should be excluded from accessing the web server. If the blacklist is empty or not specified, only the whitelist is considered. |
Whitelist | Array with values of type String | This value contains an explicit listing of the IP addresses or networks (CIDR addresses) that are allowed to access the web server (if they are not included in the blacklist). If the whitelist is empty or not specified, only the blacklist is considered (if available). |
The JsonEncryptionKey section (JSON object)
To avoid passwords in plain text, they can be encrypted before being stored in files or in the database. The exact behavior is defined by the following properties:
Property | Type | Function |
Enabled | Boolean | This option enables or disables partial encryption for objects stored as JSON. If this option is not specified, encryption of passwords is disabled. |
Key | String | This value is included in the generation of the key so that only passwords can be decrypted only from Connect Servers where the same value is stored. If this value is not defined or empty, a default key stored in the application is used. Please note that after changing this key, all stored passwords must be re-entered. |
Example
...
"Security": {
"IpFiltering": {
"Enabled": false,
"Blacklist": [
],
"Whitelist": [
"::1",
"127.0.0.1",
"192.168.0.0/16"
]
},
"JsonEncryption": {
"Enabled": true,
"Key": "MySecretKey!"
}
},
...
The Workspace section (JSON object)
This section contains configuration data for the connection to a specific data store (workspace). The following values can be stored here:
Property | Type | Function |
Id | String | Contains a unique ID to identify the workspace. |
DataSource | JSON object | Contains the information for connecting to the database with users, runtime information and, depending on the configuration, the Connect objects. This object supports the following properties: Name DbType ConnectionString RetentionPeriods OpenContexts CompletedContexts |
ConnectObjects | JSON object | Defines the behavior when accessing Connect objects. This object supports the following properties: Provider RootPath |
DbLogging | JSON object | Additional options for logging database access can be defined here. This object supports the following properties: LogLevel EnableSensitiveDataLogging EnableDetailedErrors |
Example
...
"Workspace": {
"Id": "connect",
"DataSource": {
"DbType": "SqlServer",
"ConnectionString": "Data Source=.\\SQLEXPRESS;Initial Catalog=connect;Integrated Security=True;Connect Timeout=30;Encrypt=False;TrustServerCertificate=False;ApplicationIntent=ReadWrite;MultiSubnetFailover=False"
"RetentionPeriods": {
"OpenContexts": 3,
"CompletedContexts": 1
}
},
"ConnectObjects": {
"Provider": "Database",
"RootPath": ""
},
"DbLogging": {
"LogLevel": "Warning",
"EnableSensitiveDataLogging": false,
"EnableDetailedErrors": true
}
}
...
Example configuration
The following example shows the possible Connect-specific configuration settings:
{
"AllowedHosts": "*",
"Debug": {
"HttpLogging": {
"Enabled": false,
"Include": [
".*"
],
"Exclude": [
"^(http|https)://[^/]+/_content/",
"^(http|https)://[^/]+/_framework/",
"^(http|https)://[^/]+/api/",
"^(http|https)://[^/]+/css/",
"^(http|https)://[^/]+/font/",
"^(http|https)://[^/]+/js/",
"^(http|https)://[^/]+/lib/",
"^(http|https)://[^/]+/[sS]erver/",
"^(http|https)://[^/]+/$",
"^(http|https)://[^/]+/favicon.ico$",
"^(http|https)://[^/]+/index.html$",
"^(http|https)://[^/]+/[sS]erver$",
"^(http|https)://[^/]+/[^/]+.css$"
],
"ForceHexDump": false
}
},
"Endpoints": [
{
"Uri": "http://*:80"
}
],
"Frontend": {
"SupportedLanguages": [ "de", "en", "es", "fr", "it", "nl" ]
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"Security": {
"IpFiltering": {
"Enabled": false,
"Blacklist": [
],
"Whitelist": [
"::1",
"127.0.0.1",
"192.168.0.0/16"
]
},
"JsonEncryption": {
"Enabled": true,
"Key": "MySecretKey!"
}
},
"Workspace": {
"Id": "connect",
"DataSource": {
"DbType": "sqlite",
"RetentionPeriods": {
"OpenContexts": 14,
"CompletedContexts": 7
}
},
"ConnectObjects": {
"Provider": "filesystem",
"RootPath": "Workspaces/connect"
},
"DbLogging": {
"LogLevel": "Warning",
"EnableSensitiveDataLogging": false,
"EnableDetailedErrors": true
}
}
}
Override configuration settings
The configuration settings stored in the JSON files can be overridden if necessary. This approach makes sense especially when automating Docker-based environments.
Override with the help of environment variables
To override the value of a configuration setting an environment variable can be defined with the prefix "DOTNET_" or "ASPNETCORE_" followed by the path of the setting in the JSON file. A double underscore (__) should be used as path separator here.
You can find more information on this topic at the following link:
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-5.0Example:
SET DOTNET_Logging__LogLevel__Default=Debug
Override via the command line
If required, configurations can also be overridden using key-value pairs as command line parameters. The name here corresponds to the path of the setting, using the ":" character as the path separator. Key-value pairs can be specified in various ways:
<name1>=<value1> <name2>=<value2> .../<name1> <value1> /<name2> <value2> ...--<name1> <value1> --<name2> <value2> ...
You can find more information on this topic at the following link:
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-5.0Example:
GalileoGroup.Connect.Server.exe Logging:LogLevel:Default=Debug