Overview

The DeepHub® can be configured in two different ways. Listed from most to least specific, these ways are:

1. Environment variables
2. Configuration file

Options provided multiple times via different ways will be overridden according to the aforementioned specificity. Additionally there can be a license_key YAML file stored in the data directory of the Docker container that will override the license_key. It can be added via the license/key REST API.

The configuration file is a YAML based file, stored in the data directory of the Docker container (or in the directory provided with config_path). The configuration is loaded once on startup. For every configuration option the respective environment variable is fully capitalized and prepended with DEEPHUB, separated by an underscore.

As an example, license_key becomes DEEPHUB_LICENSE_KEY.

Basic Setup

config_path

The directory used by DeepHub to store the database and configuration files. This directory needs read and write permissions.

• Expected value type: string
• Default: /data

port

The port on which to listen for incoming connections. Note that the server is capable to upgrade requests, thus only a single port is used by the server for HTTP, HTTPS and Websocket (both plain and TLS).

• Expected value type: number
• Default: 8081

host

The servers host name.

• Expected value type: string
• Default: localhost

license_key

The license key used to authenticate this DeepHub instance with the license server. This parameter is mandatory!

• Expected value type: string
• Default: not set
• Example: BE7B7835-F2B3-4F40-90C7-458AC95D4859

Advanced Setup

license_server_address

The address at which the Flowcate license server is reachable.

• Expected value type: string
• Default: https://license.deephub.io

license_server_port

The port at which the Flowcate license server is reachable.

• Expected value type: string
• Default: 443

client_max_body_size

The maximum http body size accepted by the DeepHub in a request in KiB.

• Expected value type: number
• Default: 10000

doc_root

The document root directory of the web server.

• Expected value type: string
• Default: .

num_threads

The number of worker threads to spawn for HTTP(s) and websocket connections.

• Expected value type: number
• Default: Number of available CPU cores.

calculate_collisions_default

Specifies the default behavior for calculating collisions for Trackables which do not have the property calculate_collisions set. If this is set to false, Trackables without the property will be handled as if it was set to false.

• Expected value type: boolean
• Default: true

record_path

A path to the session record. When this path is set, the server will write all requests to the specified file for later playback. Note: This functionality is meant for demonstration and testing purposes. Do not use this in production mode, as it will slow down overall operation of the server and keep the recorded file growing over time.

• Expected value type: string
• Default: Not set

playback_path

A path to a file containing a recorded session. The session will be played back in a loop.

• Expected value type: string
• Default: Not set

playback_speed

The speed at which the recorded session will be played back.

• Expected value type: number
• Default: 1.0

cors

Wether the server should accept cross site origin requests (cors).

• Expected value type: boolean
• Default: true

severity_level

In order to be able to control the verbosity of our logging, we differentiate between the following six severity levels:

• Fatal: error that is fatal for the application
• Error: error that is fatal for the current operation
• Warning: error that is recoverable
• Info: state of the program
• Debug: diagnostic information of error-prone code paths
• Trace: describes the complete program flow

The DeepHub will log all messages from the chosen severity level and higher. If you specify Error, you will get messages of type Error and Fatal. An exemplary logging output looks like the following:

I20200630 15:21:45.783285 104390656 HubController.cpp:425] This is an info message
E20200630 15:21:45.784117 104390656 HubController.cpp:426] This is an error message

and correspond to this pattern

[Lyyyymmdd hh:mm:ss.uuuuuu thread-id file:line] msg...

where the fields are defined as follows:

Field	Explanation
L	A single character, representing the log level (eg 'I' for INFO)
yyyy	The year
mm	The month (zero padded; ie May is '05')
dd	The day (zero padded)
hh:mm:ss.uuuuuu	Time in hours, minutes and fractional seconds
thread-id	The space-padded thread ID as returned by GetTID() (this matches the PID on Linux)
file	The file name
line	The line number
msg	The user-supplied message

Note: Even though we can specify six different severity levels, the output will only mark four different severity levels (Fatal, Error, Warning, Info). If the severity level is set accordingly, Trace and Debug messages will also appear as Info in the output.

• Expected value type: string
• Default: Info

Authentication, Authorization, and Encryption of Traffic

require_authorization

Whether authorization is required or not. If authorization is required openid_config_url must be configured, and the optional parameters authserver_public_key_path and verify_authserver are strongly advised to be set for a production environment.

• Expected value type: boolean
• Default: false

openid_config_url

The OpenID configuration URL which contains information about OpenID authentication and authorization endpoints. Check your OpenID server documentation for details. This setting is mandatory when require_authorization is used.

• Expected value type: string
• Default: not set
• Example: http://127.0.0.1:8080/auth/realms/omlox/.well-known/openid-configuration

openid_client_name

The client name of the DeepHub. The parameter is mandatory when using OpenID, in order to verify client token claims (mandatory by OpenID standard). Please refer to "API Security.md" for an audience claim mapping example.

• Expected value type: string
• Default: not set
• Example: deephub-service

openid_client_secret

The OpenID client secret to be used for the DeepHub service.

• Expected value type: string
• Default: not set

authserver_public_key_path

The path to the PEM file containing the public key of the authentication server. This public key is used to verify requests to the OpenID config service.

• Expected value type: string
• Default: not set

verify_authserver

Whether to verify the OpenID server's certificate. This should be set to true in production mode.

• Expected value type: boolean
• Default: false

public_key_path

Path to the PEM file containing the server's public key required for secure communication over HTTPS / wss. This parameter is mandatory when using force_https.

• Expected value type: string
• Default: not set

private_key_path

Path to the PEM file containing the server's private key required for secure communication over HTTPS / wss. This parameter is mandatory when using force_https.

private_key_password

The private key's password.

• Expected value type: string
• Default: not set

dh_params_path

Path to the DH params file for secure communication over HTTPS / wss.

• Expected value type: string
• Default: not set

force_https

Wether the server should enforce to use HTTPS / wss (secure websocket) and disallow non-encrypted requests. Requires public and private certificates.

• Expected value type: boolean
• Default: false

Database Tuning

persist_locations

Whether the server should write last locations and motions to the database. Note: When enabled, server performance might decrease. See db_fast_writes for mitigating some of the performance loss.

• Expected value type: boolean
• Default: true

db_fast_writes

Whether the server should merge multiple location and motion updates for the same entity into a single database update. Only works if persist_locations is enabled. This option can significantly increase the rate at which location updates can be processed. As a side effect, API calls for such updates can not report database errors immediately (e.g. lost connection). Accepted and confirmed updates will be retried und submitted once the error is resolved. A further explanation of the implications to data consistency can be found here.

• Expected value type: boolean
• Default: true

db_type

The database type the DeepHub uses. Supported values are sqlite and cassandra.

• Expected value type: string
• Default: sqlite

cassandra_hosts

List of host names for the cassandra cluster.

• Expected value type: string
• Default: localhost
• Example:

# In the config file, a YAML array is expected
cassandra_hosts:
  - '127.0.0.1'
  - 'localhost'

# As an environment variable, a comma separated list of hosts is expected:
DEEPHUB_CASSANDRA_HOSTS="localhost,127.0.0.1"

cassandra_port

Port of the cluster.

• Expected value type: number
• Default: 9042

cassandra_username

Username used to authenticate to the Cassandra cluster. This user needs full access to the DeepHub related namespaces.

• Expected value type: string
• Default: not set

cassandra_password

Password used to authenticate to the Cassandra cluster.

• Expected value type: string
• Default: not set

cassandra_keyspace

Base name of the Cassandra keyspace. DeepHub will use two namespaces, one named as provided by this option, and a second one appended with "_stats". For the default namespace this gives the following to namespaces: "deephub", "deephub_stats". The user provided as cassandra_username needs full access to both namespaces.

• Expected value type: string
• Default: deephub

cassandra_connect_timeout

Connection timeout, in milliseconds.

• Expected value type: number
• Default: 5000

cassandra_request_timeout

Request timeout, in milliseconds.

• Expected value type: number
• Default: 12000

cassandra_read_consistency

In order to be able to control the read consistency the DeepHub supports the following Cassandra consistencies:

• UNKNOWN
• ANY
• ONE
• TWO
• QUORUM
• ALL
• LOCAL_QUORUM
• EACH_QUORUM
• SERIAL
• LOCAL_SERIAL
• QUORUM
• LOCAL_ONE

• Expected value type: string
• Default: LOCAL_QUORUM

cassandra_write_consistency

In order to be able to control the write consistency the DeepHub supports the following Cassandra consistencies:

• UNKNOWN
• ANY
• ONE
• TWO
• QUORUM
• ALL
• LOCAL_QUORUM
• EACH_QUORUM
• SERIAL
• LOCAL_SERIAL
• QUORUM
• LOCAL_ONE

• Expected value type: string
• Default: LOCAL_QUORUM

cassandra_keep_alive

Cassandra connection keep-alive interval in seconds.

• Expected value type: number
• Default: 7200

cassandra_latency_aware_routing

Whether Cassandra latency aware routing is enabled.

• Expected value type: boolean
• Default: true

cassandra_token_aware_routing

Whether Cassandra token aware routing is enabled.

• Expected value type: boolean
• Default: true

cassandra_load_balancing

Whether Cassandra load balancing is enabled.

• Expected value type: boolean
• Default: true

cassandra_io_threads

Number of Cassandra IO threads.

• Expected value type: number
• Default: 1

cassandra_replication_strategy

Cassandra replication strategy.

• Expected value type: string
• Default: {'class': 'SimpleStrategy', 'replication_factor': '1'}

cassandra_use_tls

Whether the Cassandra connection enforces TLS.

• Expected value type: boolean
• Default: false

cassandra_tls_pem

Path to the PEM file for a TLS enabled connection to Cassandra.

• Expected value type: string
• Default: not set

cassandra_rate

The targeted throughput to the Cassandra database in kB/s. This is a combined value for read and write operations, though, during operation DeepHub will almost exclusively write to the database. The size of the database operations can only be estimated, which is why this throughput is only approximate.

• Expected value type: number
• Default: 0 (unlimited)

cassandra_burst_size

Shaping parameter for the throughput to the Cassandra database in kB. This parameter allows to momentarily exceed the limit set by cassandra_rate. The DeepHub will send up to this much data to the database without rate limitation before throttling. The DeepHub will allow transactions in cases where the size of a single transaction exceeds this parameter.

• Expected value type: number
• Default: 10000

MQTT

mqtt_address

The address used to connect to an MQTT broker.

• Expected value type: string
• Default: not set

mqtt_port

The port used to connect to an MQTT broker.

• Expected value type: string
• Default: 1883

mqtt_user

Username used to authenticate to the MQTT broker.

• Expected value type: string
• Default: not set

mqtt_password

Password used to authenticate to the MQTT broker.

• Expected value type: string
• Default: not set

uns_root

The root path used for all Unified Namespace messages.

• Expected value type: string
• Default: not set

Connecting ISO-24730 RTLS systems

iso_24730_connections

A list of configurations for connections to ISO-24730 RTLS systems. The following properties are used for a connection:

host - The host to connect to.

port - The port used for the connection.

type - The location provider type reported used for location updates from this system.

zone_id or foreign_id - The identifier of a zone with which all location updates from this system will be associated with. Exactly one of these two ids must be provided.

• Expected value type: YAML list
• Default: not set

Example:

# Configuration file:
- host: server
  port: 4000
  type: uwb
  zone_id: FDE56BB8-64B1-4B95-ADEB-AB189EE937FE
- host: otherserver
  port: 4000
  type: gps
  foreign_id: some_id

# environment variable:
[
  {
    'host': server,
    'port': 4000,
    'type': uwb,
    'zone_id': FDE56BB8-64B1-4B95-ADEB-AB189EE937FE,
  },
  { 'host': otherserver, 'port': 4000, 'type': gps, 'foreign_id': some_id },
]

Using a proxy server for outside communication

DeepHub allows for https communication via a proxy server which supports the HTTP CONNECT method. This primarily concerns the access to the license server and OpenID server. DeepHub thereby respects the environment variables https_proxy and no_proxy with the following syntax and limitations:

• The environment variables have to be lower case
• The proxy server must be the root target of its domain
• Login credentials must be provided as username:password in the https_proxy variable
• The exclusion via no_proxy is based on a comma separated list of sub.domain strings. IP address and range based filtering are currently not supported.
• Traffic to localhost/0.0.0.0/127.0.0.1 will not be routed through the proxy.

The following is an example configuration where a proxy server is used to access the license server, while the OpenID server is accessed directly:

# Route outgoing traffic via this proxy server
https_proxy="username:password@local.proxy.server:80"

# Access the OpenID server directly
no_proxy="local.openid.server:443"

Preparing self signed certificates for development

Below is an example using OpenSSL to create self-signed certificates for enabling HTTPS for development and testing purpose.

# Create public key cert.pem and private key key.pem
openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 10000 -out cert.pem -subj "/C=DE/ST=BW/L=Heidelberg/O=Flowcate/CN=www.flowcate.com"

# Create DH Params
openssl dhparam -out dh.pem 2048

Place the files inside the DeepHub's data directory, and edit the hub_config.yaml file accordingly. Example configuration using above mentioned file names:

port: 8081
host: localhost
force_https: false
public_key_path: cert.pem
private_key_path: key.pem
dh_params_path: dh.pem

Note: Setting force_https to false will accept both HTTP and HTTPS requests. For security reasons this should be changed to true in production.