HTTP Adapter Configuration

The HTTP protocol adapter exposes HTTP based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command & Control APIs.

The adapter 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.

Service Configuration

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

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:

• Common Java VM Options
• Common vert.x Options
• Common Protocol Adapter Options
• Monitoring Options

Port Configuration

The HTTP protocol adapter 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 HTTP protocol adapter will fail to start if none of the ports is configured properly.

Secure Port Only

The protocol adapter 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_HTTP_KEYSTOREPATH and the HONO_HTTP_KEYSTOREPASSWORD variables in order to load the key & certificate from a password protected key store, or
2. setting the HONO_HTTP_KEYPATH and HONO_HTTP_CERTPATH variables in order to load the key and certificate from two separate PEM files in PKCS8 format.

When starting up, the protocol adapter will bind a TLS secured socket to the default secure port 8443. The port number can also be set explicitly using the HONO_HTTP_PORT variable.

The HONO_HTTP_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 0.0.0.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_HTTP_INSECUREPORT to a valid port number, or by
• implicitly configuring the default port (8080) by simply setting HONO_HTTP_INSECUREPORTENABLED to true.

The protocol adapter issues a warning on the console if HONO_HTTP_INSECUREPORT is set to the default secure HTTP port (8443).

The HONO_HTTP_INSECUREPORTBINDADDRESS 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 0.0.0.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

The protocol adapter may be configured to open both a secure and a non-secure port at the same time simply by configuring both ports as described above. For this to work, both ports must be configured to use different port numbers, otherwise startup will fail.

Ephemeral Ports

Both the secure as well as the insecure port numbers may be explicitly set to 0. The protocol adapter will then use arbitrary (unused) port numbers determined by the operating system during startup.