Remote connectivity configuration

Customize the remote connectivity and automatic provisioning.

1: AWS Connector configuration
2: Suite connector configuration
3: Suite bootstrapping configuration

1 - AWS Connector configuration

Customize the remote connectivity.

Properties

To control all aspects of the suite connector behavior.

Property	Type	Default	Description
topicFilter	string		Regex filter used to block incoming messages by their topic
payloadFilters	string		Regex filters used to exclude parts of the incoming messages payload
Remote connectivity
address	string		Address of the MQTT endpoint that the connector will connect for the remote communication, the format is: `scheme://host:port`
tenantId	string	default-tenant-id	Tenant unique identifier that the device belongs to
clientId	string		MQTT client unique identifier
Remote connectivity - TLS
alpn	string[]		TLS application layer protocol negotiation options space separated for cloud access
caCert	string	aws.crt	PEM encoded CA certificates file
cert	string		PEM encoded certificate file to authenticate to the MQTT endpoint
key	string		PEM encoded unencrypted private key file to authenticate to the MQTT endpoint
Remote connectivity - TLS over TPM
tpmDevice	string		Path to the device file or the unix socket to access the TPM 2.0
tpmHandle	int		TPM 2.0 storage root key handle, the type is unsigned 64-bit integer
tpmKeyPub	string		File path to the public part of the TPM 2.0 key
tpmKey	string		File path to the private part of the TPM 2.0 key
Local connectivity
localAddress	string	tcp://localhost:1883	Address of the MQTT server/broker that the suite connector will connect for the local communication, the format is: `scheme://host:port`
localUsername	string		Username that is a part of the credentials
localPassword	string		Password that is a part of the credentials
Local connectivity - TLS
localCACert	string		PEM encoded CA certificates file
localCert	string		PEM encoded certificate file to authenticate to the MQTT server/broker
localKey	string		PEM encoded unencrypted private key file to authenticate to the MQTT server/broker
Logging
logFile	string	log/suite-connector.log	Path to the file where log messages are written
logLevel	string	INFO	All log messages at this or a higher level will be logged, the log levels in descending order are: ERROR, WARN, INFO, DEBUG and TRACE
logFileCount	int	5	Log file maximum rotations count
logFileMaxAge	int	28	Log file rotations maximum age in days, use 0 to not remove old log files
logFileSize	int	2	Log file size in MB before it gets rotated

Example

The minimal required configuration to connect.

{
    "address": "tls://<AWS-endpoint-address>:8883",
    "caCert": "AmazonRootCA1.pem",
    "cert": "example-device.crt",
    "key": "example-device.key",
    "clientId": "org.eclipse.kanto:exampleDevice",
    "logFile": "/var/log/aws-connector/aws-connector.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

Be aware that some combinations may be incompatible

{
    "topicFilter": "",
    "payloadFilters": [],
    "address": "",
    "alpn" : [],
    "tenantId": "default-tenant-id",
    "clientId": "",
    "caCert": "aws.crt",
    "cert": "",
    "key": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "localCACert": "",
    "localCert": "",
    "localKey": "",
    "logFile": "logs/aws-connector.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

2 - Suite connector configuration

Customize the remote connectivity.

Properties

To control all aspects of the suite connector behavior.

Property	Type	Default	Description
Remote connectivity
address	string	mqtts://mqtt.bosch-iot-hub.com:8883	Address of the MQTT endpoint that the suite connector will connect for the remote communication, the format is: `scheme://host:port`
alpn	string[]		TLS application layer protocol negotiation options space separated for cloud access
deviceId	string		Device unique identifier
authId	string		Authentication unique identifier that is a part of the credentials
tenantId	string		Tenant unique identifier that the device belongs to
username	string		MQTT username that is a part of the credentials. This parameter takes precedence over authId and tenantId
password	string		Password that is a part of the credentials
clientId	string		MQTT client unique identifier
policyId	string		Policy unique identifier of the digital twin
Remote connectivity - TLS
caCert	string	iothub.crt	PEM encoded CA certificates file
cert	string		PEM encoded certificate file to authenticate to the MQTT endpoint
key	string		PEM encoded unencrypted private key file to authenticate to the MQTT endpoint
deviceIdPattern	string		Pattern to generate the device identifier, `{{subject-dn}}` and `{{subject-cn}}` placeholders can be part of it
Remote connectivity - TLS over TPM
tpmDevice	string		Path to the device file or the unix socket to access the TPM 2.0
tpmHandle	int		TPM 2.0 storage root key handle, the type is unsigned 64-bit integer
tpmKeyPub	string		File path to the public part of the TPM 2.0 key
tpmKey	string		File path to the private part of the TPM 2.0 key
Local connectivity
localAddress	string	tcp://localhost:1883	Address of the MQTT server/broker that the suite connector will connect for the local communication, the format is: `scheme://host:port`
localUsername	string		Username that is a part of the credentials
localPassword	string		Password that is a part of the credentials
Local connectivity - TLS
localCACert	string		PEM encoded CA certificates file
localCert	string		PEM encoded certificate file to authenticate to the MQTT server/broker
localKey	string		PEM encoded unencrypted private key file to authenticate to the MQTT server/broker
Logging
logFile	string	log/suite-connector.log	Path to the file where log messages are written
logLevel	string	INFO	All log messages at this or a higher level will be logged, the log levels in descending order are: ERROR, WARN, INFO, DEBUG and TRACE
logFileCount	int	5	Log file maximum rotations count
logFileMaxAge	int	28	Log file rotations maximum age in days, use 0 to not remove old log files
logFileSize	int	2	Log file size in MB before it gets rotated

Example

The minimal required configuration to connect the publicly available Eclipse Hono sandbox.

{
    "address": "hono.eclipseprojects.io:1883",
    "tenantId": "org.eclipse.kanto",
    "deviceId": "org.eclipse.kanto:exampleDevice",
    "authId": "org.eclipse.kanto_example",
    "password": "secret",
    "logFile": "/var/log/suite-connector/suite-connector.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

Be aware that some combinations may be incompatible

{
    "provisioningFile": "provisioning.json",
    "address": "mqtts://mqtt.bosch-iot-hub.com:8883",
    "alpn" : [],
    "deviceId": "",
    "authId": "",
    "tenantId": "",
    "password": "",
    "username": "",
    "clientId": "",
    "policyId": "",
    "caCert": "iothub.crt",
    "cert": "",
    "key": "",
    "deviceIdPattern": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "logFile": "log/suite-connector.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

3 - Suite bootstrapping configuration

Customize the automatic provisioning.

Properties

To control all aspects of the suite bootstrapping behavior.

Property	Type	Default	Description
preBootstrapScript	string[]		Path to the script/command with an optional sequence of additional flags/parameters that is executed before a bootstrapping request, optionally producing a `preBootstrapFile`
preBootstrapFile	string		Path to the file used as a bootstrapping request data
postBootstrapScript	string[]		Path to the script/command with an optional sequence of additional flags/parameters that is executed after a bootstrapping response, optionally consuming a `postBootstrapFile`
postBootstrapFile	string		Path to the file used for a bootstrapping response data
bootstrapProvisioningFile	string		Path to the file that stores the provisioning information from a bootstrapping response
maxChunkSize	int	46080	Maximum chunk size of the request data in bytes
Remote connectivity
address	string	mqtts://mqtt.bosch-iot-hub.com:8883	Address of the MQTT endpoint that the suite bootstrapping will connect for the remote communication, the format is: `scheme://host:port`
deviceId	string		Device unique identifier
authId	string		Authentication unique identifier that is a part of the credentials
tenantId	string		Tenant unique identifier that the device belongs to
password	string		Password that is a part of the credentials
clientId	string		MQTT client unique identifier
policyId	string		Policy unique identifier of the digital twin
Remote connectivity - TLS
caCert	string	iothub.crt	PEM encoded CA certificates file
cert	string		PEM encoded certificate file to authenticate to the MQTT endpoint
key	string		PEM encoded unencrypted private key file to authenticate to the MQTT endpoint
deviceIdPattern	string		Pattern to generate the device identifier, `{{subject-dn}}` and `{{subject-cn}}` placeholders can be part of it
Remote connectivity - TLS over TPM
tpmDevice	string		Path to the device file or the unix socket to access the TPM 2.0
tpmHandle	int		TPM 2.0 storage root key handle, the type is unsigned 64-bit integer
tpmKeyPub	string		File path to the public part of the TPM 2.0 key
tpmKey	string		File path to the private part of the TPM 2.0 key
Logging
logFile	string	log/suite-bootstrapping.log	Path to the file where log messages are written
logLevel	string	INFO	All log messages at this or a higher level will be logged, the log levels in descending order are: ERROR, WARN, INFO, DEBUG and TRACE
logFileCount	int	5	Log file maximum rotations count
logFileMaxAge	int	28	Log file rotations maximum age in days, use 0 to not remove old log files
logFileSize	int	2	Log file size in MB before it gets rotated

Example

The minimal required configuration to connect the publicly available Eclipse Hono sandbox and request automatic provisioning.

{
    "address": "hono.eclipseprojects.io:1883",
    "tenantId": "org.eclipse.kanto",
    "deviceId": "org.eclipse.kanto:exampleDevice",
    "authId": "org.eclipse.kanto_example",
    "password": "secret",
    "logFile": "/var/log/suite-bootstrapping/suite-bootstrapping.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

Be aware that some combinations may be incompatible

{
    "preBootstrapScript": "",
    "preBootstrapFile": "",
    "postBootstrapScript": "",
    "postBootstrapFile": "",
    "bootstrapProvisioningFile": "",
    "maxChunkSize": 46080,
    "provisioningFile": "provisioning.json",
    "address": "mqtts://mqtt.bosch-iot-hub.com:8883",
    "deviceId": "",
    "authId": "",
    "tenantId": "",
    "password": "",
    "clientId": "",
    "policyId": "",
    "caCert": "iothub.crt",
    "cert": "",
    "key": "",
    "deviceIdPattern": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "logFile": "log/suite-bootstrapping.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}