Component Settings

Logging levels, Network settings, and Authorization parameters

Timebase 1.0 components stored their settings in the default appsettings.json file in the app execution directory. This was not ideal for Docker containers since these settings could never be persisted to an external Docker volume.

For Timebase 1.1, we have surfaced these settings to a separate settings.config file that you can now persist to an external Docker volume.

The only settings that can be set in the original appsettings.json file are the path locations, which, depending on the component, look like this:

{
"Settings": "\Collector\Settings",
"Config": "\Collector\Config",
"Data": "\Collector\Data",
"Logs": "\Collector\Logs"
}

These path settings are commented out so that the default path locations are used:

Windows - C:\ProgramData\Flow Software\Timebase\<Component>\Logs

Docker - \<Component>\Logs

Where is settings.config?

Each Timebase component requires the JSON file settings.config to configure its logging levels, network settings, and authentication parameters.

By default, this file can be found at the following paths:

Windows - C:\ProgramData\Flow Software\Timebase\<Component>\Settings

Docker - \<Component>\Settings (which should be in a Docker volume)

What does settings.config contain?

The settings.config file contains the following:

{
  "DetailedErrors": true,

  "Serilog": {
    "MinimumLevel": {
      "Default": "Warning",
      "Override": {
        "Timebase.Pulse": "Information"
      }
    }
  },

  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:4541"
      } ,
       "Https": {
        "Url": "https://0.0.0.0:4542",
        "Certificate": { 
          "Subject": "localhost", 
          "Store": "Root", 
          "Location": "CurrentUser", 
          "AllowInvalid": "true" 
      } 
     }
    }
  }
}

Detailed Errors

"DetailedErrors": true,

Set this to true to display more comprehensive error messages, which will help you and our support team troubleshoot problems more effectively.

Serilog logging

This section controls the logging behavior for different namespaces within the component.

"Serilog": {
    "MinimumLevel": {
      "Default": "Warning",
      "Override": {
        "Timebase.Pulse": "Information"
      }
    }
  },

The Default logging level is set to Warning to avoid flooding the logs with unnecessary messages. Relevant namespaces, like Timebase.Pulse or Timebase.Historian, can override the default Warning. We have set these to Information to provide informative logs relevant to the component.

Other log levels include:

Error, Warning, Information, Debug, Verbose

Logs can be viewed in various places:

Console
Status page on the component's UI
Text files in the component's Log path

Kestrel network settings

When the Timebase components run, they communicate with each other, and external client apps, via a Web API. The startup of this Web API is controlled by these Kestrel settings:

  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:4541"
      } ,
       "Https": {
        "Url": "https://0.0.0.0:4542",
        "Certificate": { 
          "Subject": "localhost", 
          "Store": "Root", 
          "Location": "CurrentUser", 
          "AllowInvalid": "true" 
      }
  }

Endpoints: Defines the addresses where the Web API will listen for network requests
- "Http": { "Url": "http://0.0.0.0:4541" }: This means that the Web API will listen for HTTP requests on all network addresses (0.0.0.0) on port 4541. This makes the application accessible from any IP address.
Endpoints: How to add an HTTPS endpoint.

When securing your Timebase components using Pulse, information passed between Timebase components needs to be encrypted. This requires an HTTPS endpoint for Transport Layer Security (TLS) and an accompanying certificate to encrypt message contents.

The certificate is stored on the server, and Kestrel is configured to use it. In production, a TLS certificate must be explicitly configured. At a minimum, a default certificate must be provided.

  "Kestrel": {
    "Endpoints": {
      "Https": { 
        "Url": "https://0.0.0.0:4512", 
        "Certificate": { 
          "Subject": "<subject; required>", 
          "Store": "<certificate store; required>", 
          "Location": "<location; defaults to CurrentUser>", 
          "AllowInvalid": "<true or false; defaults to false>" 
      }
    }
  }

Endpoint names are case-insensitive. For example, HTTPS and Https are equivalent.
The Url parameter is required for each endpoint.
The Certificate section is optional. If the Certificate section isn't specified, the defaults defined in Certificates:Default are used. If no defaults are available, the development certificate is used. If there are no defaults and the development certificate isn't present, the server throws an exception and fails to start.
The Certificate section supports multiple certificate sources. Please see Kestrel Certificate Settings for other examples on how to configure certificate locations
Any number of endpoints may be defined in Configuration, as long as they don't cause port conflicts.

Authorization Settings

Depending on the Timebase component, the following authorization settings are required:

Pulse

Being an OAuth 2.0 and OpenIDConnect Identity Provider, Pulse issues Tokens to its clients. These tokens require an Issuer for validation. When Pulse creates and issues a new token, it sets the token's issuer. When a client then uses that token to authenticate itself or a user, Pulse validates the token's issuer to make sure it has not been provided by a different Identity Provider.

It is for this reason that you need to provide a unique custom Issuer to secure your components.

"Auth": {
  "Issuer": "https://<YourCustomIssuer>"
}

The issuer does not have to be a resolvable Url, but rather an entity "name" in the form of a Url, e.g. auth.mycompanyname.com

Collector, Historian, and Explorer

When securing your Timebase components, you will need to configure these settings:

"Auth": {
  "Enabled": true,
  "IdP": {
    "Host": "localhost",
    "Port": 4542,
    "UseTls": true
  },
  "ClientId": "<Component>",
  "ClientSecret": "<YourComponentClientSecret>"
}

Enabled - true or false. Set to true if you want to secure your component. This setting is useful if you want to turn authentication off during testing, and not have to delete the whole Auth section.
IdP - "Identity Provider" - in this case the Timebase IdP is the Pulse component. You will set the Host, Port, and UseTls appropriately to access Pulse.
ClientId - must reference a configured client in Pulse
ClientSecret - must be the Client Secret of the specified ClientId