Hono Client Configuration

Hono comes with a set of Java packages that contain classes for interacting with Hono’s service components via AMQP 1.0. Hono’s protocol adapters use these classes to query the device registry, receive commands and to forward events, telemetry and command response messages to downstream business applications.

All these classes require an instance of org.eclipse.hono.client.amqp.connection.HonoConnection which represents an AMQP 1.0 connection to a peer. The properties of the connection can be configured by means of environment variables and/or Java system properties. All these variables share a common prefix. This way, multiple sets of variables can be used to configure multiple connections to different service endpoints without interfering with each other. For example, the set of variables for configuring a protocol adapter’s connection to the Device Registration service use the common prefix HONO_REGISTRATION whereas the set of variables for configuring the connection to the Credentials service use the HONO_CREDENTIALS prefix.

Connection Properties

The following table provides an overview of the environment variables and corresponding system properties for configuring an AMQP connection to a peer. Note that the variables map to the properties of class org.eclipse.hono.client.amqp.config.ClientConfigProperties which can be used to configure a client programmatically.

The variable names contain ${PREFIX} as a placeholder for the particular common prefix being used. The ${prefix} placeholder used in the Java system properties is the same as ${PREFIX}, using all lower case characters and . instead of _ as the delimiter, e.g. the environment variable prefix HONO_CREDENTIALS corresponds to the Java system property prefix hono.credentials.

Response Caching

The clients for interacting with the device registry services support the caching of responses received in response to service invocations. Caching can greatly improve performance by preventing repeated (and costly) invocations of remote service operations using the same request parameters. However, it usually only makes sense for resources that do not change too frequently.

The clients follow the approach to caching used in HTTP 1.1. In particular, they consider cache directives that a service includes in the response messages it sends back to the client.

Instances of org.eclipse.hono.client.amqp.AbstractRequestResponseServiceClient that have been created with a response cache being passed into their constructor will cache responses to service invocations based on the following rules:

1. If the response contains a no-cache directive, the response is not cached at all.
2. Otherwise, if the response contains a max-age directive, the response is cached for the number of seconds determined as the minimum of the value contained in the directive and the value of the ${PREFIX}_RESPONSECACHEDEFAULTTIMEOUT variable.
3. Otherwise, if the response message does not contain any of the above directives and the response’s status code is one of the codes defined in RFC 2616, Section 13.4 Response Cacheability, the response is put to the cache using the default timeout defined by the ${PREFIX}_RESPONSECACHEDEFAULTTIMEOUT variable as the maximum age.

The following table provides an overview of the environment variables and corresponding system properties for configuring the clients’ caching behavior. Note that the variables map to the properties of class org.eclipse.hono.client.amqp.config.RequestResponseClientConfigProperties which can be used to configure a client programmatically.

Using TLS

The factory can be configured to use TLS for

• authenticating the server during connection establishment and
• (optionally) authenticating to the server using a client certificate (if the server supports this)

In order to authenticate the server by means of the server’s certificate, the factory needs to be configured with a trust anchor containing the certificate authorities that the client trusts. The trust anchor can be configured explicitly by means of the ${PREFIX}_TRUSTSTOREPATH and ${PREFIX}_TRUSTSTOREPASSWORD variables. This is most useful in cases where the server’s certificate has not been signed by one of the public root CAs that are contained in the JRE’s standard trust store. However, if the server does use a certificate signed by such a public CA, then it is sufficient to set the ${PREFIX}_TLSENABLED variable to true in order for the client to support TLS when connecting to the server.

The client can also be configured to authenticate to the server by means of an X.509 client certificate if the server is configured to support this. The ${PREFIX}_CERTPATH and ${PREFIX}_KEYPATH variables can be used to set the paths to PEM files containing the certificate and private key. Alternatively, the ${PREFIX}_KEYSTOREPATH and ${PREFIX}_KEYSTOREPASSWORD variables can be used to set the path and password of a key store which contains both the certificate as well as the private key.

The factory supports TLS 1.2 only by default for negotiating TLS sessions with servers. Additional protocols can be enabled by setting the ${PREFIX}_SECUREPROTOCOLS variable to a comma separated list of protocol names as defined in the vert.x documentation. However, great care should be taken when enabling older protocols because most of them are vulnerable to attacks.

Address rewriting

In some multi-tenant messaging environments external can have their addresses internally mapped to enforce consistent name spaces. For example, the addresses can be prefixed by the virtual host the client uses to connect or some other internal identifier. So address like telemetry/DEFAULT_TENANT would be internally represented as test-vhost/telemetry/DEFAULT_TENANT for example.

To successfully address those external clients, infrastructure Hono components need to apply the same mapping rules. The client factory can be configured to automatically rewrite addresses when opening links to the AMQP network. The ${PREFIX}_ADDRESSREWRITERULE variable contains rewrite rule for addresses based on the regular expressions.

The rule is defined in the "$PATTERN $REPLACEMENT" format, where the pattern and replacement use the standard Java regular expression syntax. The pattern should match the address or otherwise the original address will be used.

For example, setting HONO_ADDRESSREWRITERULE to ([a-z_]+)/([\\w-]+) test-vhost/$1/$2 would result in adding the test-vhost/ prefix to all addresses used by the client.