Server Configuration

The omlox™ hub server uses a YAML based configuration file stored in the data directory of the Docker container. The configuration is loaded once on startup.

Available configuration options

license_key

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

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

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

num_threads

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

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

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

[L yyyymmdd hh:mm:ss.uuuuuu threadid 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

threadid

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

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 omlox™ hub. 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

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

persist_locations

Whether the server should write last locations to the database. Note: When enabled, server performance might decrease.

Expected value type: boolean Default: true

license_server_address

The address at which the Heidelberg Mobil license server is reachable.

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

license_server_port

The port at which the Heidelberg Mobil license server is reachable.

Expected value type: string Default: 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=Heidelberg Mobil International/CN=www.heidelberg-mobil.com"

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

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

license_key: BE7B7835-F2B3-4F40-90C7-458AC95D4859
port: 8081
host: localhost
cors: true
verify_authserver: true
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.