Configuration parameters
- All the below parameters can be updated by following the configuration update procedure.
- Majority of them can be updated at any time. Parameters impacting the ThingPark Enterprise operation are explicitly highlighted
- See a complete example in files under the
examples/customization
folder of configuration repository. Be sure to have selected the appropriate tag version.
Instance identification and basic customization
Name | Mandatory | Description | Value | Default Value |
---|---|---|---|---|
global.installationId | yes | InstallationID obtained at instance registration | string | "" |
global.supportEmail | yes | Set the support contact email for your instance | email address | "support@actility.com" |
global.logo | no | Main logo displayed in the login page and top menu. The image should be in PNG format and less than 50 kB. Recommended size is 300 x 100 px. Logo must be provided as base64 encoded string. | string | Actility Logo |
smp-tpe.trustedCertSecret | no | Certificate Authority (CA) certificate that signs the TLS Certificate for SMTP or an external IDP in Base64 ASCII encoded PEM format when a corporate or private Certificate Authority (CA) is used. Can be changed anytime. | PEM certificate | Undefined (-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE----\n ) |
Hostname and Inbound flows
Name | Mandatory | Description | Value | Default Value |
---|---|---|---|---|
global.dnsHostname | yes | Set your desired hostname | fqdn | "" |
global.ingress.hosts | no | Replace default use of global.dnsHostname for ingress by the provided list of hosts | ["fqdn"] | Undefined |
networkPolicy.ingress.enabled | no | Allow to isolate workload running in the ThingPark deployment namespace from others. | boolean | false |
ingress-nginx.controller.service.annotations | no | Service to use to add annotation allowing DNS dynamic provisioning | object | {"service.beta.kubernetes.io/azure-dns-label-name": "thingpark-enterprise"} or {"external-dns.alpha.kubernetes.io/hostname": "dnsHostname,enterprise.mycompany.org" } |
ingress-nginx.tcp.2022 | yes | Support ssh inbound. Set namespace regarding your deployment | string | "<namespace>/support-inbound:22" |
ingress-nginx.tcp.3001 | yes | LRC tls inbounds. Set namespace regarding your deployment | string | "<namespace>/lrc-proxy:3001" |
ingress-nginx.tcp.3101 | yes | LRC tls inbounds. Set namespace regarding your deployment | string | "<namespace>/lrc-proxy:3101" |
ingress-nginx.tcp.3002 | yes | LRC sftp over tls inbound Set namespace regarding your deployment | string | "<namespace>/lrc-proxy:3002" |
ingress-nginx.tcp.4443 | yes | Basics Station LNS inbound. Set only if global.featuresActivation.basicsStation is set to true . Set namespace regarding your deployment | string | "<namespace>/lrc-proxy-lns:8443" |
global.ingress.lnsPublicPort | no | Optional override of load balancer exposed port for lns endpoint. Should be updated in a coordinated way with ingress-nginx.tcp.4443 | int | 4443 |
global.dnsHostname
FQDN is used:
- by ingress-nginx to allow access the TPE portal GUI and API
- by base stations to reach ThingPark Enterprise in TLS security mode
- Changing
global.dnsHostname
FQDN of your TPE instance has an impact on all the Base Stations configured on the TPE instance:- You MUST re-generate all your Base Stations certificate.
- Then, you MUST reconfigure the Base Stations with the new dnsHostName fqdn address on the Suplog menu.
- You MUST obtain this https certificate from a trusted https certificate provider or force trust in you browser if default autosigned one is used.
- If you wish to use a certificate generated by your own, it is mandatory to provide one in line with this domain name.
Use cloud DNS provisioning services
AZURE:
global.dnsHostname
should be composed of Azure DNS alias followed by Azure region domain name (i.e. thingpark-enterprise.westeurope.cloudapp.azure.com)- Azure DNS alias is specified using service annotation:
service.beta.kubernetes.io/azure-dns-label-name: thingpark-enterprise
AMAZON:
- Use external-dns controller to manage a Route 53 subdomain
- Configure provisioning by using the
external-dns.alpha.kubernetes.io/hostname
with theglobal.dnsHostname
:external-dns.alpha.kubernetes.io/hostname:thingpark-enterprise.mycompany.org
Network Isolation
Once your cluster uses a networking plugin which supports NetworkPolicy, you can
start to filter thingpark workloads ingress.
Enable networkPolicy.ingress.enabled
allows to isolate workload running in the
ThingPark deployment namespace from other. Only flow exposed by ingress controller
are allowed.
Integration behind a reverse proxy
To allow usage of reverse proxy
- Configure the public hostname as
global.dnsHostname
- The Load Balancer front of reverse proxy MUST also forward base stations TCP flows
- To use a internal FQDN to reach Kubernetes Load Balancer and an appropriate
certificate, you have to use the
global.ingress.hosts
parameter to override with this custom host.
TLS Certificate for HTTP traffic
Name | Description | Value | Default Value |
---|---|---|---|
global.ingress.tls.issuer | Select an issuer for https inbound flow certificate. A certificate can be: - an externally generated one. - a selfsigned one automatically generated by deployment, - a letsencrypt generated one, public access to ingress and a public resolved dnsHostname are required | "external" , "selfsigned" , "letsencrypt" | "selfsigned" |
global.ingress.tls.certificate | Server certificate when you use your own (external issuer) | PEM certificate | Undefined (-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE----\n ) |
global.ingress.tls.key | Server certificate private key when you use your own (external issuer) | PEM private key | Undefined (-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY-----\n ) |
global.ingress.tls.caCertificate | Root Certificate of Public Key Infrastructure that have issued the server certificate. Mandatory when Basics Station feature is enabled and global.ingress.tls.issuer: "external" or "letsencrypt" | PEM certificate | Undefined (-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE----\n ) |
global.ingress.tls.acmeEmail | Email address used by Let's Encrypt to contact you about expiring | email | "foo@example.com" |
global.ingress.tls.acmeSolvers | ACME Challenge configuration to obtain certificate. See cert-manager documentation to configure other one | object | [{"http01": {"ingress": {"class": "nginx-tpe"}}}] |
tp-gui.ingress.items.gui.annotations | Required annotation allowing cert-manager to trigger certificate generation for tpe ingress | object (cert-manager letsencrypt issuer) | {"cert-manager.io/issuer": "letsencrypt-prod"} when letsencrypt issuer used |
- With default
global.ingress.tls.issuer: "selfsigned"
, don't omit to add{"cert-manager.io/issuer": "internal-ca-issuer"}
annotation totp-gui.ingress.items.gui.annotations
- With
global.ingress.tls.issuer: "letsencrypt"
,don't omit to add{"cert-manager.io/issuer": "letsencrypt-prod"}
annotation totp-gui.ingress.items.gui.annotations
. - Using
global.ingress.tls.issuer: "external"
,global.ingress.tls.certificate
MUST include the server certificate first, and next all intermediate certificates of the chain of trust.
- Changing
global.ingress.tls.issuer
will break Basics Station connections! You have to take in account the update of trusts on Gateway side. global.ingress.tls.caCertificate
certificate is:- Empty default TLS configuration (
global.ingress.tls.issuer: "selfsign"
), - The root certificate of
Letsencrypt authority(Default ISRG Root X1)
that have signed server certificate with
global.ingress.tls.issuer: "letsencrypt"
(Root CA Name can be obtained usingkubectl get secrets ingress-tls -o jsonpath="{.data['tls\.crt']}"|base64 -d | sed '1,/-----END CERTIFICATE-----/d'|openssl x509 -in - -issuer -noout
), - The root certificate of authority that have signed your own server
certificate with
global.ingress.tls.issuer: "external"
.
- Empty default TLS configuration (
Repositories
Only for custom deployments
Name | Description | Value | Default Value |
---|---|---|---|
global.repositories | Repository configurations. No additional configuration required for a partner deployment | object | |
global.repositories.containerImagesRegistry.fqdn | Container registry hostname FQDN | fqdn | "repository.thingpark.com" |
global.repositories.containerImagesRegistry.namespace | Container registry Namespace | string | "thingpark-kubernetes" |
global.repositories.containerImagesRegistry.pullPolicy | Container image pullPolicy to use for all deployed workloads | string in imagePullPolicy | "IfNotPresent" |
global.repositories.containerImagesRegistry.auth.username | Username to authenticate against container registry. Set with InstallationID when default Actility registry used | string | installationId |
global.repositories.containerImagesRegistry.auth.password | Password to authenticate against container registry. Set with InstallationID when default Actility registry used | string | installationId |
global.repositories.thingparkResources.url | Base stations firmware and documentation repository URL. This URL should be reachable from web browser | url | "https://repository.thingpark.com" |
global.repositories.thingparkCatalogs.url | Catalogs repository URL. Serve RF regions, devices and base station profiles and drivers' catalogs. This URL must be reachable from the ThingPark Enterprise servers | url | "https://repository.thingpark.com" |
global.repositories.thingparkCatalogs.updateMethod | When set to repository , catalogs are served by the repository configured. When set to manual-upload , catalogs are manually uploaded in the ThingPark Enterprise user interface. Can be changed anytime. | string | "repository" |
Feature settings
To save server resources and following your need, some services may be enabled/disabled or scaled depending your needs.
Name | Description | Value | Default Value |
---|---|---|---|
global.featuresActivation.dxApi | DX API activation | boolean | true |
global.featuresActivation.iotFlow | IoT Flow activation | boolean | true |
global.featuresActivation.basicsStation | Basics Station components activation | boolean | false |
Mail settings
Name | Mandatory | Description | Value | Default Value |
---|---|---|---|---|
global.outgoingMail | no | Default empty configuration not need any mail relay | object | {} |
global.outgoingMail.smtpServer | yes | Hostname or IP address of the SMTP server to use to send emails. | fqdn or ip-address | "smtp.example.com" |
global.outgoingMail.smtpAuth | no | Authentication activation when no empty block is provided | object | {} |
global.outgoingMail.smtpAuth.login | yes | Login used to authenticate against SMTP server | string | "" |
global.outgoingMail.smtpAuth.password | yes | Password used to authenticate against SMTP server | string | "" |
global.outgoingMail.port | yes | SMTP server port | int | 465 |
global.outgoingMail.noReplyEmail | yes | email sender "From" of all emails sent by the TPE instance. | email | "noreply@example.com" |
global.outgoingMail.smtpSecurity | yes | select one of the available options (None, SSL or TLS) depending on the SMTP server you will use. | string in "clear" , "ssl" , "tls" | "ssl" |
global.outgoingMail.actionTokenGeneratedByUserLifespan | no | Maximum time in minutes before an action permit sent by a user (e.g. forgot password e-mail) is expired. This value is recommended to be short because it is expected that the user would react to self-created action quickly. | int | 15 |
global.outgoingMail.actionTokenGeneratedByAdminLifespan | no | Maximum time in minutes before an action permit sent to a user by admin (e.g. account creation) is expired. This value is recommended to be long to allow admins send e-mails for users that are currently offline | string | 60 |
"Alarms notification", "activation of users account", "password recovery" and "Contact us" features require a valid smtp configuration.
Proxy settings
Name | Description | Value | Default Value |
---|---|---|---|
global.outgoingProxy | Proxy configuration bloc, disabled by default | object | {} |
global.outgoingProxy.url | URL of the proxy server used for ThingPark Enterprise resources repository access | url | "http://192.168.1.1:8080" |
global.outgoingProxy.auth | Proxy authentication configuration block (optional) | object | {} |
global.outgoingProxy.auth.username | Username of the proxy account | string | "" |
global.outgoingProxy.auth.password | Password of the proxy account | string | "" |
global.outgoingProxy.useForLrcUplinks | Enable proxy for LRC uplinks: enable if you want to use the proxy for LRC uplinks on the tunneling interface | boolean | true |
Below the list of Cipher suites supported for an access through HTTPS proxy:
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_AES_128_GCM_SHA256
- TLS_CHACHA20_POLY1305_SHA256
- TLS_AES_256_GCM_SHA384
Oauth federation settings
Name | Description | Value | Default Value |
---|---|---|---|
global.oauthFederation | OAuth configuration bloc, disabled by default | object | {} |
global.oauthFederation.issuer | OAuth identity provider issuer url | url | "" |
global.oauthFederation.clientId | OAuth identity provider client ID | string | "" |
global.oauthFederation.clientSecret | OAuth identity provider client Secret | string | "" |
First installation MUST always be done without any oauthFederation configuration. See Authentication Federation for more details.
Device and base station alarm notification
Name | Description | Value | Default Value |
---|---|---|---|
global.snmp.trap.server | SNMP trap destination server. Hostname or IP address of the SNMP trap destination server | fqdn or ip-address | "" |
global.snmp.trap.community | SNMP trap community | string | "public" |
Base station security
Name | Description | Value | Default Value |
---|---|---|---|
global.ingress.baseStation.keyInstallerPasswordHash | Hash of the password configured in the base stations to connect the key-installer service. This password should be set only if base stations are flashed with custom images. | The hash must be provided in the SHA512 format, for example using the openssl passwd -6 command. | Undefined |
wireless-pki.certProfiles.lrrClient.validity | Base station client certificates validity period. This property is taken into account when a certificate is issued. Certificates issued before this property is changed should be revoked to use the new validity period | (*y *mo *d) y=365 days, mo=30 days | 3y |
Basics Station
Name | Description | Values | Default Value (example) |
---|---|---|---|
ingress-nginx.tcp.4443 | ingress-nginx TCP service port configuration | object | ({ 4443: thingpark-enterprise/lrc-proxy-lns:8443} ) |
global.basicsStation.lnsPublicPort | Optional override of load balancer exposed port for lns endpoint | int | 4443 |
- Overall activation is governed by
global.featuresActivation.basicsStation
flag - In order to be able to reach Lns endpoint,
ingress-nginx.tcp.4443
have to be uncommented incustom-values.yaml
file. Ifglobal.basicsStation.lnsPublicPort
is overridden, port number coordinated withingress-nginx.tcp.4443
key number.
AS security level
Name | Description | Values | Default Value |
---|---|---|---|
global.asSecurity | When set to 'strict' (default), auto-signed certificates are rejected. This configuration applies only to HTTPS AS | string in strict , loose | "strict" |
LoRa configuration
Please update carefully below Lora configuration
Name | Description | Value | Default Value |
---|---|---|---|
global.lora.ismBand | Choose the desired ISM Band (also known as Regional RF profile) for your deployment. The Base Station and Device Catalogs will be automatically filtered on the TPE Portal GUI according to this setting. On the TPE Portal GUI, it will be possible to create Base Stations and Devices that match the ISM Bands set here. This configuration should be done during the TPE instance initialization ONLY. Anyway, it can be updated afterwards, but you must keep consistency with the deployments of your Base Stations and Devices. | ["string"] | ["eu868"] |
global.lora.netId | Configure the LoRaWAN™ 24 bits network identifier. A dedicated NetID assigned by the LoRa Alliance® is required when roamout is enabled. Possible values are 6 hexadecimal digits (case insensitive) restricted to the following list: - Default value: 000001 | string | "000001" |
global.lora.roaming | Configure the LoRaWAN™ Activation and passive roaming. Configuration block can be changed anytime. | object | See below |
global.lora.roaming.integrationMode | Configure the roaming mode. The possible values are: - none: default value. - Activation only: allows the activation of devices pre-commissioned on agreed external join servers. - Activation and roaming in: allows devices from agreed foreign networks to use local base stations for uplink and downlink communications (in addition to LoRaWAN™ Activation). - Activation, roaming in and out: allows local devices to use base stations from agreed foreign networks for uplink and downlink communications (in addition to LoRaWAN™ Activation). | string in "none" ,"activation" , "roam-in" , "roam-in-out" | "none" |
global.lora.roaming.nsId | When Roaming and/or Activation is enabled, LoRaWAN™ 64 bits network server identifier. This information is part of the ThingPark Exchange (TEX) subscription. | string | "" |
global.lora.roaming.tex.url | When Roaming and/or Activation is enabled, URL of ThingPark Exchange (TEX). | url | "https://exchange.thingpark.com/" |
global.lora.roaming.tex.hubId | When Roaming and/or Activation is enabled, HubID of ThingPark Exchange (TEX). | string | "" |
global.lora.roaming.tex.outgoingAuth.username | When Roaming and/or Activation is enabled, Username of the ThingPark Exchange (TEX) account. | string | "" |
global.lora.roaming.tex.outgoingAuth.password | When Roaming and/or Activation is enabled, Password of the ThingPark Exchange (TEX) account. | string | "" |
global.lora.roaming.tex.incomingAuth | When Roaming and/or Activation is enabled, AUth of the ThingPark Exchange (TEX) account. | object | in sync with global.lora.roaming.tex.outgoingAuth |
global.lora.otaaDevAddrPoolBlock | Configure a DevAddr range to be used for OTAA devices. The DevAddr range is expressed as a hexadecimal prefix followed by a slash (/) and the number of bits. This range must match the configured NetID. This parameter is optional and can be configured if you want to do roaming between TPE instances sharing the same NetID. In such case, you can define a dedicated OTAA DevAddr range to each TPE instance. See below for configuration details. | string | "" |
TEX synchronization status with LRC can be monitored using this Administration Procedure.
OTAA DevAddr range configuration
This parameter allows to configure a DevAddr range to be used for OTAA devices. The DevAddr range is expressed as a hexadecimal prefix followed by a slash (/) and the number of bits. This range must match the configured NetID. Can be changed anytime.
This parameter is optional and can be configured if you want to do roaming between TPE instances sharing the same NetID. In such case, you can define a dedicated OTAA DevAddr range to each TPE instance.
OTAA DevAddr range validation is done as follows:
- The binary NetID DevAddr prefix is computed based on the configured NetID:
- NetID DevAddr prefix is Type | NwkID
- If NetID is type 0 (3 MSB are 0b000):
- Type is 0b0
- NwkID is the 6 LSB of NetID
- Else if NetID is type 3 (3 MSB are 0b011):
- Type is 0b1110
- NwkID is the 11 LSB of NetID
- Else if NetID is type 6 (3 MSB are 0b110):
- Type is 0b1111110
- NwkID is the 15 LSB of NetID
- The binary SubNetID DevAddr prefix is computed based on the configured
OTAA DevAddr range:
- Left part is translated from hexadecimal to binary.
- Only the number of MSB specified in the right part are kept.
- OTAA DevAddr range is valid if SubNetID DevAddr prefix binary string starts with NetID DevAddr prefix binary string.
Below some valid and invalid OTAA DevAddr range configuration based on configured NetID:
-
Example #1: NetID 000002 (type 0) / OTAA DevAddr range 040/12
- NetID DevAddr prefix: 0b0000010
- Type is 0b0
- NwkID is 0b000010
- SubNetID DevAddr prefix: 0b000001000000
- OTAA DevAddr range is valid
- NetID DevAddr prefix: 0b0000010
-
Example #2: NetID 60000F (type 3) / OTAA DevAddr range E01E0/20
- NetID DevAddr prefix: 0b111000000001111
- Type is 0b1110
- NwkID is 0b00000001111
- SubNetID DevAddr prefix: 0b11100000000111100000
- OTAA DevAddr range is valid
- NetID DevAddr prefix: 0b111000000001111
-
Example #3: NetID C0000F (type 6) / OTAA DevAddr range FC0038/24
- NetID DevAddr prefix: 0b1111110000000000001111
- Type is 0b1111110
- NwkID is 0b000000000001111
- SubNetID DevAddr prefix: 0b111111000000000000111000
- OTAA DevAddr range is invalid
- NetID DevAddr prefix: 0b1111110000000000001111
Wireless configuration
Name | Description | Value | Default Value |
---|---|---|---|
global.wireless.deviceHistoryExpiration | Set the lifespan of LoRaWAN uplink and downlink frames. The default value of 15 days is enough for a normal usage of ThingPark Enterprise. Extending the default value consumes hardware resources (RAM, Disk space), please contact your support before any change. | integer (in days) | 15 |
Iot Flow settings
Name | Description | Value | Default Value |
---|---|---|---|
global.iotFlow.maxConnections | Set the maximum number of IoT flow connections allowed simultaneously. As each connection consumes hardware resources (CPU, RAM), this value should be set carefully | integer | Depend hardware sizing |
tpx-flow.kafka.topicConfigRetentionMs | IotFlow connection topics retention duration between 6 hours and 240 hours | int , 21600000 to 864000000 ms | 21600000 |
tpx-flow.kafka.topicConfigRetentionMs
parameter update is not applied to
existing IotFlow connections. Relating topics configuration must be updated
after the configuration have been applied. See
Update IotFlow connection topics retentions
procedure.
Maps settings
Name | Description | Value | Default Value |
---|---|---|---|
global.mapService | Map service used by the applications, leave empty to disable. When disabled, all map widgets are deactivated and Network Survey application cannot be used | object | {} |
global.mapService.defaultLocation | Default map location used on map widgets | string | "" |
global.mapService.api | Map API to use, either Google Maps or Openstreet Maps | string in gmaps,osm | "" |
global.mapService.apiKey | Api key, required for Google Maps | string | "" |
global.mapService.osmTile | Leaflet tile layer URL template, required for Openstreet Maps | url | "" |
global.mapService.osmNominatim | Nominatim search URL, required for Openstreet Maps | url | "" |
Backup settings
- A storage is MANDATORY to allow to backup during upgrades
- Scheduled backup is optional
Name | Description | Value | Default value (example) |
---|---|---|---|
global.backup.schedule | Backup scheduling configuration, disabled by default | cron expression | Undefined ("30 2 * * *" ) |
global.backup.s3Compat | Backup configuration to use a s3 compatible backend (ex: minio) | object | Undefined |
global.backup.s3Compat.url | url to use to reach s3 storage api | url | "" |
global.backup.s3Compat.accessKey | Access Key to use to authenticate against api | string | "" |
global.backup.s3Compat.secretAccessKey | Secret Access Key to use to authenticate against api | string | "" |
global.backup.s3Compat.bucket | Bucket name to use to store backup archives | string | ("thingpark-enterprise-backup" ) |
global.backup.amazon | Backup configuration to use an Amazon s3 bucket | object | - |
global.backup.amazon.accessKey | Access Key to use to authenticate against api. Optional, if not provided, EKS Node Group IAM Role must allow get/put to S3 backup bucket | string | "" |
global.backup.amazon.secretAccessKey | Secret Access Key to use to authenticate against api. Optional, if not provided, EKS Node Group IAM Role must allow get/put to S3 backup bucket | string | "" |
global.backup.amazon.bucket | Bucket name to use to store backup archives | string | ("thingpark-enterprise-backup" ) |
global.backup.amazon.region | Bucket region | string | ("us-east-2" ) |
global.backup.azure | Backup configuration to use an Amazon s3 bucket | object | Undefined |
global.backup.azure.resourceGroup | string | "" | |
global.backup.azure.storageAccount | bucket | string | "" |
global.backup.azure.blobContainer | url | ("thingpark-enterprise-backup" ) | |
global.backup.azure.subscriptionId | string | "" | |
global.backup.azure.tenantId | string | "" | |
global.backup.azure.clientId | string | "" | |
global.backup.azure.clientSecret | string | "" |