Common Configuration

Many Hono components support a common set of configuration options. This section describes those options.

Each component which supports the following options explicitly states so. If it doesn’t, then these options are not supported by this component.

Java VM Options

The Java VM started in Hono’s components can be configured with arbitrary command line options by means of setting the JDK_JAVA_OPTIONS environment variable.

Vert.x Options

The vert.x framework instance used to run Hono’s components can be configured using the following environment variables or corresponding system properties:

Using Native Transport on Linux/MacOS

Using epoll() on Linux/MacOS may provide better performance for applications which have a high I/O throughput. Especially when the application supports an asynchronous I/O model. This is true for most Hono components and applications using Hono.

The Netty framework supports using epoll() on Linux/MacOS x86_64 based systems.

Hono’s components support native transport out of the box.

Protocol Adapter Options

Messaging Configuration

Protocol adapters use a connection to an AMQP 1.0 Messaging Network and/or an Apache Kafka cluster to

• forward telemetry data and events received from devices so that they can be received by downstream consumers,
• receive command & control messages sent from downstream applications (and forwarded by the command router component),
• forward command response messages to be received by downstream applications,
• receive notification messages about changes to tenant/device/credentials data sent from the device registry.

For telemetry and event messages a connection to a Apache Kafka cluster is used by default, if configured. If both kinds of messaging are configured, the decision which one to use is done according to the Tenant Configuration.

Command messages are received on each configured messaging system. Command response messages are sent on the kind of messaging system that was used for the corresponding command message.

For notification messages, the Kafka connection is used by default, if configured. Otherwise the AMQP messaging network is used.

AMQP 1.0 Messaging Network Connection Configuration

The connection to the AMQP 1.0 Messaging Network is configured according to the Hono Client Configuration with HONO_MESSAGING (for telemetry and event messages and notification messages) and HONO_COMMAND (for command and command response messages) being used as ${PREFIX}. Since there are no responses being received, the properties for configuring response caching can be ignored.

Kafka based Messaging Configuration

The connection to an Apache Kafka cluster can be configured according to the Hono Kafka Client Configuration.

The following table provides an overview of the prefixes to be used to individually configure the Kafka clients used by a protocol adapter. The individual client configuration is optional, a minimal configuration may only contain a common client configuration consisting of properties prefixed with HONO_KAFKA_COMMONCLIENTCONFIG_ and hono.kafka.commonClientConfig. respectively.

Tenant Service Connection Configuration

Protocol adapters require a connection to an implementation of Hono’s Tenant API in order to retrieve information for a tenant.

The connection to the Tenant Service is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_TENANT and the additional values for response caching apply.

The adapter caches the responses from the service according to the cache directive included in the response. If the response doesn’t contain a cache directive no data will be cached.

Device Registration Service Connection Configuration

Protocol adapters require a connection to an implementation of Hono’s Device Registration API in order to retrieve registration status assertions for connected devices.

The connection to the Device Registration Service is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_REGISTRATION.

The adapter caches the responses from the service according to the cache directive included in the response. If the response doesn’t contain a cache directive no data will be cached.

Note that the adapter uses a single cache for all responses from the service regardless of the tenant identifier. Consequently, the Device Registration Service client configuration’s responseCacheMinSize and responseCacheMaxSize properties determine the overall number of responses that can be cached.

Credentials Service Connection Configuration

Protocol adapters require a connection to an implementation of Hono’s Credentials API in order to retrieve credentials stored for devices that needs to be authenticated. During connection establishment, the adapter uses the Credentials API to retrieve the credentials on record for the device and matches that with the credentials provided by a device.

The connection to the Credentials Service is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_CREDENTIALS.

The adapter caches the responses from the service according to the cache directive included in the response. If the response doesn’t contain a cache directive no data will be cached.

Note that the adapter uses a single cache for all responses from the service regardless of the tenant identifier. Consequently, the Credentials Service client configuration’s responseCacheMinSize and responseCacheMaxSize properties determine the overall number of responses that can be cached.

Command Router Service Connection Configuration

Protocol adapters connect to an implementation of Hono’s Command Router API in order to supply information with which a Command Router service component can route command & control messages to the protocol adapters that the target devices are connected to.

The connection to the Command Router service is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_COMMANDROUTER.

Responses from the Command Router service are never cached, so the properties for configuring the cache are ignored.

Resource Limits Checker Configuration

The adapter can use metrics collected by a Prometheus server to enforce certain limits set at the tenant level like the overall number of connected devices allowed per tenant.

The following table provides an overview of the configuration variables and corresponding system properties for configuring the checker.

In addition to the properties listed above, the resource limit checker also supports the properties listed below as documented in the Hono Client Configuration. These properties might be useful if a reverse proxy in front of the Prometheus server requires the client to use TLS and/or provide credentials for authentication.

• HONO_RESOURCELIMITS_PROMETHEUSBASED_CREDENTIALSPATH
• HONO_RESOURCELIMITS_PROMETHEUSBASED_HOSTNAMEVERIFICATIONREQUIRED
• HONO_RESOURCELIMITS_PROMETHEUSBASED_KEYPATH
• HONO_RESOURCELIMITS_PROMETHEUSBASED_KEYSTOREPASSWORD
• HONO_RESOURCELIMITS_PROMETHEUSBASED_KEYSTOREPATH
• HONO_RESOURCELIMITS_PROMETHEUSBASED_PASSWORD
• HONO_RESOURCELIMITS_PROMETHEUSBASED_SECUREPROTOCOLS
• HONO_RESOURCELIMITS_PROMETHEUSBASED_TLSENABLED
• HONO_RESOURCELIMITS_PROMETHEUSBASED_TRUSTSTOREPATH
• HONO_RESOURCELIMITS_PROMETHEUSBASED_TRUSTSTOREPASSWORD
• HONO_RESOURCELIMITS_PROMETHEUSBASED_USERNAME

Connection Event Producer Configuration

Some of the protocol adapters report the establishment and termination of a connection with a device by means of a Connection Event Producer.

The producer being used by the adapter can be configured as follows:

The events based connection event producer sets the TTL of event messages that it emits to the max TTL configured at the tenant level.