Page Comparison

...

General

Die Konfiguration des Connect Servers erfolgt in der Regel mit Hilfe von JSON-Dateien, welche sich im Installationsverzeichnis der Applikation befinden. In Spezialfällen ist eine Übersteuerung über Umgebungsvariablen oder über Kommandozeilenparameter möglich.

Standardkonfiguration

Die Standardkonfiguration befindet sich in der Datei “appsettings.Default.json”. Diese Datei sollte nicht direkt verändert werden, da diese Änderungen ggf. durch ein späteres Upgrade überschrieben werden.

Installationsspezifische Konfiguration

Soll eine installationsspezifische Konfiguration angelegt werden, so empfiehlt es sich die Datei „appsettings.Default.json“ in eine Datei mit dem Namen “appsettings.json” zu kopieren. Diese Datei wird bei einem eventuellen Upgrade nicht überschrieben, somit bleiben die hier hinterlegten Konfigurationseinstellungen bestehen.

Die Standardkonfiguration wird hierbei weiterhin berücksichtigt. Die installationsspezifische Konfiguration muss daher nur die gewünschten Deltas enthalten.

Umgebungsspezifische Konfiguration

Wird ein Installationsverzeichnis in verschiedenen Umgebungen genutzt (z. B. in einem Template für Container), so können umgebungsspezifische Konfigurationen angelegt werden. Hierfür wird die Datei „appsettings.Default.json“ in eine Datei mit dem Namen “appsettings.{environment}.json” kopiert ({environment} ist hierbei durch den Namen der entsprechenden Umgebung zu ersetzen).

In diesem Szenario kann die Umgebung zur Laufzeit mit Hilfe der Umgebungsvariablen “ASPNETCORE_ENVIRONMENT” spezifiziert werden. In der Regel werden hier die Werte “Development”, “Staging” und “Production” verwendet, der Standardwert ist “Production”.

Die Standardkonfiguration sowie ein evtl. vorhandene installationsspezifische Konfiguration werden weiterhin berücksichtigt. Die umgebungsspezifischen Konfigurationen müssen daher nur die gewünschten Deltas enthalten.

Die Verwendung der Umgebung “Development” sollte in Produktionsumgebungen vermieden werden, da hierbei zusätzliche Debugging-Funktionalitäten aktiviert werden.

Explizite Konfiguration

Bei Bedarf können in der Kommandozeile über das Argument “settings=…”, “-settings=…”, “--settings=…” oder “/settings=…” zusätzliche Konfigurationsdateien angegeben werden. Hierbei wird geprüft, ob die angegebene Konfigurationsdatei vorhanden ist und gegebenenfalls eine Fehlermeldung ausgegeben. Diese Prüfung kann deaktiviert werden, indem an den Dateinamen ein Fragezeichen angehängt wird. Dadurch lassen sich auch optionale Konfigurationsdateien in der Kommandozeile spezifizieren.

Die Standardkonfiguration sowie die installationsspezifische Konfiguration und die umgebungsspezifische(n) Konfiguration(en) werden weiterhin berücksichtigt. Die expliziten Konfigurationen müssen in diesem Fall nur die gewünschten Deltas enthalten.

Struktur der Konfigurationsdatei

Die Konfigurationsdatei für den Connect Server ist eine JSON Datei mit eine JSON Objekt als Wurzelelement. Die entsprechenden untergeordneten Elemente werden in den folgenden Kapiteln beschrieben.

Der Abschnitt „AllowedHosts“ (JSON Wert vom Typ String)

Dieser Abschnitt erlaubt die Einschränkung der Host-Namen, an welche der Webserver gebunden werden kann. Somit lässt sich der Zugriff über unerwünschte Hostnamen oder über IP-Adressen verhindern. Mehrere Werte können durch ein Semikolon getrennt werden. Weitere Informationen finden Sie unter folgendem Link:

...

Beispiel

...
  "AllowedHosts": "connect.mycompany.com;localhost",
...

Der Abschnitt „Debug“ (JSON Objekt)

Dieser Abschnitt enthält Einstellungen zur Fehleranalyse.

Der Abschnitt HttpLogging (JSON Objekt)

In diesem Abschnitt kann die Protokollierung des eingehenden und ausgehenden HTTP-Verkehrs aktiviert werden. Bitte beachten Sie, dass hierbei eine erhebliche Datenmenge in die Protokolle geschrieben werden kann und dass die Protokollierung spürbare Auswirkungen auf die Performance des Gesamtsystems hat. Die Funktionalität sollte nur dann aktiviert werden, wenn das Ziel der Protokollierung eine Datei oder die Konsole ist. Hier können folgende Werte hinterlegt werden:

...

Eigenschaft

...

Typ

...

Funktion

...

Enabled

...

Boolean

...

Diese Option aktiviert oder deaktiviert die Protokollierung des eingehenden aus ausgehenden HTTP-Verkehrs. Da diese Funktionalität bei Bedarf auch zur Laufzeit über die GUI aktiviert oder deaktiviert werden kann, empfiehlt es sich, diese Voreinstellung auf dem Wert “false” zu belassen.

...

Include

...

Array mit Werten vom Typ String

...

Dieser Wert enthält eine Auflistung von Regular Expressions. Nur URIs, welche zu einer der hier aufgelisteten Regular Expressions passen, werden bei der Protokollierung berücksichtigt. Wird dieser Wert nicht definiert, so werden generell aller URIs in die Protokollierung miteinbezogen.

...

Exclude

...

Array mit Werten vom Typ String

...

Dieser Wert enthält eine Auflistung von Regular Expressions. Nur URIs, welche nicht zu einer der hier aufgelisteten Regular Expressions passen, werden bei der Protokollierung berücksichtigt. Wird dieser Wert nicht definiert, so werden keine URIs von der Protokollierung ausgeschlossen.

...

ForceHexDump

...

Boolean

...

Ist dieser Wert nicht definiert oder auf false gesetzt, so entscheidet der Connect Server, anhand des Content Types inwiefern der Inhalt einer HTTP-Nachricht als Text oder als Hexdump angezeigt wird. Wird dieser Wert auf true gesetzt, wird die Darstellung des Inhalts von HTTP-Nachrichten als Hexdump erzwungen (unabhängig vom Inhalt).

Der Abschnitt EnableBackgroundExceptions (JSON Wert vom Typ Boolean)

Dieser Wert steuert den Umgang mit bei der Hintergrundverarbeitung auftretenden Exceptions. Diese Option sollte nach Möglichkeit nicht definiert oder auf den Wert false gesetzt werden. Der Wert true macht nur während des Debuggings oder innerhalb von Unit Tests Sinn.

Beispiel

...

...

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.

Default 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=..." 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.

Priority of the configuration types

If multiple configurations are available, they are applied in the following order:

1. Default configuration (appsettings.Default.json)

2. Environment-specific configuration (appsettings.{environment}.json)

3. Installation-specific configuration (appsettings.json)

4. Explicit configuration

5. Override via environment variables

6. Override via command line

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:

...

Example

...
  "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:

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)://[^/]+/font_content/",
        "^(http|https)://[^/]+/js_framework/",
        "^(http|https)://[^/]+/libapi/",
        "^(http|https)://[^/]+/[sS]ervercss/",
         "^(http|https)://[^/]+/$font/",
        "^(http|https)://[^/]+/favicon.ico$js/",
        "^(http|https)://[^/]+/index.html$lib/",
        "^(http|https)://[^/]+/[sS]erver$erver/",

        "^(http|https)://[^/]+/$",
        "^(http|https)://[^/]+/favicon.css$ico$",
        "^(http|https)://[^/],
 +/index.html$",
    "ForceHexDump": false   "^(http|https)://[^/]+/[sS]erver$",
        "^(http|https)://[^/]+/[^/]+.css$"
      ],
      "ForceHexDump": false
    },
    "EnableBackgroundExceptions": false
  },
  
...

...

The Endpoints section (JSON Array)

Dieser Abschnitt dient zur Konfiguration des integrierten Webservers und enthält ein Array mit Informationen zu den Enpoints. Die einzelnen Elemente des Arrays besitzen folgende Eigenschaften:

...

Eigenschaft

...

Typ

...

This section is used to configure the integrated web server and contains an array with information about the endpoints. The individual elements of the array have the following properties:

Beispiel

...

...

The ClientCertificates section (JSON Object)

This configuration section defines the handling of client certificates. If no client certificates are to be used, the entire section can be omitted. Currently, the following properties are supported:

The ServerCertificates section (JSON Object)

This configuration section currently contains only one property named “Bindings”. This JSON array contains the certificate bindings for the endpoint in the form of JSON objects with the following properties:

The certificate bindings are processed in the sequence defined by their array positions. The first element whose preconditions specified under "Conditions" are met or for which no preconditions have been specified will define the server certificate. Additional elements are not taken into account during processing.

It is recommended to specify a certificate without preconditions as the last element. This is then used as a fallback value.

Use of certificates

Wherever certificates can be specified, a JSON object is expected. This object supports the following properties:

The selection criteria are only evaluated if the certificate is to be read from a certificate store. Not all possible selection criteria need to be specified, but the certificate search must lead to a unique result. If several certificates fulfill all specified selection criteria and only one of them is valid, the valid certificate is used. If several valid certificates fulfill all specified selection criteria, the web server cannot be started.

Example

...
  
  "Endpoints": [
    {
      "Uri": "http://*:80"
    },
    {
      "Uri": "https://*:443",
      "ClientCertificates": {
        "Mode": "required",
        "Authentication": {
          "Enabled": true
        },
        "Validation": {
          "CheckRevokation": true,
          "Filters": {
            "SubjectRegex": "@mycompany\\.com)$"
          },
          "IntermediateCertificates": [
            {
              "Source": "UserStore",
              "Subject": "My Company's intermediate certificate",
              "Serial": "01234567890ABCDEFFEDCBA9876543210"
            }
          ],
          "TrustedClientCertificates": [
            {
              "Source": "UserStore",
              "Serial": "012301234567456789AB89ABCDEFCDEF"
            }
          ],
          "TrustedRootCertificates": [
            {
              "Source": "UserStore",
              "Subject": "My Company's root certificate",
              "Serial": "FEDCBA987654321001234567890ABCDEF"
            }
          ]
        }
      },
      "ServerCertificates": {
        "Bindings": [
          {
            "Conditions": {
              "Host": "localhost",
              "LocalNetwork": "192.168.0.0/16",
              "RemoteNetwork": "192.168.0.0/16"
            },
            "Certificate": {
              "Source": "UserStore",
              "DisplayName": "My Company's server certificate"
              "Serial": "00112233445566778899AABBCCDDEEFF"
            }
          }
        ]
      },
      "HttpProtocols": [ "http2" ],
      "SslProtocols": [ "tls1.2", "tls1.3" ],
      "HandshakeTimeout": 10
    },
    {
      "Uri": "https://192.168.100.100:444",
      "Certificate": {
        "Source": "Store"File",
        "Path": "C:\Certificates",
        "Name": "Certificate.pfx",
        "SerialNumberPassword": "0123456789CertificatePassword"
      }
    }
  ],
  
...

...

The "Frontend" section (JSON

...

object)

Der Abschnitt „SupportedLanguages“ (JSON Array mit Werten vom Typ String)

Dieser Abschnitt definiert die im Dialog zur Pflege von Sprachabhängigen Texte auswählbaren Sprachen. Hierbei werden sowohl generische Sprachschlüssel (wie “en” oder “de”) als auch gebietsspezifische Sprachschlüssel (wie “en-US”, “en-UK”, “de-DE” oder “de-AT”) unterstützt.

...

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)

Dieser Abschnitt enthält ein weiteres JSON Objekte mit dem Namen “LogLevel”, welches den Detailgrad der Protokollausgaben festlegt. Hierbei enthält die Eigenschaft “Default” die Standardeinstellung, weitere vorhandene Eigenschaften definieren ggf. abweichende Einstellungen für bestimmte .NET Namensräume. Für den Detailgrad werden folgende die Werte “Trace”, “Debug”, “Information”, “Warning” und “Error” unterstützt.

...

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"
    }
  },

...

Bei Bedarf kann der Detailgrad in Abhängigkeit vom Protokollierungsziel (Konsole, Event LogIf required, the level of detail can be specified depending on the logging target (console, event log, etc.) spezifiziert werden. Weitergehende Informationen finden sie unter folgendem Link. Further information can be found under the following link:

...

...

The Security section (JSON

...

object)

...

The IpFiltering section (JSON

...

object)

In diesem Abschnitt kann der Zugriff auf den Connect Server auf bestimmte IP-Adressen beschränkt werden. Hier können folgende Werte hinterlegt werden:

...

Eigenschaft

...

Typ

...

Funktion

...

Enabled

...

Boolean

...

Diese Option aktiviert oder deaktiviert die Filterung nach IP-Adressen.

...

Blacklist

...

Array mit Werten vom Typ String

...

Dieser Wert enthält eine Auflistung der IP-Adressen oder Netzwerke (CIDR-Adressen), welche vom Zugriff auf den Webserver ausgeschlossen werden sollen. Ist die Blacklist leer oder nicht angegeben, so wird lediglich die Whitelist betrachtet.

...

Whitelist

...

Array mit Werten vom Typ String

...

Dieser Wert enthält eine explizite Auflistung der IP-Adressen oder Netzwerke (CIDR-Adressen), welche auf den Webserver zugreifen dürfen (sofern sie nicht in der Blacklist enthalten sind). Ist die Whitelist leer oder nicht angegeben, so wird lediglich die Blacklist betrachtet (sofern verfügbar).

Der Abschnitt “JsonEncryptionKey“ (JSON Objekt)

Um Passwörtern im Klartext zu vermeiden, können diese vor der Speicherung in Dateien oder in der Datenbank verschlüsselt werden. Das genaue Verhalten wird durch folgende Eigenschaften definiert:

...

Eigenschaft

...

Typ

...

Funktion

...

Enabled

...

Boolean

...

Diese Option aktiviert oder deaktiviert die partielle Verschlüsselung für als JSON abgelegte Objekte. Ist diese Option nicht angegeben, ist die Verschlüsselung von Passwörtern deaktiviert.

...

Key

...

String

...

Dieser Wert wird bei der Generierung des Schlüssels miteinbezogen, so dass nur Passwörter nur von Connect Servern entschlüsselt werden können, bei denen derselbe Wert hinterlegt ist. Ist dieser Wert nicht definiert oder leer, so wird ein in der Applikation hinterlegter Standardschlüssel verwendet. Bitte beachten Sie, dass nach einer Änderung dieses Schlüssels alle gespeicherten Passwörter neu eingegeben werden müssen.

...

this section, access to the Connect Server can be restricted to specific IP addresses. The following values can be stored here:

The JsonEncryption section (JSON object)

To avoid important informations (e.g. 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:

Additional sections

Additional sections are supported for special scenarios The following table lists these sections along with a linke to the corresponding documentation.

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

...

Dieser Abschnitt enthält Konfigurationsdaten für die Verbindung mit einem bestimmten Datenspeicher (Workspace). Hir können die folgenden Werte hinterlegt werden:

...

Eigenschaft

...

Typ

...

object)

This section contains configuration data for the connection to a specific data store (workspace). The following values can be stored here:

...

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
    }
  }

...

Beispielkonfiguration

...

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
    }
  }
}

Übersteuerung von Konfigurationseinstellungen

Die in den JSON-Dateien hinterlegten Konfigurationseinstellungen können bei Bedarf übersteuert werden. Diese Vorgehensweise macht insbesondere bei der Automatisierung von Docker-basierten Umgebungen Sinn.

Übersteuerung mit Hilfe von Umgebungsvariablen

Um den Wert einer Konfigurationseinstellung zu übersteuern kann eine Umgebungsvariable mit dem Präfix “DOTNET_” oder “ASPNETCORE_” gefolgt vom Pfad der Einstellung in der JSON Datei definiert werden. Als Pfadtrennzeichen sollte hier ein doppelter Underscore (__) verwendet werden.

...

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:

...

BeispielExample:

SET DOTNET_Logging__LogLevel__Default=Debug

Übersteuerung über die Kommandozeile

Bei Bedarf können Konfigurationen auch mit Hilfe von Schlüssel-Wert-Paaren als Kommandozeilenparameter übersteuert werden. Der Name entspricht hierbei dem Pfad der Einstellung, wobei das Zeichen „:“ als Pfadtrennzeichen verwendet wird. Die Angabe von Schlüssel-Wert-Paaren kann auf verschiedene Art und Weisen erfolgen:

<name1>=<wert1> <name2>=<wert2> …
/<name1> <wert1> /<name2> <wert2> …
--<name1> <wert1> --<name2> <wert2> …

Weitere Informationen zu diesem Thema finden Sie unter folgendem Link:

...

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 as follows:

<name1>=<value1> <name2>=<value2> ...

Example:

GalileoGroup.Connect.Server.exe Logging:LogLevel:Default=Debug

...