The thingsHub's tenants are managed using the Kubernetes package manager helm. Each tenant is implemented as a helm release. Helm provides a config file format for configuring releases. Consequently, a tenant can be configured using this file format.

Heads-up notice

The base configuration of a tenant, as initially created in Creating a Tenant, should not be changed after the initial creation of the tenant. In particular, this includes the tenant's name and domain, as well as the configuration options affecting where an how data is persisted.

Example configuration file

The following is an example of a minimal config file for a thingsHub tenant.

Example Configuration File
global:
  domain: thingshub.smartmakers.de
  name: example

  security:
    service_key: <randomly-generated service key>
    admin_password: <randomly generated password>
	password_policy_regex: <user defined regular expression>
    password_help_text: <user defined help text to show on user form>

  sql:
    host: hostname.domain:port
    database: example
    user: example
    password: <the example role's passsword on the sql server>

  tls:
    enabled: true
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    key: |
      ----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
YML

Updating a tenant’s configuration

To update a tenant configuration, first modify the config file as required, then run the helm tool with the following options:

$ helm upgrade --namespace <tenant> -f <tenant>.yaml <tenant> ./th-tenant-<version>.tar.gz
...
$
CODE

General options

Name

Type

Description

global.domain

string

The base domain name, e.g. thingshub.smartmakers.de.

global.name

string

The name of the tenant.

This is concatenated with the value of global.domain to create the full domain name of the tenant.

global.logo

base64

A logo image representing the tenant, e.g. the company or project logo.

Docker Images

global.image.tag

string

The name of the tag to select for the images. Note that this is only required to override the default tag, which is identical to the chart version.

global.image.registry

string

The name of the registry from which to pull the images. Actually, not just the registry, but the parent path of the repositories that actually contain the thingsHub images.

global.image.credentials.username

string

The name used for pulling the docker images

global.image.credentials.password

string

The password used for pulling the docker images

Security (Authentication & Transport Layer Security)

global.security.service_key

string

A service key, shared by the services for  mutual authentication.

global.security.admin_password

string

The password of the admin user.

global.security.password_policy_regex

string

Contains a regular expression as a value and basically reflects the desired  complexity/security of the users passwords. In other words, when a new user is created or an existing user is updated via the REST API, the given password is checked against the defined regular expression. If such a check fails,  "HTTP 400 Bad Request" error and a message "user's password doesn't match security policy" is returned by the service. The default security policy ensures that any newly created password would match a string of any symbols with length no less than 10.

global.security.password_help_text

string

Contains the string to display on the user creation form to help users understand what the requirement for the password policy is.

global.security.system_user_ip_whitelist

string

The IP subnets from which admin login to the thingsHub is allowed. This is a comma-separated list of CIDR address ranges, e.g. 1.2.3.4/24, to allow any host in the subnet 1.2.3.x admin access to the thingsHub. Note that a personalized user with role TenantOwner can still access the system from other IP addresses. This only affects the built-in admin user.

global.tls.enabled

boolean

Enabled Transport Layer Security. This requires global.tls.cert and global.tls.key to be set.

global.tls.cert

string

The PEM-encoded TLS certificate for the domain name in <global.name>.<global.domain>. It is strongly recommended that this option is set to contain the entire certificate chain (excluding the root CA certificate) with the domain's own certificate first.

global.tls.key

string

The matching key for the certficate in global.tls.cert.

Datenbanken (PostgreSQL & InfluxDB)

global.sql.host

string

Hostname of the PostgreSQL server which hosts the tenants database.

global.sql.database

string

The database which stores the 

global.sql.user

string

The role with which the tenant shall access the PostgreSQL database.

global.sql.password

string

The password for the role with which the tenant shall access the PostgreSQL database.

global.influxdb.address

string

The hostname (with schema and port) of the InfluxDB server.

global.influxdb.user

string

The user with which to login to the InfluxDB server.

global.influxdb.password

string

The password for the above user.

global.influxdb.database

string

The database in which thingsHub shall store its data.

global.visualizer.auth.enabled

boolean

Set this to true to manage the Visualizer users with the thingsHub (recommended).

Advanced options

Advanced options are usually specific to one of the system's services, e.g. InfluxDB. They are prefixed with this service's internal name, e.g. influxdb.

Option

Type

Description

influxdb.retention_policies.receptions_data

time duration

Sets the duration of the retention policy receptions_retention_policy for reception related data, e.g. RSSI, SNR.

This data is stored in the InfluxDB measurement reception_data.

This configuration option only has affect during creation of the tenant, and will not be updated after initial configuration of the tenant. Furthermore, this option requires that the InfluxDB user that the tenant uses has admin privileges for the InfluxDB server.


influxdb.retention_policies.devices_data

time duration

Sets the duration of the retention policy for devices data, named thub_device_data.

This affects data that is automatically stored in InfluxDB in a measurement per device driver, e.g. in smartmakers/nke-ino:2.3.

This configuration option only has affect during creation of the tenant, and will not be updated after initial configuration of the tenant. Furthermore, this option requires that the InfluxDB user that the tenant uses has admin privileges for the InfluxDB server.


influxdb.retention_policies.raw_logs

time duration

Sets the duration of the retention policy for raw log messages, named logs_rp. This affects for example the raw messages received over a network connection.

This data is stored in the measurement logs_rp.

This configuration option only has affect during creation of the tenant, and will not be updated after initial configuration of the tenant. Furthermore, this option requires that the InfluxDB user that the tenant uses has admin privileges for the InfluxDB server.

grafana.auth.anonymous.enabled

boolean (true by default)

True if anonymous authentication is enabled, false otherwise.

grafana.plugins.hostPath

string

Set this to a path on the Kubernetes host machine in which Grafana plugins are stored. Make sure that the contents of this path are identical on all nodes of the cluster, so that grafana behaves consistently.

For each version of grafana in use, introduce a separate subpath with the version number, e.g. if the path is /mnt/plugins and some tenants are running version 5.0.4, the plugins for this tenant should be in the path /mnt/plugins/5.0.4.

How to...

... set a logo for the index page

You require a logo which is not higher then 70px and in PNG format. The logo must be supplied in the values as a base64 encoded. Set the logo as in the example below:

index:
  logo: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==
YML

In order to convert the image to base64, you can use an online encoder such as: https://www.base64-image.de/ or search google for others.

If you run a linux machine you can execute the following command

$ cat logo.png | base64 -w 0
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==
$
BASH

... generate a secure, random password on the command line

You can generate a secure, random password from the command line using the command line tool openssl:

$ openssl rand -base64 30
pNABkkecqQTdTrck9IzhrPgulvNY4qELUgaC3JDA
$
BASH

Password policy regex examples

Regular expression

Description

^.{8,}$

A password with at least 8 characters.

^(?=.*[A-Z])[A-Za-z\d@$!%*?&]{8,}$

Minimum eight characters, at least one uppercase letter

^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[A-Za-z\d@$!%*?&]{8,}$

Minimum eight characters, at least one uppercase letter, one lowercase letter and one number