What does the command routera(config)#line cons 0 allow you to perform next?

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 Variable
Java System PropertyMandatoryDefaultDescriptionHONO_APP_MAXINSTANCES
hono.app.maxInstancesno#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.bindAddressno127.0.0.1The 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.certPathno-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.maxInstances0no-The insecure port the server should listen on for AMQP 1.0 connections.
See below for details.hono.app.maxInstances1
hono.app.maxInstances2no127.0.0.1The IP address of the network interface that the insecure AMQP port should be bound to.
See below for details.hono.app.maxInstances4
hono.app.maxInstances5nohono.app.maxInstances6If set to hono.app.maxInstances7 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.maxInstances9) if not set explicitly.
See below for details.HONO_COMMANDROUTER_AMQP_KEYPATH
HONO_COMMANDROUTER_AMQP_BINDADDRESS1no-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_BINDADDRESS4
HONO_COMMANDROUTER_AMQP_BINDADDRESS5no-The password required to read the contents of the key store.HONO_COMMANDROUTER_AMQP_KEYSTOREPATH
HONO_COMMANDROUTER_AMQP_BINDADDRESS7no-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.bindAddress0 or hono.commandRouter.amqp.bindAddress1 indicated by a hono.commandRouter.amqp.bindAddress2 or hono.commandRouter.amqp.bindAddress3 file suffix respectively.hono.commandRouter.amqp.bindAddress4
hono.commandRouter.amqp.bindAddress5nohono.app.maxInstances6The 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.maxInstances7, the server will fail to start at all in this case.hono.commandRouter.amqp.bindAddress8
hono.commandRouter.amqp.bindAddress9no127.0.0.10The secure port that the server should listen on for AMQP 1.0 connections.
See below for details.127.0.0.11
127.0.0.12no127.0.0.13The number of credits to flow to a client connecting to the service’s AMQP endpoint.127.0.0.14
127.0.0.15no127.0.0.16A (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.17
127.0.0.18no-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.19
HONO_COMMANDROUTER_AMQP_CERTPATH0nohono.app.maxInstances7If set to hono.app.maxInstances7 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.maxInstances6 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:

1. Setting the HONO_COMMANDROUTER_AMQP_KEYSTOREPATH and the HONO_COMMANDROUTER_AMQP_BINDADDRESS4 variables in order to load the key & certificate from a password protected key store, or
2. setting the HONO_COMMANDROUTER_AMQP_KEYPATH and HONO_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.bindAddress8 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.certPath0 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.maxInstances4 to hono.app.maxInstances7.

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.maxInstances1 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.certPath0 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.maxInstances1. 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.certPath8. 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.certPath9 and HONO_COMMANDROUTER_AMQP_KEYPATH0 being used as HONO_COMMANDROUTER_AMQP_KEYPATH1. 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_KEYPATH2 and HONO_COMMANDROUTER_AMQP_KEYPATH3 respectively.

OS Environment Variable Prefix
Java System Property PrefixDescriptionHONO_COMMANDROUTER_AMQP_KEYPATH4
HONO_COMMANDROUTER_AMQP_KEYPATH5Configures the Kafka admin client that removes Hono internal topics.HONO_COMMANDROUTER_AMQP_KEYPATH6
HONO_COMMANDROUTER_AMQP_KEYPATH7Configures the Kafka consumer that receives command messages.HONO_COMMANDROUTER_AMQP_KEYPATH8
HONO_COMMANDROUTER_AMQP_KEYPATH9Configures the Kafka producer that publishes command messages to Hono internal topics.HONO_COMMANDROUTER_AMQP_KEYSTOREPATH0
HONO_COMMANDROUTER_AMQP_KEYSTOREPATH1Configures the Kafka producer that publishes command response messages.HONO_COMMANDROUTER_AMQP_KEYSTOREPATH2
HONO_COMMANDROUTER_AMQP_KEYSTOREPATH3Configures 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_KEYPATH1 is set to HONO_COMMANDROUTER_AMQP_KEYSTOREPATH5 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_KEYPATH1 is set to HONO_COMMANDROUTER_AMQP_KEYSTOREPATH7.

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 Variable
Java System PropertyMandatoryDefaultDescriptionHONO_COMMANDROUTER_AMQP_KEYSTOREPATH8
HONO_COMMANDROUTER_AMQP_KEYSTOREPATH9noHONO_COMMANDROUTER_AMQP_INSECUREPORT0The name of the cacheHONO_COMMANDROUTER_AMQP_INSECUREPORT1
HONO_COMMANDROUTER_AMQP_INSECUREPORT2noHONO_COMMANDROUTER_AMQP_INSECUREPORT3The key used to check the health of the cache. This is only used in case of a remote cache.HONO_COMMANDROUTER_AMQP_INSECUREPORT4
HONO_COMMANDROUTER_AMQP_INSECUREPORT5noHONO_COMMANDROUTER_AMQP_INSECUREPORT6The 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_INSECUREPORT7 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 Variable
Java System PropertyMandatoryDefaultDescriptionHONO_COMMANDROUTER_AMQP_INSECUREPORT7
HONO_COMMANDROUTER_AMQP_INSECUREPORT9yes-A list of remote servers in the form: hono.app.maxInstances00.hono.app.maxInstances01
hono.app.maxInstances02yes-The server name to indicate in the SASL handshake when authenticating to the server.hono.app.maxInstances03
hono.app.maxInstances04yes-The authentication realm for the SASL handshake when authenticating to the server.hono.app.maxInstances05
hono.app.maxInstances06yes-The username to use for authenticating to the server.hono.app.maxInstances07
hono.app.maxInstances08yes-The password to use for authenticating to the server.hono.app.maxInstances09
hono.app.maxInstances10yes-The SASL mechanism to use for authenticating to the server.hono.app.maxInstances11
hono.app.maxInstances12no-Alternate cluster definition. Example:
Property: hono.app.maxInstances13, value: hono.app.maxInstances14.hono.app.maxInstances15
hono.app.maxInstances16nohono.app.maxInstances17Specifies what happens when asking for a connection from a server’s pool, and that pool is exhausted. Valid values are hono.app.maxInstances17, hono.app.maxInstances19 and hono.app.maxInstances20.hono.app.maxInstances21
hono.app.maxInstances22nohono.app.maxInstances23 (no limit)Maximum number of connections per server.hono.app.maxInstances24
hono.app.maxInstances25nohono.app.maxInstances23 (no limit)Specifies the maximum number of requests sent over a single connection at one instant.hono.app.maxInstances27
hono.app.maxInstances28nohono.app.maxInstances23 (no limit)Time to wait in milliseconds for a connection to become available if hono.app.maxInstances30 is hono.app.maxInstances17.hono.app.maxInstances32
hono.app.maxInstances33nohono.app.maxInstances23 (no limit)Minimum amount of time that an connection may sit idle in the pool.hono.app.maxInstances35
hono.app.maxInstances36nohono.app.maxInstances23 (no limit)Minimum number of idle connections (per server) that should always be available.hono.app.maxInstances38
hono.app.maxInstances39nohono.app.maxInstances40The timeout for connections in milliseconds.hono.app.maxInstances41
hono.app.maxInstances42nohono.app.maxInstances43Size of the thread pool.hono.app.maxInstances44
hono.app.maxInstances45nohono.app.maxInstances46Prefix for the default executor thread names.hono.app.maxInstances47
hono.app.maxInstances48no-Suffix for the default executor thread names.hono.app.maxInstances49
hono.app.maxInstances50no-The alias of the key to use, in case the keyStore contains multiple certificates.hono.app.maxInstances51
hono.app.maxInstances52no-The certificate password in the keystore.hono.app.maxInstances53
hono.app.maxInstances54no-The filename of a keystore to use when using client certificate authentication.hono.app.maxInstances55
hono.app.maxInstances56no-The keystore password.hono.app.maxInstances57
hono.app.maxInstances58nohono.commandRouter.amqp.bindAddress0The keystore type.hono.app.maxInstances60
hono.app.maxInstances61no-A SASL property (specific to the used SASL mechanism).hono.app.maxInstances62
hono.app.maxInstances63nohono.app.maxInstances40The timeout for socket read/writes in milliseconds.hono.app.maxInstances65
hono.app.maxInstances66no-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.maxInstances67
hono.app.maxInstances68no-The SSL protocol to use (e.g. hono.app.maxInstances69).hono.app.maxInstances70
hono.app.maxInstances71no-The path of the trust store.hono.app.maxInstances72
hono.app.maxInstances73no-The password of the trust store.hono.app.maxInstances74
hono.app.maxInstances75nohono.commandRouter.amqp.bindAddress0The type of the trust store. Valid values are hono.commandRouter.amqp.bindAddress0, hono.app.maxInstances78, hono.app.maxInstances79 and hono.app.maxInstances80.hono.app.maxInstances81
hono.app.maxInstances82nohono.app.maxInstances6Enable 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 Variable
Java System PropertyMandatoryDefaultDescriptionhono.app.maxInstances84
hono.app.maxInstances85yes-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_KEYPATH1 is set to hono.app.maxInstances87. The properties for configuring the client’s response caching will be ignored because Hono’s Authentication Service does not allow caching of responses.