Protocol Adapters use the Command Router API to supply information that the Command Router service component can use to route command & control messages to the particular protocol adapter instances that the target devices are connected to.
The Command Router component provides an implementation of the Command Router API which uses a remote data grid for storing information about device connections. The data grid can be scaled out independently from the Command Router service components to meet the storage demands at hand.
The Command Router is implemented as a Quarkus application. It can be run either directly from the command line or by means of starting the corresponding Docker image created from it.
Info
The Command Router had originally been implemented as a Spring Boot application. That variant has been removed in Hono 2.0.0.
Service Configuration
The following table provides an overview of the configuration variables and corresponding system properties for configuring the Command Router component.
OS Environment VariableJava System PropertyMandatoryDefaultDescription
HONO_APP_MAXINSTANCES
hono.app.maxInstances
no#CPU coresThe number of Verticle instances to deploy. If not set, one Verticle per processor core is deployed.HONO_COMMANDROUTER_AMQP_BINDADDRESS
hono.commandRouter.amqp.bindAddress
no127.0.0.1
The IP address of the network interface that the secure AMQP port should be bound to.See below for details.
HONO_COMMANDROUTER_AMQP_CERTPATH
hono.commandRouter.amqp.certPath
no-The absolute path to the PEM file containing the certificate that the server should use for authenticating to clients. This option must be used in conjunction with HONO_COMMANDROUTER_AMQP_KEYPATH
.Alternatively, the
HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
option can be used to configure a key store containing both the key as well as the certificate.HONO_COMMANDROUTER_AMQP_INSECUREPORT
hono.app.maxInstances
0no-The insecure port the server should listen on for AMQP 1.0 connections.See below for details.
hono.app.maxInstances
1hono.app.maxInstances
2no127.0.0.1
The IP address of the network interface that the insecure AMQP port should be bound to.See below for details.
hono.app.maxInstances
4hono.app.maxInstances
5nohono.app.maxInstances
6If set to hono.app.maxInstances
7 the server will open an insecure port [not secured by TLS] using either the port number set via HONO_COMMANDROUTER_AMQP_INSECUREPORT
or the default AMQP port number [hono.app.maxInstances
9] if not set explicitly.See below for details.
HONO_COMMANDROUTER_AMQP_KEYPATH
HONO_COMMANDROUTER_AMQP_BINDADDRESS
1no-The absolute path to the [PKCS8] PEM file containing the private key that the server should use for authenticating to clients. This option must be used in conjunction with HONO_COMMANDROUTER_AMQP_CERTPATH
. Alternatively, the HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
option can be used to configure a key store containing both the key as well as the certificate.HONO_COMMANDROUTER_AMQP_BINDADDRESS
4HONO_COMMANDROUTER_AMQP_BINDADDRESS
5no-The password required to read the contents of the key store.HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
HONO_COMMANDROUTER_AMQP_BINDADDRESS
7no-The absolute path to the Java key store containing the private key and certificate that the server should use for authenticating to clients. Either this option or the HONO_COMMANDROUTER_AMQP_KEYPATH
and HONO_COMMANDROUTER_AMQP_CERTPATH
options need to be set in order to enable TLS secured connections with clients. The key store format can be either hono.commandRouter.amqp.bindAddress
0 or hono.commandRouter.amqp.bindAddress
1 indicated by a hono.commandRouter.amqp.bindAddress
2 or hono.commandRouter.amqp.bindAddress
3 file suffix respectively.hono.commandRouter.amqp.bindAddress
4hono.commandRouter.amqp.bindAddress
5nohono.app.maxInstances
6The server will probe for OpenSSL on startup if a secure port is configured. By default, the server will fall back to the JVM’s default SSL engine if not available. However, if set to hono.app.maxInstances
7, the server will fail to start at all in this case.hono.commandRouter.amqp.bindAddress
8hono.commandRouter.amqp.bindAddress
9no127.0.0.1
0The secure port that the server should listen on for AMQP 1.0 connections.See below for details.
127.0.0.1
1127.0.0.1
2no127.0.0.1
3The number of credits to flow to a client connecting to the service’s AMQP endpoint.127.0.0.1
4127.0.0.1
5no127.0.0.1
6A [comma separated] list of secure protocols [in order of preference] that are supported when negotiating TLS sessions. Please refer to the for a list of supported protocol names.127.0.0.1
7127.0.0.1
8no-A [comma separated] list of names of cipher suites [in order of preference] that are supported when negotiating TLS sessions. Please refer to for a list of supported names.127.0.0.1
9HONO_COMMANDROUTER_AMQP_CERTPATH
0nohono.app.maxInstances
7If set to hono.app.maxInstances
7 and the Command Router component runs in a Kubernetes cluster, a Kubernetes based service to identify protocol adapter instances will be used to prevent sending command & control messages to already terminated adapter instances. Needs to be set to hono.app.maxInstances
6 if not all protocol adapters are part of the Kubernetes cluster and namespace that the Command Router component is in.The variables only need to be set if the default value does not match your environment.
In addition to the options described in the table above, this component supports the following standard configuration options:
- Monitoring Options
Port Configuration
The Command Router component supports configuration of an AMQP based endpoint that can be configured to listen for connections on
- a secure port only [default] or
- an insecure port only or
- both a secure and an insecure port [dual port configuration]
The server will fail to start if none of the ports is configured properly.
Secure Port Only
The server needs to be configured with a private key and certificate in order to open a TLS secured port.
There are two alternative ways for doing so:
- Setting the
HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
and theHONO_COMMANDROUTER_AMQP_BINDADDRESS
4 variables in order to load the key & certificate from a password protected key store, or - setting the
HONO_COMMANDROUTER_AMQP_KEYPATH
andHONO_COMMANDROUTER_AMQP_CERTPATH
variables in order to load the key and certificate from two separate PEM files in PKCS8 format.
When starting up, the server will bind a TLS secured socket to the default secure AMQP port 5671. The port number can also be set explicitly using the hono.commandRouter.amqp.bindAddress
8 variable.
The HONO_COMMANDROUTER_AMQP_BINDADDRESS
variable can be used to specify the network interface that the port should be exposed on. By default the port is bound to the loopback device only, i.e. the port will only be accessible from the local host. Setting this variable to hono.commandRouter.amqp.certPath
0 will let the port being bound to all network interfaces [be careful not to expose the port unintentionally to the outside world].
Insecure Port Only
The secure port will mostly be required for production scenarios. However, it might be desirable to expose a non-TLS secured port instead, e.g. for testing purposes. In any case, the non-secure port needs to be explicitly enabled either by
- explicitly setting
HONO_COMMANDROUTER_AMQP_INSECUREPORT
to a valid port number, or by - implicitly configuring the default AMQP port [5672] by simply setting
hono.app.maxInstances
4 tohono.app.maxInstances
7.
The server issues a warning on the console if HONO_COMMANDROUTER_AMQP_INSECUREPORT
is set to the default secure AMQP port [5671].
The hono.app.maxInstances
1 variable can be used to specify the network interface that the port should be exposed on. By default the port is bound to the loopback device only, i.e. the port will only be accessible from the local host. This variable might be used to e.g. expose the non-TLS secured port on a local interface only, thus providing easy access from within the local network, while still requiring encrypted communication when accessed from the outside over public network infrastructure.
Setting this variable to hono.commandRouter.amqp.certPath
0 will let the port being bound to all network interfaces [be careful not to expose the port unintentionally to the outside world].
Dual Port
In test setups and some production scenarios Hono server may be configured to open one secure and one insecure port at the same time.
This is achieved by configuring both ports correctly [see above]. The server will fail to start if both ports are configured to use the same port number.
Since the secure port may need different visibility in the network setup compared to the secure port, it has its own binding address hono.app.maxInstances
1. This can be used to narrow the visibility of the insecure port to a local network e.g., while the secure port may be visible worldwide.
Ephemeral Ports
Both the secure as well as the insecure port numbers may be explicitly set to hono.commandRouter.amqp.certPath
8. The Command Router component will then use arbitrary [unused] port numbers determined by the operating system during startup.
Messaging Configuration
The Command Router component uses a connection to an AMQP 1.0 Messaging Network and/or an Apache Kafka cluster to
- receive command & control messages sent by downstream applications and to forward these commands on a specific address/topic so that they can be received by protocol adapters,
- send delivery failure command response messages in case no consumer exists for a received command [only with Kafka messaging],
- receive notification messages about changes to tenant/device/credentials data sent from the device registry.
- send an event message for indicating the device readiness to receive commands.
Command messages are received on each configured messaging system.
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.commandRouter.amqp.certPath
9 and HONO_COMMANDROUTER_AMQP_KEYPATH
0 being used as HONO_COMMANDROUTER_AMQP_KEYPATH
1. 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 the component. The individual client configuration is optional, a minimal configuration may only contain a common client configuration consisting of properties prefixed with HONO_COMMANDROUTER_AMQP_KEYPATH
2 and HONO_COMMANDROUTER_AMQP_KEYPATH
3 respectively.
Java System Property PrefixDescription
HONO_COMMANDROUTER_AMQP_KEYPATH
4HONO_COMMANDROUTER_AMQP_KEYPATH
5Configures the Kafka admin client that removes Hono internal topics.HONO_COMMANDROUTER_AMQP_KEYPATH
6HONO_COMMANDROUTER_AMQP_KEYPATH
7Configures the Kafka consumer that receives command messages.HONO_COMMANDROUTER_AMQP_KEYPATH
8HONO_COMMANDROUTER_AMQP_KEYPATH
9Configures the Kafka producer that publishes command messages to Hono internal topics.HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
0HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
1Configures the Kafka producer that publishes command response messages.HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
2HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
3Configures the Kafka consumer that receives notification messages about changes to tenant/device/credentials data.Tenant Service Connection Configuration
The Command Router component requires 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 HONO_COMMANDROUTER_AMQP_KEYPATH
1 is set to HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
5 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
The Command Router component requires a connection to an implementation of Hono’s Device Registration API in order to retrieve registration status assertions for the target devices of incoming command messages.
The connection to the Device Registration Service is configured according to the Hono Client Configuration where the HONO_COMMANDROUTER_AMQP_KEYPATH
1 is set to HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
7.
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.
Data Grid Connection Configuration
The Command Router component requires either an embedded cache or a remote data grid, using the Infinispan Hotrod protocol to store device information.
The following table provides an overview of the configuration variables and corresponding command line options for configuring the common aspects of the service:
OS Environment VariableJava System PropertyMandatoryDefaultDescription
HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
8HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
9noHONO_COMMANDROUTER_AMQP_INSECUREPORT
0The name of the cacheHONO_COMMANDROUTER_AMQP_INSECUREPORT
1HONO_COMMANDROUTER_AMQP_INSECUREPORT
2noHONO_COMMANDROUTER_AMQP_INSECUREPORT
3The key used to check the health of the cache. This is only used in case of a remote cache.HONO_COMMANDROUTER_AMQP_INSECUREPORT
4HONO_COMMANDROUTER_AMQP_INSECUREPORT
5noHONO_COMMANDROUTER_AMQP_INSECUREPORT
6The value used to check the health of the cache. This is only used in case of a remote cache.The type of cache [embedded or remote] is determined during startup by means of the HONO_COMMANDROUTER_AMQP_INSECUREPORT
7 configuration variable. If the variable has a non empty value, a is configured. Otherwise, an is configured.
Remote cache
The following table provides an overview of the configuration variables and corresponding system properties for configuring the connection to the data grid:
OS Environment VariableJava System PropertyMandatoryDefaultDescription
HONO_COMMANDROUTER_AMQP_INSECUREPORT
7HONO_COMMANDROUTER_AMQP_INSECUREPORT
9yes-A list of remote servers in the form: hono.app.maxInstances
00.hono.app.maxInstances
01hono.app.maxInstances
02yes-The server name to indicate in the SASL handshake when authenticating to the server.hono.app.maxInstances
03hono.app.maxInstances
04yes-The authentication realm for the SASL handshake when authenticating to the server.hono.app.maxInstances
05hono.app.maxInstances
06yes-The username to use for authenticating to the server.hono.app.maxInstances
07hono.app.maxInstances
08yes-The password to use for authenticating to the server.hono.app.maxInstances
09hono.app.maxInstances
10yes-The SASL mechanism to use for authenticating to the server.hono.app.maxInstances
11hono.app.maxInstances
12no-Alternate cluster definition. Example:Property:
hono.app.maxInstances
13, value: hono.app.maxInstances
14.hono.app.maxInstances
15hono.app.maxInstances
16nohono.app.maxInstances
17Specifies what happens when asking for a connection from a server’s pool, and that pool is exhausted. Valid values are hono.app.maxInstances
17, hono.app.maxInstances
19 and hono.app.maxInstances
20.hono.app.maxInstances
21hono.app.maxInstances
22nohono.app.maxInstances
23 [no limit]Maximum number of connections per server.hono.app.maxInstances
24hono.app.maxInstances
25nohono.app.maxInstances
23 [no limit]Specifies the maximum number of requests sent over a single connection at one instant.hono.app.maxInstances
27hono.app.maxInstances
28nohono.app.maxInstances
23 [no limit]Time to wait in milliseconds for a connection to become available if hono.app.maxInstances
30 is hono.app.maxInstances
17.hono.app.maxInstances
32hono.app.maxInstances
33nohono.app.maxInstances
23 [no limit]Minimum amount of time that an connection may sit idle in the pool.hono.app.maxInstances
35hono.app.maxInstances
36nohono.app.maxInstances
23 [no limit]Minimum number of idle connections [per server] that should always be available.hono.app.maxInstances
38hono.app.maxInstances
39nohono.app.maxInstances
40The timeout for connections in milliseconds.hono.app.maxInstances
41hono.app.maxInstances
42nohono.app.maxInstances
43Size of the thread pool.hono.app.maxInstances
44hono.app.maxInstances
45nohono.app.maxInstances
46Prefix for the default executor thread names.hono.app.maxInstances
47hono.app.maxInstances
48no-Suffix for the default executor thread names.hono.app.maxInstances
49hono.app.maxInstances
50no-The alias of the key to use, in case the keyStore contains multiple certificates.hono.app.maxInstances
51hono.app.maxInstances
52no-The certificate password in the keystore.hono.app.maxInstances
53hono.app.maxInstances
54no-The filename of a keystore to use when using client certificate authentication.hono.app.maxInstances
55hono.app.maxInstances
56no-The keystore password.hono.app.maxInstances
57hono.app.maxInstances
58nohono.commandRouter.amqp.bindAddress
0The keystore type.hono.app.maxInstances
60hono.app.maxInstances
61no-A SASL property [specific to the used SASL mechanism].hono.app.maxInstances
62hono.app.maxInstances
63nohono.app.maxInstances
40The timeout for socket read/writes in milliseconds.hono.app.maxInstances
65hono.app.maxInstances
66no-A list of ciphers, separated with spaces and in order of preference, that are used during the SSL handshake to negotiate a cryptographic algorithm for key encryption. By default, the SSL protocol [e.g. TLSv1.2] determines which ciphers to use. You should customize the cipher list with caution to avoid vulnerabilities from weak algorithms. For details about cipher lists and possible values, refer to the OpenSSL documentation.hono.app.maxInstances
67hono.app.maxInstances
68no-The SSL protocol to use [e.g. hono.app.maxInstances
69].hono.app.maxInstances
70hono.app.maxInstances
71no-The path of the trust store.hono.app.maxInstances
72hono.app.maxInstances
73no-The password of the trust store.hono.app.maxInstances
74hono.app.maxInstances
75nohono.commandRouter.amqp.bindAddress
0The type of the trust store. Valid values are hono.commandRouter.amqp.bindAddress
0, hono.app.maxInstances
78, hono.app.maxInstances
79 and hono.app.maxInstances
80.hono.app.maxInstances
81hono.app.maxInstances
82nohono.app.maxInstances
6Enable TLS [implicitly enabled if a trust store is set].See also the .
Embedded cache
The following table provides an overview of the configuration variables and corresponding system properties for configuring the embedded cache:
OS Environment VariableJava System PropertyMandatoryDefaultDescription
hono.app.maxInstances
84hono.app.maxInstances
85yes-The absolute path to an Infinispan configuration file. Also see the Infinispan Configuration Schema.Authentication Service Connection Configuration
The service requires a connection to an implementation of Hono’s Authentication API in order to authenticate and authorize client requests.
The connection is configured according to the Hono Client Configuration where the HONO_COMMANDROUTER_AMQP_KEYPATH
1 is set to hono.app.maxInstances
87. The properties for configuring the client’s response caching will be ignored because Hono’s Authentication Service does not allow caching of responses.