This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

References

Explore customization of Eclipse Kanto.

1: Remote connectivity configuration

1.1: AWS Connector configuration
1.2: Suite connector configuration
1.3: Suite bootstrapping configuration

2: Local digital twins configuration
3: Container management configuration

3.1: Container configuration
3.2: Manager configuration

4: Software update configuration
5: File upload configuration
6: File backup configuration
7: System metrics configuration

1 - Remote connectivity configuration

Customize the remote connectivity and automatic provisioning.

1.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
}

1.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
}

1.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
}

2 - Local digital twins configuration

Customize the local digital twins persistency, access and synchronization.

Properties

To control all aspects of the local digital twins behavior.

Property	Type	Default	Description
thingsDb	string	things.db	Path to the file where digital twins will be stored
Remote connectivity
address	string	mqtts://mqtt.bosch-iot-hub.com:8883	Address of the MQTT endpoint that the local digital twins 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
Local connectivity
localAddress	string	tcp://localhost:1883	Address of the MQTT server/broker that the local digital twins 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/local-digital-twins.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 enable the local digital twins and their synchronization with 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",
    "thingsDb": "/var/lib/local-digital-twins/thing.db",
    "logFile": "/var/log/local-digital-twins/local-digital-twins.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

{
    "thingsDb": "things.db",
    "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": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "localCACert": "",
    "localCert": "",
    "localKey": "",
    "logFile": "log/local-digital-twins.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

3 - Container management configuration

Customize the deployment and management of containers.

3.1 - Container configuration

Customize the deployment of a container instance.

Properties

To control all aspects of the container instance behavior.

Property	Type	Default	Description
container_name	string	<container_id>	User-defined name for the container, if omitted the internally auto-generated container ID will be set
Image
name	string		Fully qualified image reference, that follows the OCI Image Specification, the format is: `host[:port]/[namespace/]name:tag`
Image - decryption
keys	string[]		Private keys (GPG private key ring, JWE or PKCS7) used for decrypting the container’s image, the format is: `filepath_private_key[:password]`
recipients	string[]		Recipients (only for PKCS7 and must be an x509) used for decrypting the container’s image, the format is: `pkcs7:filepath_x509_certificate`
Networking
domain_name	string	<container_name>-domain	Domain name inside the container, if omitted the `container_name` with suffix -domain will be set
host_name	string	<container_name>-host	Host name for the container, if omitted the `container_name` with suffix -host will be set
network_mode	string	bridge	The container’s networking capabilities type based on the desired communication mode, the possible options are: bridge or host
extra_hosts	string[]		Extra host name to IP address mappings added to the container network configuration, the format is: `hostname:ip`. If the IP of the host machine is to be added to the container’s hosts file the reserved host_ip[_<network-interface>] must be provided. If only host_ip (the network-interface part is skipped) is used, by default it will be resolved to the host’s IP on the default bridge network interface for containerm (the default configuration is kanto-cm0) and add it to the container’s hosts file. If the IP of a container in the same bridge network is to be added to the hosts file the reserved container_<container-host_name> must be provided.
Networking - port mappings
proto	string	tcp	Protocol used for the port mapping from the container to the host, the possible options are: tcp and udp
container_port	int		Port number on the container that is mapped to the host port
host_ip	string	0.0.0.0	Host IP address
host_port	int		Beginning of the host ports range
host_port_end	int	<host_port>	Ending of the host ports range
Host resources - devices
path_on_host	string		Path to the device on the host
path_in_container	string		Path to the device in the container
cgroup_permissions	string	rwm	Cgroup permissions for the device access, possible options are: r(read), w(write), m(mknod) and all combinations are possible
privileged	bool	false	Grant root capabilities to all devices on the host system
Host resources - mount points
source	string		Path to the file or directory on the host that is referred from within the container
destination	string		Path to the file or directory that is mounted inside the container
propagation_mode	string	rprivate	Bind propagation for the mount, supported are: rprivate, private, rshared, shared, rslave or slave
Process
env	string[]		Environment variables that are set into the container
cmd	string[]		Command with arguments that is executed upon the container’s start
I/O
open_stdin	bool		Open the terminal’s standard input for an interaction with the current container
tty	bool		Attach standard streams to a TTY
Resource management
memory	string		Hard memory limitation of the container as a number with a unit suffix of B, K, M and G, the minimum allowed value is 3M
memory_reservation	string		Soft memory limitation of the container as a number with a unit suffix of B, K, M and G, if `memory` is specified, the `memory_reservation` must be smaller than it
memory_swap	string		Total amount of memory and swap that the container can use as a number with a unit suffix of B, K, M and G, use -1 to allow the container to use unlimited swap
Lifecycle
type	string	unless-stopped	The container’s restart policy, the supported types are: always, no, on-failure and unless-stopped
maximum_retry_count	int		Maximum number of retries that are made to restart the container on exit with fail, if the `type` is on-failure
retry_timeout	int		Timeout period in seconds for each retry that is made to restart the container on exit with fail, if the `type` is on-failure
Logging
type	string	json-file	Type in which the logs are produced, the possible options are: json-file or none
max_files	int	2	Maximum log files before getting rotated
max_size	string	100M	Maximum log file size before getting rotated as a number with a unit suffix of B, K, M and G
root_dir	string	<meta_path>/containers/<container_id>	Root directory where the container’s log messages are stored
mode	string	blocking	Messaging delivery mode from the container to the log driver, the supported modes are: blocking and non-blocking
max_buffer_size	string	1M	Maximum size of the buffered container’s log messages in a non-blocking mode as a number with a unit suffix of B, K, M and G

Example

The minimal required configuration to spin up an InfluxDB container instance.

{
  "image": {
    "name": "docker.io/library/influxdb:1.8.4"
  }
}

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 require property removal

{
    "container_name": "",
    "image": {
        "name": "",
        "decrypt_config": {
            "keys": [],
            "recipients": []
        }
    },
    "domain_name": "",
    "host_name": "",
    "mount_points": [
        {
            "destination": "",
            "source": "",
            "propagation_mode": "rprivate"
        }
    ],
    "config": {
        "env": [],
        "cmd": []
    },
    "io_config": {
        "open_stdin": false,
        "tty": false
    },
    "host_config": {
        "devices": [
            {
                "path_on_host": "",
                "path_in_container": "",
                "cgroup_permissions": "rwm"
            }
        ],
        "network_mode": "bridge",
        "privileged": false,
        "extra_hosts": [],
        "port_mappings": [
            {
                "proto": "tcp",
                "container_port": 0,
                "host_ip": "0.0.0.0",
                "host_port": 0,
                "host_port_end": 0
            }
        ],
        "resources": {
            "memory": "",
            "memory_reservation": "",
            "memory_swap": ""
        },
        "restart_policy": {
            "type": "unless-stopped",
            "maximum_retry_count": 0,
            "retry_timeout": 0
        },
        "log_config": {
            "driver_config": {
                "type": "json-file",
                "max_files": 2,
                "max_size": "100M",
                "root_dir": ""
            },
            "mode_config": {
                "mode": "blocking",
                "max_buffer_size": "1M"
            }
        }
    }
}

3.2 - Manager configuration

Customize the container manager components.

Properties

To control all aspects of the container manager behavior.

Property	Type	Default	Description
home_dir	string	/var/lib/container-management	Home directory for the container manager data
exec_root_dir	string	/var/run/container-management	Root directory for the container manager’s executable artifacts
container_client_sid	string	container-management.service.local.v1.service-containerd-client	Unique identifier that is used for an interaction with the runtime
network_manager_sid	string	container-management.service.local.v1.service-libnetwork-manager	Unique identifier that is used for networking
default_ctrs_stop_timeout	int	30	Timeout in seconds for a container to stop gracefully, otherwise its root process will be force stopped
Runtime
default_ns	string	kanto-cm	Namespace that is used by the runtime for isolation
address_path	string	/run/containerd/containerd.sock	Path to the runtime’s communication endpoint
home_dir	string	/var/lib/container-management	Home directory for the runtime data
exec_root_dir	string	/var/run/container-management	Root directory for the runtime’s executable artifacts
image_dec_keys	string[]		Private keys (GPG private key ring, JWE or PKCS7) used for decrypting container images, the format is: `filepath_private_key[:password]`
image_dec_recipients	string[]		Recipients (only for PKCS7 and must be an x509) used for decrypting container images, the format is: `pkcs7:filepath_x509_certificate`
runc_runtime	string	io.containerd.runc.v2	Runc communication mode, the possible values are: io.containerd.runtime.v1.linux, io.containerd.runc.v1 and io.containerd.runc.v2
image_expiry	string	744h	Time period for the cached images and content to be kept in the form of e.g. 72h3m0.5s
image_expiry_disable	bool	false	Disable expiry management of cached images and content, must be used with caution as it may lead to large memory volumes being persistently allocated
lease_id	string	kanto-cm.lease	Lease identifier to be used for container resources persistence
Registry access - secure
user_id	string		User unique identifier to authenticate to the image registry
password	string		Password to authenticate to the image registry
root_ca	string		PEM encoded CA certificates file
client_cert	string		PEM encoded certificate file to authenticate to the image registry
client_key	string		PEM encoded unencrypted private key file to authenticate to the image registry
Registry access - insecure
insecure_registries	string[]	localhost	Image registries that do not use valid certificates or do not require a HTTPS connection, the format is: `host[:port]`
Networking
home_dir	string	/var/lib/container-management	Home directory for the network manager data
exec_root_dir	string	/var/run/container-management	Root directory for the network manager’s executable artifacts
Networking - bridge
name	string	kanto-cm0	Bridge name
ip4	string		Bridge IPv4 address
fcidr4	string		IPv4 address range for the bridge, using the standard CIDR notation
gwip4	string		Bridge gateway IPv4 address
enable_ip6	bool	false	Permit the bridge IPv6 support
mtu	int	1500	Bridge maximum transmission unit in bytes
icc	bool	true	Permit the inter-container communication
ip_tables	bool	true	Permit the IP tables rules
ip_forward	bool	true	Permit the IP forwarding
ip_masq	bool	true	Permit the IP masquerading
userland_proxy	bool	false	Forbid the userland proxy for the loopback traffic
Local communication
protocol	string	unix	Communication protocol used for accessing the gRPC server, the possible values are: tcp, tcp4, tcp6, unix or unixpacket
address_path	string	/run/container-management/container-management.sock	Path to the gRPC server’s communication endpoint
Digital twin
enable	bool	true	Permit the container manager digital twin representation
home_dir	string	/var/lib/container-management	Home directory for the digital twin data
features	string[]	ContainerFactory, SoftwareUpdatable, Metrics	Features that will be registered for the container manager digital twin, the possible values are: ContainerFactory, SoftwareUpdatable and Metrics
Digital twin - connectivity
broker_url	string	tcp://localhost:1883	Address of the MQTT server/broker that the container manager will connect for the local communication, the format is: `scheme://host:port`
keep_alive	int	20000	Keep alive duration in milliseconds for the MQTT requests
disconnect_timeout	int	250	Disconnect timeout in milliseconds for the MQTT server/broker
client_username	string		Username that is a part of the credentials
client_password	string		Password that is a part of the credentials
connect_timeout	int	30000	Connect timeout in milliseconds for the MQTT server/broker
acknowledge_timeout	int	15000	Acknowledge timeout in milliseconds for the MQTT requests
subscribe_timeout	int	15000	Subscribe timeout in milliseconds for the MQTT requests
unsubscribe_timeout	int	5000	Unsubscribe timeout in milliseconds for the MQTT requests
Digital twin - connectivity - TLS
root_ca	string		PEM encoded CA certificates file
client_cert	string		PEM encoded certificate file to authenticate to the MQTT server/broker
client_key	string		PEM encoded unencrypted private key file to authenticate to the MQTT server/broker
Logging
log_file	string	log/container-management.log	Path to the file where the container manager’s log messages are written
log_level	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
log_file_count	int	5	Log file maximum rotations count
log_file_max_age	int	28	Log file rotations maximum age in days, use 0 to not remove old log files
log_file_size	int	2	Log file size in MB before it gets rotated
syslog	bool	false	Route logs to the local syslog
Deployment
enable	bool	true	Permit the deployment manager service providing installation/update of containers via the container descriptor files
mode	string	update	Deployment manager mode, the possible values are: init (container descriptors are processed only on first start, new containers are deployed and started), update (container descriptors are processed on each restart, new containers can be deployed and started, existing containers may be updated, no container removals)
home_dir	string	/var/lib/container-management	Home directory for the deployment manager data
ctr_dir	string	/etc/container-management/containers	Directory containing descriptors of containers that will be automatically deployed on first start or updated on restart

Example

The minimal required configuration that sets a timeout period of 5 seconds for the managed containers to stop gracefully.

{
    "manager": {
        "default_ctrs_stop_timeout": 5
    },
    "log": {
        "log_file": "/var/log/container-management/container-management.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 in the registry configuration the host (used as a key) has to be set instead of the default empty string, the format is: host[:port]

{
    "manager": {
        "home_dir": "/var/lib/container-management",
        "exec_root_dir": "/var/run/container-management",
        "container_client_sid": "container-management.service.local.v1.service-containerd-client",
        "network_manager_sid": "container-management.service.local.v1.service-libnetwork-manager",
        "default_ctrs_stop_timeout": 30
    },
    "containers": {
        "default_ns": "kanto-cm",
        "address_path": "/run/containerd/containerd.sock",
        "exec_root_dir": "/var/run/container-management",
        "home_dir": "/var/lib/container-management",
        "image_dec_keys": [],
        "image_dec_recipients": [],
        "runc_runtime": "io.containerd.runc.v2",
        "image_expiry": "744h",
        "image_expiry_disable": false,
        "lease_id": "kanto-cm.lease",
        "registry_configurations": {
            "": {
                "credentials": {
                    "user_id": "",
                    "password": ""
                },
                "transport": {
                    "root_ca": "",
                    "client_cert": "",
                    "client_key": ""
                }
            }
        },
        "insecure_registries": [
            "localhost"
        ]
    },
    "network": {
        "home_dir": "/var/lib/container-management",
        "exec_root_dir": "/var/run/container-management",
        "default_bridge": {
            "name": "kanto-cm0",
            "ip4": "",
            "fcidr4": "",
            "enable_ip6": false,
            "mtu": 1500,
            "icc": true,
            "ip_tables": true,
            "ip_forward": true,
            "ip_masq": true,
            "userland_proxy": false
        }
    },
    "grpc_server": {
        "protocol": "unix",
        "address_path": "/run/container-management/container-management.sock"
    },
    "things": {
        "enable": true,
        "home_dir": "/var/lib/container-management",
        "features": [
            "ContainerFactory",
            "SoftwareUpdatable",
            "Metrics"
        ],
        "connection": {
            "broker_url": "tcp://localhost:1883",
            "keep_alive": 20000,
            "disconnect_timeout": 250,
            "client_username": "",
            "client_password": "",
            "connect_timeout": 30000,
            "acknowledge_timeout": 15000,
            "subscribe_timeout": 15000,
            "unsubscribe_timeout": 5000,
            "transport": {
                "root_ca": "",
                "client_cert": "",
                "client_key": ""
            }
        }
    },
    "log": {
        "log_file": "log/container-management.log",
        "log_level": "INFO",
        "log_file_count": 5,
        "log_file_size": 2,
        "log_file_max_age": 28,
        "syslog": false
    },
    "deployment": {
        "enable": true,
        "mode": "update",
        "home_dir": "/var/lib/container-management",
        "ctr_dir": "/etc/container-management/containers"
    }
}

4 - Software update configuration

Customize the deployment and management of software artifacts.

Properties

To control all aspects of the software update behavior.

Property	Type	Default	Description
featureId	string	SoftwareUpdatable	Feature unique identifier in the scope of the edge digital twin
moduleType	string	software	Type of the software that is managed by this feature
artifactType	string	archive	Type of the artifact that is to be processed: archive or plain
install	string[]		Absolute path to the install script/command and an optional sequence of additional flags/parameters
storageLocation	string	./	Path to the storage directory where the working files are stored
installDirs	string[]		File system directories where the local artifacts are stored
mode	string	strict	Restriction where the local artifacts can be stored on the file system, the supported modes are: strict, lax and scope
Download
downloadRetryCount	int	0	Number of retries, in case of a failed download
downloadRetryInterval	string	5s	Interval between retries, in case of a failed download as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
Download - TLS
serverCert	string		PEM encoded certificate file for secure downloads
Local connectivity
broker	string	tcp://localhost:1883	Address of the MQTT server/broker that the software update will connect for the local communication, the format is: `scheme://host:port`
username	string		Username that is a part of the credentials
password	string		Password that is a part of the credentials
Logging
logFile	string	log/software-update.log	Path to the file where log messages are written
logLevel	string	INFO	All log messages at this or 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 that sets the software type to firmware.

{
    "moduleType": "firmware",
    "storageLocation": "/var/lib/software-update",
    "logFile": "/var/log/software-update/software-update.log"
}

Template

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

{
    "featureId": "SoftwareUpdatable",
    "moduleType": "software",
    "artifactType": "archive",
    "install": [],
    "storageLocation": "./",
    "installDirs": [],
    "mode": "strict",
    "downloadRetryCount": 0,
    "downloadRetryInterval": "5s",
    "serverCert": "",
    "broker": "tcp://localhost:1883",
    "username": "",
    "password": "",
    "logFile": "log/software-update.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

5 - File upload configuration

Customize the files transfer to a backend storage.

Properties

To control all aspects of the file upload behavior.

Property	Type	Default	Description
featureId	string	AutoUploadable	Feature unique identifier in the scope of the edge digital twin
type	string	file	Type of the files that are uploaded by this feature
context	string	edge	Context of the files that are uploaded by this feature, unique in the scope of the `type`
files	string		Glob pattern to select the files for upload
mode	string	strict	Restriction on files that can be dynamically selected for an upload, the supported modes are: strict, lax and scoped
singleUpload	bool	false	Forbid triggering of new uploads when there is an upload in progress
checksum	bool	false	Send MD5 checksum for uploaded files to ensure data integrity
stopTimeout	string	30s	Time to wait for running uploads to finish as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
delete	bool	false	Delete successfully uploaded files
Upload - TLS
serverCert	string		PEM encoded certificate file for secure uploads
Auto upload
active	bool	false	Activate periodic uploads
activeFrom	string		Time from which periodic uploads should be active, in RFC 3339 format, if omitted (and `active` flag is set) current time will be used as start of the periodic uploads
activeTill	string		Time till which periodic uploads should be active, in RFC 3339 format, if omitted (and `active` flag is set) periodic uploads will be active indefinitely
period	string	10h	Upload period as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
Local connectivity
broker	string	tcp://localhost:1883	Address of the MQTT server/broker that the file upload will connect for the local communication, the format is: `scheme://host:port`
username	string		Username that is a part of the credentials
password	string		Password that is a part of the credentials
Local connectivity - TLS
caCert	string		PEM encoded CA certificates file
cert	string		PEM encoded certificate file to authenticate to the MQTT server/broker
key	string		PEM encoded unencrypted private key file to authenticate to the MQTT server/broker
Logging
logFile	string	log/file-upload.log	Path to the file where log messages are written
logLevel	string	INFO	All log messages at this or 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 that sets the file type to log.

{
    "type": "log",
    "files": "/var/tmp/file-upload/*.*",
    "logFile": "/var/log/file-upload/file-upload.log"
}

Template

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

{
    "featureId": "AutoUploadable",
    "type": "file",
    "context": "edge",
    "files": "",
    "mode": "strict",
    "singleUpload": false,
    "checksum": false,
    "stopTimeout": "30s",
    "delete": false,
    "serverCert": "",
    "active": false,
    "activeFrom": "",
    "activeTill": "",
    "period": "10h",
    "broker": "tcp://localhost:1883",
    "username": "",
    "password": "",
    "caCert": "",
    "cert": "",
    "key": "",
    "logFile": "log/file-upload.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

6 - File backup configuration

Customize the files backup and restore to and from a backend storage.

Properties

To control all aspects of the file backup behavior.

Property	Type	Default	Description
featureId	string	BackupAndRestore	Feature unique identifier in the scope of the edge digital twin
type	string	file	Type of the files that are backed up by this feature
context	string	edge	Context of the files backed up by this feature, unique in the scope of the `type`
dir	string		Directory to be backed up
mode	string	strict	Restriction on directories that can be dynamically selected for a backup, the supported modes are: strict, lax and scoped
backupCmd	string		Command to be executed before the backup is done
restoreCmd	string		Command to be executed after the restore
singleUpload	bool	false	Forbid triggering of new backups when there is a backup in progress
checksum	bool	false	Send MD5 checksum for backed up files to ensure data integrity
stopTimeout	string	30s	Time to wait for running backups to finish as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
keepUploaded	bool	false	Keep successfully uploaded backups locally
storage	string	./storage	Directory where backups and downloads will be stored
Upload/Download - TLS
serverCert	string		PEM encoded certificate file for secure uploads and downloads
Auto backup
active	bool	false	Activate periodic backups
activeFrom	string		Time from which periodic backups should be active, in RFC 3339 format, if omitted (and `active` flag is set) current time will be used as start of the periodic backups
activeTill	string		Time till which periodic backups should be active, in RFC 3339 format, if omitted (and `active` flag is set) periodic backups will be active indefinitely
period	string	10h	Backup period as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
Local connectivity
broker	string	tcp://localhost:1883	Address of the MQTT server/broker that the file backup will connect for the local communication, the format is: `scheme://host:port`
username	string		Username that is a part of the credentials
password	string		Password that is a part of the credentials
Local connectivity - TLS
caCert	string		PEM encoded CA certificates file
cert	string		PEM encoded certificate file to authenticate to the MQTT server/broker
key	string		PEM encoded unencrypted private key file to authenticate to the MQTT server/broker
Logging
logFile	string	log/file-backup.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 that enables backing up a directory and sets the file type to config.

{
    "type": "config",
    "dir": "/var/tmp/file-backup",
    "mode": "scoped",
    "storage": "/var/lib/file-backup",
    "logFile": "/var/log/file-backup/file-backup.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.

{
  "featureId": "BackupAndRestore",
  "type": "file",
  "context": "edge",
  "dir": "",
  "mode": "strict",
  "backupCmd": "",
  "restoreCmd": "",
  "singleUpload": false,
  "checksum": false,
  "stopTimeout": "30s",
  "keepUploaded": false,
  "storage": "./storage",
  "serverCert": "",
  "active": false,
  "activeFrom": "",
  "activeTill": "",
  "period": "10h",
  "broker": "tcp://localhost:1883",
  "username": "",
  "password": "",
  "caCert": "",
  "cert": "",
  "key": "",
  "logFile": "log/file-backup.log",
  "logLevel": "INFO",
  "logFileCount": 5,
  "logFileMaxAge": 28,
  "logFileSize": 2
}

7 - System metrics configuration

Customize the reporting of system metrics.

Properties

To control all aspects of the system metrics behavior.

Property	Type	Default	Description
frequency	string		Initial system metrics reporting frequency as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
Local connectivity
broker	string	tcp://localhost:1883	Address of the MQTT server/broker that the system metrics will connect for the local communication, the format is: `scheme://host:port`
username	string		Username that is a part of the credentials
password	string		Password that is a part of the credentials
Logging
logFile	string	log/system-metrics.log	Path to the file where log messages are written
logLevel	string	INFO	All log messages at this or 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 that enables the auto reporting of system metrics.

{
    "frequency": "60s",
    "logFile": "/var/log/system-metrics/system-metrics.log"
}

Template

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

{
    "frequency" : ""
    "broker": "tcp://localhost:1883",
    "username": "",
    "password": "",
    "logFile": "log/system-metrics.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}